Skip to content

Widget Layout XML

The admin dashboard framework registers several layout handles. They fall into three groups:

Core Handles

hyva_dashboard_widget

This layout handle contains all of the <container> and <block> definitions required for adding a widget dashboard to an admin page. It places the dashboard content in the standard content container and adds any additional JavaScript to the before.body.end container.

Tip

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

Due to the fact the ifconfig attribute cannot be used 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 house 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 instance skeleton, 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.

hyva_dashboard_widget_instance

This layout handle defines the structure of a widget instance, including its header, main content area, menu, and footer. It also defines a number of additional blocks within those areas to ease customization and extensibility. Each block in this handle receives an instance of the widget instance object as a data argument named widget_instance, providing developers with convenient access to the widget being rendered.

Per-Widget-Type Handles

In order to further ease customization the admin dashboard framework also supports additional layout handles for specific widget types. These handles follow the pattern hyva_dashboard_widget_instance_{{WIDGET_TYPE_ID}} and are loaded when rendering a widget of the given type.

default_magento_dashboard_* Handles

The framework also registers two handles that splice the Hyvä dashboard alongside the original Magento dashboard rather than replacing it:

  • default_magento_dashboard_before
  • default_magento_dashboard_after

The Hyva\AdminDashboardFramework\Observer\Adminhtml\AddDashboardLayoutHandles observer chooses between the two, based on the hyva_admin_dashboard/general/dashboard_position system configuration value, and appends the result to the layout for the dashboard_index_index route. Loading is gated by hyva_admin_dashboard/general/keep_default; when the configuration disables the legacy dashboard, neither handle is added.