Dropdown Toggle

Description

The dropdown_toggle field type creates a dynamic select menu in the admin panel that toggles the visibility of additional fields based on the selected option. It is rendered as an HTML <select> element styled with Bootstrap’s form-select class, followed by conditionally displayed sub-fields. This field is ideal for scenarios where different settings are needed depending on a user’s choice, such as environment-specific configurations (e.g., production vs. development).

Available Options

Parameter Type Description Required Default
name String The name of the field, used as the identifier and default label if label is not provided. Yes –
type String The field type. Must be set to dropdown_toggle. Yes –
label String The display label for the dropdown field. If not provided, the name is used. No name
options Array An associative array where keys are the dropdown options (strings) and values are arrays of sub-field configurations. Each sub-field follows the standard field structure (e.g., name, type). Yes –
default String/Boolean The default selected option. Must match one of the options keys if provided. If set to false, no option is selected by default. No false
class String Additional CSS classes to apply to the dropdown for custom styling or JavaScript targeting. No –
help String A help message displayed in a sidebar or tooltip when the user clicks the info icon next to the dropdown. No –
required Boolean If true, the dropdown is marked as required, adding the HTML required attribute. No false


Note: The dropdown_toggle field stores the selected option in the settings array as a sanitized string, using WordPress’s sanitize_text_field function. Sub-fields are stored separately under the same section, following their respective sanitization rules.

Example

Below is an example of how to define a dropdown_toggle field in the $fields array for the Reusable Admin Panel settings class.

$this->fields = array(
    'api' => array(
        array(
            'name'    => __('Environment', 'your-plugin-slug'),
            'type'    => 'dropdown_toggle',
            'label'   => __('API Environment', 'your-plugin-slug'),
            'options' => array(
                'Production' => array(
                    array(
                        'name'  => __('Production API Key', 'your-plugin-slug'),
                        'type'  => 'text',
                        'label' => __('Production API Key', 'your-plugin-slug'),
                        'help'  => __('Enter the API key for production.', 'your-plugin-slug')
                    )
                ),
                'Development' => array(
                    array(
                        'name'  => __('Development API Key', 'your-plugin-slug'),
                        'type'  => 'text',
                        'label' => __('Development API Key', 'your-plugin-slug'),
                        'help'  => __('Enter the API key for development.', 'your-plugin-slug')
                    )
                )
            ),
            'default' => 'Production',
            'class'   => 'environment-selector',
            'help'    => __('Select the API environment.', 'your-plugin-slug'),
            'required' => true
        )
    )
);

This configuration will create a dropdown toggle field labeled “API Environment” under the “api” section. It offers two options (Production and Development), each revealing a text field for an API key when selected. The dropdown defaults to Production, includes the CSS class environment-selector, displays a help message, and is marked as required.

Usage Notes

  • The dropdown_toggle field uses WordPress’s sanitize_text_field for sanitizing the selected option, ensuring a safe string. Sub-fields are sanitized according to their respective types (e.g., text uses sanitize_text_field).
  • The dropdown’s ID is automatically generated as {section}-{name}, where name is sanitized using sanitize_title. Sub-fields follow the same ID convention.
  • The field is styled using Bootstrap’s form-select class, with sub-fields wrapped in a togglable div styled by option-specific classes (e.g., production, development). Custom styles can be applied via the class parameter.
  • A placeholder option matching the label is included by default, which is disabled and selected if no default is set. This option has an empty value and does not persist upon saving.
  • The required attribute ensures a valid option is selected, triggering browser validation.
  • Sub-fields are displayed or hidden dynamically based on the selected option, using CSS classes derived from the option keys (lowercased).
  • To retrieve the value of the dropdown, use the get_option method, e.g., $this->get_option('api', 'environment'). Sub-field values are retrieved similarly, e.g., $this->get_option('api', 'production-api-key').