Skip to main content
Version: main (4.5)

Choice Dropdown

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.
  2. Add options and any extra information to the choicelist instance.
  3. Add the choicedropdown form field to the form, passing the choicelist instance.
// 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);