Skip to content

Widget Layout XML

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.

The admin dashboard framework provides a custom layout handle: hyva_dashboard_widget.xml. This layout handle contains all the <container> and <block> definitions required for adding a widget dashboard to an admin page.

Info

The core adminhtml_dashboard_index.xml layout handle is also used by the admin dashboard module to populate the toolbar and provide the necessary AlpineJS components for the toolbar elements on the dashboard page.

Containers

Only a single <container> is currently defined and it has the name widget-container. This container essentially serves as a "wrapper" for all other widget-related layout elements.

Tip

More information about Magento <container> elements can be found in the official documentation.

Blocks

Tip

More information about Magento <block> elements can be found in the official documentation.

Pseudo-Containers

Due to the fact we cannot use the ifconfig attribute in conjunction with <container> elements to exert conditional control over the inclusion of layout elements, a set of 3 blocks dubbed "pseudo-containers" have been created to serve this purpose - leveraging the same ifconfig attribute to ensure widget-related content is only output when the appropriate system configuration value is set.

widget-container.before

This block displays content before the main widget content area. The admin dashboard framework uses this block to render the various widget configuration form input blocks.

widget-container.content

This block houses the main widget content area, including the dashboard that houses the widget instances, the widget instances, their menus, and their respective configuration forms.

widget-container.after

This block displays content after the main widget content area. The admin dashboard modules use this block to render their various AlpineJS component templates.

Custom Widget Instance Blocks

On some occasions it may be pertinent to use custom widget instance templates for a subset of widget types. In order to simplify this type of implementation, improve extensibility, and reduce the maintenance burden involved when overriding templates, the admin dashboard framework provides an easy block-based solution via the hyva_dashboard_widget layout handle.

The example below illustrates how this could be done for the Conversion Rate widget type.

Warning

A degree of caution is advised when opting to use custom widget instance blocks as you then become responsible for all aspects of its rendering - including its menu, configuration form, and any other child blocks the admin dashboard framework may add at a later date.

Tip

Your custom block will receive the widget instance object as a data argument. This is available through the usual block functions: $block->getData('widget_instance') and $block->getWidgetInstance().

Info

For the curious, the following locations are responsible for locating custom widget instance blocks:

  • The foreach loop found towards the bottom of Hyva_AdminDashboardFramework::widget/container.phtml

  • Hyva\AdminDashboardFramework\Util\Widget\Instance\Content::getSkeletonBlock()

1. Create the Layout XML Boilerplate

<?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-container.content">
            ...
        </referenceBlock>
    </body>
</page>

Note

While the example above defines the new <block> as a child of the widget-container.content pseudo-container, this is merely by convention. The code responsible for utilising custom widget instance blocks will actually consider the entire hyva_dashboard_widget layout handle when searching for the custom block.

2. Define the Custom Block

<referenceBlock name="widget-container.content">
    <block name="widget-instance.conversion_rate"
           template="Vendor_Module::path/to/template.phtml">
        <!-- Continue using default menu and config form blocks -->
        <block name="widget-instance.menu"
               template="Hyva_AdminDashboardFramework::widget/menu.phtml"/>
        <block name="widget-instance.config-form"
               template="Hyva_AdminDashboardFramework::widget/form/configure.phtml"/>

        <!-- New blocks specific for this customisation -->
        <block name="example" template="Vendor_Module::example.phtml">
            <block name="example.child" template="Vendor_Module::example/child.phtml">
                <arguments>
                    <argument name="is_awesome" xsi:type="boolean">true</argument>
                    <argument name="misc_data" xsi:type="array">
                        <item name="foo" xsi:type="string">foo</item>
                        <item name="bar" xsi:type="string">bar</item>
                    </argument>
                </arguments>
            </block>
        </block>
    </block>
</referenceBlock>

Block Names

Your block name MUST match the format widget-instance.{{WIDGET_TYPE_ID}} in order for it to be loaded.