Commonly, you may encounter the options, optionsMethod or optionsPreset property, this article describes in more detail how to configure options.
The options property should specify the options directly as part of the definition as a key-value pair, where the value and label are independently specified.
options:
draft: Draft
published: Published
archived: ArchivedThe keys can be integers with their label.
options:
1: Simple
2: ComplexIn addition to a simple arrays, some fields such as radio lists support specifying a description as part of their options values. This is where the value is defined as another array with the syntax key: [label, description].
options:
all: [All, Guests and customers will be able to access this page.]
registered: [Registered only, Only logged in member will be able to access this page.]
guests: [Guests only, Only guest users will be able to access this page.]Other fields, such as dropdown fields support specifying an icon, image or color as part of their options values. If the second item in the array starts with a # then it is considered a color, and if the value contains a . then it is considered an image, otherwise it is considered an icon class.
options:
red: [Color, '#ff0000']
icon: [Icon, 'oc-icon-calendar']
image: [Image, '/path/to/image.png']The optionsPreset property specifies a preset code that can be used to request the available options.
optionsPreset: iconsThe following presets are available:
| Preset | Description |
|---|---|
| icons | Lists available icon names (eg: icon-calendar) |
| phosphorIcons | Lists available icon names (eg: ph ph-calendar) |
| locales | Lists available locales (eg: en-au) |
| flags | Lists locales with their icons as flags (eg: [en-au, flag-au]) |
| timezones | Lists available timezones (eg: Australia/Sydney) |
The optionsMethod property specifies a callable PHP method that can be used to request the available options. Typically the method name will refer to a method local to the associated model.
optionsMethod: getMyOptionsFromModelThe method name can also be a static method on any object.
optionsMethod: MyAuthor\MyPlugin\Helpers\FormHelper::getMyStaticMethodOptionsInside the method, an detailed definition can be used to specify more advanced options, such as setting individual attributes for each option. A detailed definition is identified by its associated array structure.
public function getDetailedFieldOptions()
{
return [
1 => [
'label' => 'Option 1',
'comment' => 'This is option one'
],
2 => [
'label' => 'Option 2',
'comment' => 'This is option two',
'disabled' => true
]
];
}The following properties are supported where possible:
| Property | Description |
|---|---|
| label | a name when displaying the option to the user. |
| comment | places a descriptive comment below the option label. |
| readOnly | specifies if the option is read-only or not. |
| disabled | specifies if the option is disabled or not. |
| hidden | defines the option without ever displaying it. |
| color | defines a status indicator color for the option as a hex color (dropdown) |
| icon | specifies an icon name for this option (dropdown) |
| image | specifies an image URL for this option (dropdown) |
| optgroup | set to true if the children should belong to an option group structure, default: false (dropdown) |
| children | specifies child options as another array for a nested structure (checkbox list) |
Use the children property if the option definition supports nesting. Generally, this will display a structure for checkbox lists and implement an option group for dropdowns.
public function getDetailedFieldOptions()
{
return [
1 => [
'label' => 'Option 1',
'comment' => 'This is option one',
'children' => [
2 => [
'label' => 'Option 2',
'comment' => 'This is option two',
],
// ...
]
],
];
}