Skip to content

Configurable Inputs

Admin users typically have two avenues to configure widgets: configurable properties and display properties. In both cases, developers need to be able to define an array of options to present to the admin user so they can configure the widget to their needs. These sets of options are handled by the widget type's getConfigurableProperties() and getDisplayProperties() functions respectively.

Input Fields

There are a number of input field types available for developers to choose from:

Field Definition Structure

Developers must ensure they follow a particular pattern when defining input fields for their widget configuration. The code snippet below illustrates the generic pattern but each keyword and input type is documented in further detail in later sections.

public function get{{Configurable|Display}}Properties(): array
{
    return [
        'input_name' => [
            'label' => __('My Awesome Input Label'),
            'note' => __('Some helper text to display beneath the input element.'),
            'input' => [
                'type' => 'select',
                'options' => [
                    [
                        'label' => 'Foo',
                        'value' => 'foo',
                    ],
                    [
                        'label' => 'Bar',
                        'value' => 'bar',
                    ],
                ],
                'attributes' => [
                    'required' => true,
                ],
                'depends' => [
                    '{{configurable|display}}_properties[input_name]' => 0,
                ],
            ],
        ],
        'second_input' => [...],
    ];
}

Names

The keys of the array returned by these functions are used as the name attribute for the <input> element rendered on the frontend.

Labels

The label entry is used to populate the <label> element for the input.

Input Definition

The input array is used to configure the input element, including its:

Types

The type element is used to define which input type is used for the configuration option e.g. text, select, date etc.

Subtypes

The subtype element is used in conjunction with text types to define more specific types such as email, url, tel etc. and in conjunction with select types to define whether the input is a multiselect input or not.

Options

The options element is used in conjunction with select types to define the list of available values. The value of this element is a nested array where each child array contains a pair of labels and values - just like Magento's source model classes.

Groups

The groups element is used in conjunction with select types to define option groups. Each group is an array consisting of a label and a set of options.

Attributes

The attributes element is used as a "catch all" array that contains a set of attribute => value pairs that are mapped onto the input element during rendering. This array is typically used to mark fields as being required or to enforce additional HTML validation attributes such as maxlength or minlength etc.

Additionally, because it simply adds the attribute/value pair to the <input> element, it can be used to add any other relevant HTML attributes, custom data- attributes, AlpineJS bindings etc.

Tip

The Hyva\AdminDashboardFramework\ViewModel\Widget::renderHtmlAttributes() function is responsible for generating the output for these HTML attributes.

Inputs

The inputs element is used in conjunction with the dynamic-rows input type. The value of this element is a nested array of other input fields.

Dependencies

The depends element is used to define one or more dependencies on other input values held by the currently configured widget. The keys of this array use array notation to target other display or configurable properties while their values specify the value required in order to display the associated input.

Our own Google CrUX History widget utilises this to display its configurable URL property when the Use Custom URL toggle is disabled and display its Store View property when it is enabled.

[
    'url_type' => [...],
    'store_id' => [
        'label' => __('Store View'),
        'input' => [
            ...
            'depends' => [
                'configurable_properties[url_type]' => 0,
            ],
        ],
    ],
    'url' => [
        'label' => __('URL'),
        'input' => [
            ...
            'depends' => [
                'configurable_properties[url_type]' => 1,
            ],
        ],
    ],
]

Defining Multiple Dependencies

When defining multiple dependencies, ALL of the dependant criteria must be satisfied in order for the field to show.

Dependency Values

Dependency values are currently evaluated based on equality, meaning that the dependant field's value must match in order for the field to show.

Input Type: Date

  • Type: date

This input type provides the admin user with the HTML date picker element.

Code Sample 
public function get{{Configurable|Display}}Properties(): array
{
    return [
        'foo' => [
            'label' => 'Date of Birth',
            'input' => [
                'type' => 'date',
            ],
        ],
    ];
}

Input Type: Dynamic Rows

  • Type: dynamic-rows

This input type provides the admin user with a set of dynamic rows, much like the traditional Magento 2 dynamic rows UI component. Each of the defined child inputs are grouped in a row and the admin user has the ability to add or remove rows as required.

