Document allowCustom

Replaces #14. Documents wintercms/winter@bb79834

backend/forms.md

@@ -393,6 +393,43 @@ status:
     showSearch: false
 ```
 
+Dropdowns can also allow users to provide a new value. This can be activated by setting the `allowCustom` option to `true`.
+
+    status:
+        label: Blog Post Status
+        type: dropdown
+        allowCustom: true
+
+The `allowCustom` option can be useful to provide a preset list of options without preventing the user from adding a new or custom value. 
+
+When using the `get*Options` method for defining options, you would be able to take into consideration any custom options present in the data:
+
+```yaml
+status:
+    label: Blog Post Status
+    type: dropdown
+    allowCustom: true
+```
+
+```php
+public function getStatusOptions($value, $formData)
+{
+    // Prefill the dropdown with the already used statuses: [['status' => 'draft'], ['status' => 'published']]
+    $statuses = self::distinct('status')->get();
+
+    // Insert the actual form's model value to avoid it to vanish
+    // on eventual AJAX call that would refresh the field partial like dependsOn
+    if ($this->status) {
+    
+        // The actual form's status could be a custom like ['status' => 'need review']
+        $statuses->add(['status' => $this->status]);
+    }
+
+    // Return a list of statuses: [['status' => 'draft'], ['status' => 'published'], ['status' => 'need review']]
+    return $statuses->pluck('status', 'status');
+}
+```
+
 ### Email
 
 `email` - renders a single line text box with the type of `email`, triggering an email-specialised keyboard in mobile browsers.