Skip to content

Widget XML Configuration

Every Hyvä admin dashboard widget type is declared in XML before its PHP class does any work. You define widgets in a module's etc/adminhtml/hyva_dashboard_widget.xml file, where each <widget> node sets the widget's ID, its PHP implementation class, how it displays, and optional behavior such as caching, access control, and categorization.

Minimal Widget Definition

The snippet below shows a minimally configured widget. It sets a unique id, points at the PHP <class> that implements the widget, and picks a <display_type> that determines the rendering template.

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

Widget Attributes

The <widget> XML node accepts the following attributes. The id attribute is required; disabled is optional.

* required

id

The widget id attribute uniquely identifies each widget type. Its value must be a non-empty alphanumeric string, whose permitted special characters are hyphens (-), underscores (_), and periods (.). This attribute is required.

disabled

The disabled attribute enables or disables the widget. Disabling a widget means admin users cannot create, edit, or delete instances of it, and existing instances of that type will not be rendered. This attribute is optional and defaults to false when omitted.

Widget Arguments

Beyond its attributes, the <widget> XML node accepts a number of child arguments. The class and display_type arguments are required; the rest are optional.

* required

acl

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

cache_lifetime

The <cache_lifetime> argument is optional and specifies the number of seconds widget content should be cached for. If a widget does not define a <cache_lifetime>, the default value of 86400 (1 day) is used. Change the default cache lifetime by setting the Hyva\AdminDashboardFramework\Model\Config\Widget\Converter class's defaultCacheLifetime argument via di.xml.

category

The <category> argument is optional and groups widgets together. Widgets with the same <category> value are grouped in the new widget instance creation modal. Uncategorized widgets fall into an Other category, which is appended to the list of defined <category> values. Change the default <category> name 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 implements the behavior 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\AdminDashboardApi\Api\V1\WidgetTypeInterface (or, for legacy widgets, 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 maps display types to templates through its displayTypeTemplateMap property, configured 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 template but no <template> argument is present. The same is true if any other <display_type> value is used without a matching entry in the Hyva\AdminDashboardFramework\Model\Config\Widget\Converter class's displayTypeTemplateMap.

full_screen

The <full_screen> argument is optional and flags whether admin users can view the widget in a full screen modal. When enabled, an additional option is added to the widget instance menu to toggle the full screen view.

icon

The <icon> argument is optional and assigns 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 is typically any of the icons documented here.

min_height

The <min_height> argument is optional and specifies the minimum number of rows the widget should occupy in the dashboard. Admin users cannot 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 specifies the minimum number of columns the widget should occupy in the dashboard. Admin users cannot resize their widget instances to a width smaller than the value specified. The default value is 1.

tags

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

template

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

title

The <title> argument is optional and provides a user-friendly name for the widget. If no <title> is given, the widget defaults to using its id value, replacing special characters with spaces and capitalizing each word.

trailing_action

The <trailing_action> argument is optional and defines a number of key/value pairs for use in the widget's getTrailingAction() function.

These are currently used to provide a link in the widget's footer, where the <label> defines the text to render and the <route> is a destination URL or admin route path. The <target> argument specifies whether the link opens in the current tab or a new one.

XML Validation

The XSD that validates these files ships with the Hyva_AdminDashboardApi module in etc/adminhtml/hyva_dashboard_widget.xsd.

Reference it via the URN urn:magento:module:Hyva_AdminDashboardApi:etc/adminhtml/hyva_dashboard_widget.xsd.