Skip to content

Configurable Inputs

Widget configuration in the Hyvä Admin Dashboard is driven by two sets of input fields: configurable properties and display properties. Developers define these as arrays of options presented to the admin user, returned from the widget type's getConfigurableProperties() and getDisplayProperties() methods respectively. This page documents the field definition structure and every input field type you can use to let admin users configure a widget to their needs.

Input Fields

The Hyvä Admin Dashboard provides a range of input field types you can use in widget configuration:

Field Definition Structure

Every widget input field follows a particular definition pattern inside getConfigurableProperties() or getDisplayProperties(). The code snippet below illustrates the generic pattern. Each keyword and input type is documented in further detail in the sections that follow.

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 getConfigurableProperties() and getDisplayProperties() 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 configures the input element itself. It supports the following keys:

Types

The type element defines which input type is used for the configuration option, for example text, select, date, and so on.

Subtypes

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

Options

The options element is used together with select types to define the list of available values. Its value is a nested array where each child array contains a pair of label and value entries, just like Magento's source model classes.

Groups

The groups element is used together 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 a "catch all" array of attribute => value pairs that are mapped onto the input element during rendering. This array is typically used to mark fields as required or to enforce additional HTML validation attributes such as maxlength or minlength.

Because it simply adds the attribute/value pair to the <input> element, attributes can also add any other relevant HTML attributes, custom data- attributes, Alpine.js bindings, and so on.

Tip

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

Inputs

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

Dependencies

The depends element defines 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 uses this to display its configurable URL property when the Use Custom URL toggle is disabled, and to display its Store View property when the toggle 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

The date 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

The dynamic-rows 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 is grouped in a row, and the admin user can 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

The select 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

The scope 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

The template input type lets you provide a custom template for your input, giving you finer control over how it renders.

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

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

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

The textarea input type provides the admin user with a 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

The toggle 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 you may want to give admin users additional information or instructions for their input fields. Add this with the note entry of the 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

Set a default value for an input by 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. Their templates handle this input configuration appropriately for their respective input type.

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