-
Notifications
You must be signed in to change notification settings - Fork 301
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[docs] Describe choicedropdown form field
- Loading branch information
1 parent
f9f6094
commit e34bd55
Showing
3 changed files
with
64 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
label: Form fields |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,61 @@ | ||
# Choice Dropdown Form Field (`choicedropdown`) | ||
|
||
The `choicedropdown` form field creates a dropdown list with multiple options. It is different from a | ||
standard select dropdown in that each option can have extra icons and descriptions. This field is often | ||
used in forms to facilitate the selection of a non-trivial option that demands additional information. | ||
|
||
## Using the `choicedropdown` Form Field | ||
|
||
While most form API fields use primitive data types, the `choicedropdown` form field uses a particular | ||
data definition called `choicelist`. This data definition is an abstraction that represents a user | ||
choice list and is used in other UI components like `core\output\local\dropdown\status` | ||
or `core\output\local\action_menu\subpanel`. | ||
|
||
The `choicelist` class provides a way to define a list of options with additional information such as icons, | ||
descriptions, the currently selected option, or the ability to disable specific options. | ||
|
||
## Example Usage | ||
|
||
To create a `choicedropdown` form field, you need to: | ||
|
||
1. Create a new instance of the `choicelist` class. | ||
1. Add options and any extra information to the `choicelist` instance. | ||
1. Add the `choicedropdown` form field to the form, passing the `choicelist` instance. | ||
|
||
```php | ||
// Define the options for the dropdown list. | ||
$options = new core\output\choicelist(); | ||
$options->add_option( | ||
'option1', | ||
"Text option 1", | ||
[ | ||
'description' => 'Option 1 description', | ||
'icon' => new pix_icon('t/hide', 'Eye icon 1'), | ||
] | ||
); | ||
$options->add_option( | ||
'option2', | ||
"Text option 2", | ||
[ | ||
'description' => 'Option 2 description', | ||
'icon' => new pix_icon('t/stealth', 'Eye icon 2'), | ||
] | ||
); | ||
$options->add_option( | ||
'option3', | ||
"Text option 3", | ||
[ | ||
'description' => 'Option 3 description', | ||
'icon' => new pix_icon('t/show', 'Eye icon 3'), | ||
] | ||
); | ||
|
||
// Add the choicedropdown field to the form. | ||
$mform->addElement( | ||
'choicedropdown', | ||
'FIELDNAME', | ||
get_string('FIELDNAME', 'PLUGINNAME'), | ||
$options, | ||
); | ||
$mform->setDefault('FIELDNAME', $defaultvalue); | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters