diff --git a/backend/forms.md b/backend/forms.md index 7bb51bc5..aa7ca936 100644 --- a/backend/forms.md +++ b/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.