Skip to content

Configurable Inputs

Currently available in beta

Admin Dashboard is currently available in beta, which means some of the features, specifications, and details provided herein are subject to change. We recommend checking back regularly for the most up-to-date information and viewing our roadmap in regard to the general availability release.

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,
                ],
            ],
        ],
    ];
}

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.

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,
                ],
            ],
        ],
    ];
}

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.',
        ],
    ];
}

Examples

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.',
                ],
            ],
        ],
    ];
}

Note

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.

Custom Input Types

While a set of input elements are provided out-of-the-box, it is certainly feasible for developers to want to create their own custom input types to better suit the needs of their widgets and/or admin users. This brief example covers the steps required to implement a custom input type and provide an explanation as to how Magento maps the array to the final frontend output.

  1. Add a new child block to the widget-form.inputs block in adminhtml_dashboard_index.xml. 
    <referenceBlock name="widget-form.inputs">
    <!-- Replace the {{TYPE}} suffix with the custom type name -->
    <block name="input.{{TYPE}}" template="Vendor_Module::path/to/the/input/template.phtml"/>
</referenceBlock>
  2. Create the template file to handle the rendering of the custom input type.
    • The input name is available from the block via $block->getData('input_name') or $block->getInputName() and contains the value specified for the label
    • The input configuration is available from the block via $block->getData('input_config') or $block->getInputConfig()
  3. Use the custom input type name when defining the input type in the widget's PHP class. 
    public function get{{Configurable|Display}}Properties(): array
{
    return [
        'foo' => [
            'label' => 'Custom Input Type',
            'input' => [
                'type' => '{{TYPE}}',
            ],
        ],
    ];
}

Input Type Names

When creating a custom input type, the name of the block defined in layout XML must match the pattern input.{{TYPE}} in order for Magento to be able to automatically handle the rendering of the input template. Whichever value is used to replace the {{TYPE}} placeholder must also be used when specifying the type in the widget's get{{Configurable|Display}}Properties() functions.