Skip to content

Tutorials

Creating a dashboard widget type requires two steps: defining the widget via XML and implementing the widget behaviors in PHP. The tutorials below cover additional customization scenarios once you have a working widget type.

Customizing the Widget Menu

Customizing Menus for Specific Widget Types

The examples given below apply the changes to all widget types. In cases where the changes should only apply to widgets of a specific type, use the hyva_dashboard_widget_instance_{{WIDGET_TYPE_ID}} handle instead.

Removing Menu Items

  1. Create the hyva_dashboard_widget_instance.xml layout file
  2. Reference the specific menu item block and set the remove attribute to true
<?xml version="1.0"?>
<page
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd"
>
    <body>
        <referenceBlock name="widget-instance.menu.foo" remove="true"/>
    </body>
</page>

Adding Menu Items

  1. Create the hyva_dashboard_widget_instance.xml layout file
  2. Add a new block to the widget-instance.menu block
<?xml version="1.0"?>
<page
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd"
>
    <body>
        <referenceBlock name="widget-instance.menu">
            <block name="foo" template="Vendor_Module::path/to/foo.phtml"/>
        </referenceBlock>
    </body>
</page>

Reordering Menu Items

  1. Create the hyva_dashboard_widget_instance.xml layout file
  2. Reference the specific menu item block(s) and use the before and/or after attributes to reposition them
<?xml version="1.0"?>
<page
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd"
>
    <body>
        <referenceBlock name="widget-instance.menu.foo" before="widget-instance.menu.bar"/>
    </body>
</page>

Creating Custom Configurable Inputs

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.

  1. Add a new child block to the widget-form.inputs block in hyva_dashboard_widget.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 widget type object is available from the block via $block->getData('widget') or $block->getWidget()
    • The widget instance object is available from the block via $block->getData('widget_instance') or $block->getWidgetInstance()
      • The widget instance object will be null when the input is not associated with a particular widget instance
    • 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()
    • The input ID is available from the block via $block->getData('input_id') or $block->getInputId()
  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.

Dynamic Row Inputs

In some instances it may also be necessary to handle inputs differently when they are rendered as part of a dynamic row input. In these cases the block name used in layout XML should follow the pattern input.dynamic-rows.{{TYPE}}.

Managing Widget Categories

Widget categories group the widgets shown in the Hyvä Admin Dashboard widget menu. You manage them by configuring the Hyva\AdminDashboardFramework\Model\Config\Widget\Converter class through etc/di.xml. This section covers adding, removing, reordering, and renaming categories, plus changing the default.

Adding New Categories

To add a category, define a new <item> in the converter's categoryNames argument. The item name is the value you reference from hyva_dashboard_widget.xml, and each category carries an enabled flag, a label, and a sortOrder:

<type name="Hyva\AdminDashboardFramework\Model\Config\Widget\Converter">
    <arguments>
        <argument name="categoryNames" xsi:type="array">
            <!-- The item name is the value used in the hyva_dashboard_widget.xml configuration -->
            <item name="foo" xsi:type="array">
                <item name="enabled" xsi:type="boolean">true</item>
                <item name="label" xsi:type="string">Foo</item>
                <item name="sortOrder" xsi:type="number">500</item>
            </item>
        </argument>
    </arguments>
</type>

Removing Categories

To remove a category, set its enabled flag to false. You only need to specify the flag you are changing; the rest of the category definition is inherited:

<type name="Hyva\AdminDashboardFramework\Model\Config\Widget\Converter">
    <arguments>
        <argument name="categoryNames" xsi:type="array">
            <item name="sales" xsi:type="array">
                <item name="enabled" xsi:type="boolean">false</item>
            </item>
        </argument>
    </arguments>
</type>

Reordering Categories

To move a category, change its sortOrder to a number before, after, or between the sortOrder values of the other categories. Lower numbers appear first:

<type name="Hyva\AdminDashboardFramework\Model\Config\Widget\Converter">
    <arguments>
        <argument name="categoryNames" xsi:type="array">
            <item name="catalog" xsi:type="array">
                <item name="sortOrder" xsi:type="number">1</item>
            </item>
        </argument>
    </arguments>
</type>

Updating Category Names

To rename a category, change its label value:

<type name="Hyva\AdminDashboardFramework\Model\Config\Widget\Converter">
    <arguments>
        <argument name="categoryNames" xsi:type="array">
            <item name="system" xsi:type="array">
                <item name="label" xsi:type="string">Configuration</item>
            </item>
        </argument>
    </arguments>
</type>

Info

Category names are translated in the relevant template(s), so there is no need to update a category name just to translate it.

Changing the Default Category

To change which category is selected by default, update the defaultCategoryName argument to the name of the new default category:

<type name="Hyva\AdminDashboardFramework\Model\Config\Widget\Converter">
    <arguments>
        <argument name="defaultCategoryName" xsi:type="string">foo</argument>
    </arguments>
</type>

Warning

The default category MUST be enabled.