Widget XML Configuration

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.

Widgets are defined in a module's etc/adminhtml/dashboard_widget.xml file. The snippet below shows a minimally configured widget.

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Hyva_AdminDashboardFramework:etc/adminhtml/dashboard_widget.xsd">
    <widget id="my_widget">
        <class>Vendor\Module\Model\Widget\MyWidget</class>
        <display_type>text</display_type>
    </widget>
</config>

Widget Attributes

The following attributes may be used when defining the <widget> XML node:

• id*
• disabled

* required

id

As the name suggests, the widget id attribute is used to uniquely identify each widget type. The value of this attribute must be a non-empty alphanumeric string whose permitted special characters include hyphens "-", underscores "_", and periods ".". This attribute is required.

disabled

The disabled attribute is used to enable or disable the widget. Disabling a widget means admin users cannot create, edit, or delete instances of the widget and existing instances of the given type will not be rendered. This is an optional attribute which defaults to a value of false when omitted.

Widget Arguments

There are a number of arguments that can be supplied to the <widget> XML node:

• acl
• category
• class*
• display_type*
• icon
• min_height
• min_width
• tags
• template
• title

* required

acl

The <acl> argument is optional and can be used to restrict the widget to a subset of admin users. Admin users that do not have access to the defined resource will not be able to create, edit, delete, or view the widget. If a widget does not define an <acl> then the default Magento_Backend::admin resource is used. The default ACL resource can be changed by setting the Hyva\AdminDashboardFramework\Model\Config\Widget\Converter class's defaultAclRole argument via di.xml.

category

The <category> argument is optional and can be used to categorise widgets. Widgets with the same <category> value are grouped together in the new widget instance creation modal. Uncategorised widgets are grouped into an Other category, which is appended to the list of defined <category> values. The default <category> name can be changed by setting the Hyva\AdminDashboardFramework\Model\Config\Widget\Converter class's defaultCategoryName argument via di.xml.

class

The <class> argument is required and defines which PHP class is responsible for implementing the behaviour of the widget. More information about this class can be found in the PHP Implementation documentation.

Warning

An exception will be thrown if the specified class does not implement Hyva\AdminDashboardFramework\Model\WidgetType\WidgetTypeInterface somewhere in its class hierarchy.

display_type

The <display_type> argument is required and determines which template is used to display the widget once the admin user has added it to their dashboard. The Hyva\AdminDashboardFramework\Model\Config\Widget\Converter class is responsible for mapping display types to templates and this is achieved by configuring its displayTypeTemplateMap property via di.xml, where the item name is the display type and the item value is the Magento template responsible for rendering it.

Warning

Magento will throw an exception if the <display_type> argument is set to be template but no <template> argument is present. The same is true if any other <display_type> value is used without it also having an entry in the Hyva\AdminDashboardFramework\Model\Config\Widget\Converter class's displayTypeTemplateMap.

icon

The <icon> argument is optional and can be used to assign an icon to the widget. The icon is displayed with the widget in the new widget instance creation modal. No icon is displayed when no <icon> value is specified.

Note

The value of this argument must match the name of an icon available to the Hyva\Theme\ViewModel\LucideIcons view model. This will typically be any of the icons documented here.

min_height

The <min_height> argument is optional and can be used to specify the minimum number of rows the widget should occupy in the dashboard. Admin users will not be able to resize their widget instances to a height smaller than the value specified. The default value is 1.

min_width

The <min_width> argument is optional and can be used to specify the minimum number of columns the widget should occupy in the dashboard. Admin users will not be able to resize their widget instances to a width smaller than the value specified. The default value is 1.

tags

The <tags> argument is optional and allows developers to provide a comma-separated list of keywords related to the widget. These values are considered when the admin user utilises the widget search function.

template

The <template> argument is optional and allows developers to define a custom template for the widget in cases where none of the standard display types are suitable. The value of this argument must follow Magento's standard template naming convention e.g. Vendor_Module::path/to/template.phtml.

title

The <title> argument is optional and simply provides a user-friendly name for the widget. If no <title> is given the widget will default to using its id value in its place - replacing special characters with spaces and capitalising each word.

XML Validation

The XSD that validates these files can be found in the etc/adminhtml/dashboard_widget.xsd file in the Hyva_AdminDashboardFramework module.