Code Sample 
public function get{{Configurable|Display}}Properties(): array
{
    return [
        'foo' => [
            'label' => '',
            'input' => [
                'type' => 'dynamic-rows',
                'inputs' => [
                    'name' => [
                        'label' => 'Product Name',
                        'input' => [
                            'type' => 'text',
                        ],
                    ],
                    'description' => [
                        'label' => 'Product Description',
                        'input' => [
                            'type' => 'textarea',
                        ],
                    ],
                ],
            ],
        ],
    ];
}

Input Type: Select

  • Type: select

This input type provides the admin user with the HTML <select> input. This single input can also be configured to use option groups and multiselect inputs.

Code Sample 
public function get{{Configurable|Display}}Properties(): array
{
    return [
        'foo' => [
            'label' => 'Please Choose',
            'input' => [
                'type' => 'select',
                'subtype' => 'multiselect',
                'groups' => [
                    [
                        'label' => 'Group One',
                        'options' => $this->yesNoSourceModel->toOptionArray(),
                    ],
                    [
                        'label' => 'Group Two',
                        'options' => [
                            [
                                'label' => 'One',
                                'value' => 1,
                            ],
                            [
                                'label' => 'Two',
                                'value' => 2,
                            ],
                            [
                                'label' => 'Three',
                                'value' => 3,
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ];
}

Input Type: Store Scope Selector

  • Type: scope

This input type provides the admin user with a multiselect input displaying the various store views available within the Magento application, grouped by both website and store.

Code Sample 
public function get{{Configurable|Display}}Properties(): array
{
    return [
        'store_ids' => [
            'label' => 'Store Views',
            'input' => [
                'type' => 'scope',
            ],
        ],
    ];
}

Input Type: Template

  • Type: template

This input type allows the developer to provide a custom template for their input, providing them with finer control.

Code Sample 
public function get{{Configurable|Display}}Properties(): array
{
    return [
        'foo' => [
            'input' => [
                'type' => 'template',
                'template' => 'Vendor_Module::path/to/template.phtml',
            ],
        ],
    ];
}

Input Type: Text

  • Type: text

This input type provides the admin user with a simple text input. The subtype value can be used to specify more specific text-based inputs such as email, url, number etc.

Code Sample 
public function get{{Configurable|Display}}Properties(): array
{
    return [
        'foo' => [
            'label' => 'Email Address',
            'input' => [
                'type' => 'text',
                'subtype' => 'email',
            ],
        ],
    ];
}

Input Type: Text Area

  • Type: textarea

This input type provides the admin user with textarea input.

Code Sample 
public function get{{Configurable|Display}}Properties(): array
{
    return [
        'foo' => [
            'label' => 'Description',
            'input' => [
                'type' => 'textarea',
                'attributes' => [
                    'rows' => 5,
                    'cols' => 50,
                ],
            ],
        ],
    ];
}

Input Type: Toggle

  • Type: toggle

This input type provides the admin user with a simple toggle switch.

Code Sample 
public function get{{Configurable|Display}}Properties(): array
{
    return [
        'foo' => [
            'label' => 'Use Custom Value',
            'input' => [
                'type' => 'toggle',
            ],
        ],
    ];
}

Field Notes

Sometimes developers may wish to provide admin users with some additional information or instructions for their input fields. This can be achieved using the note entry of their field definition array.

Code Sample 
public function get{{Configurable|Display}}Properties(): array
{
    return [
        'foo' => [
            'label' => 'Description',
            'input' => [
                'type' => 'textarea',
            ],
            'note' => 'HTML formatting is not supported.',
        ],
    ];
}

Using HTML in Notes

The input.note block takes a list of permitted HTML tags as an argument in the hyva_dashboard_widget layout handle. The <a> and <br> tags are allowed by default. Other tags can be allowed by adding them to the block's allowed_note_tags array - using the array key to define the tag name and the value as a flag for whether to allow its inclusion or not.

Setting Default Input Values

Setting a default value for an input is achieved by simply defining the value attribute inside the attributes array.

public function get{{Configurable|Display}}Properties(): array
{
    return [
        'foo' => [
            'label' => 'Foo',
            'input' => [
                'type' => 'text',
                'attributes' => [
                    'value' => 'Some default value.',
                ],
            ],
        ],
    ];
}

Special Cases

In cases where the HTML input types do not support the value attribute, such as select and textarea, no special care needs to be taken as their templates handle this input configuration appropriately for their respective input type.

Additionally, when using toggle inputs, the checked attribute is used to determine whether the option is selected by default or not.