Skip to content

Widget PHP Implementation

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.

Each widget is powered by a PHP class that implements Hyva\AdminDashboardFramework\Model\WidgetType\WidgetTypeInterface, which defines a number of functions:

An abstract implementation of this interface exists in the form of Hyva\AdminDashboardFramework\Model\WidgetType\AbstractWidget. This abstraction provides a number of common dependencies, helper functions, and global configuration options.

Note

Extending from our Hyva\AdminDashboardFramework\Model\WidgetType\AbstractWidget class when creating your own widget types is optional however implementing the Hyva\AdminDashboardFramework\Model\WidgetType\WidgetTypeInterface is required.

Configurable Properties

The term "configurable properties" refers to the set of input options that configure the behaviour of the widget. Learn more about configurable inputs here.

getConfigurableProperties()

public function getConfigurableProperties(): array

This function typically returns an array of input options to present to the admin user to complete when adding the widget to their dashboard.

getConfigurablePropertyByName()

public function getConfigurablePropertyByName(string $name): ?array

This function takes a single argument: $name. If the widget type contains a configurable property which matches the given name, it will return the array of input data - otherwise returning null.

Display Properties

The term "display properties" refers to the set of input options that configure the appearance or style of the widget. Learn more about configurable inputs here.

getDisplayProperties()

public function getDisplayProperties(): array

Just like with configurable properties, the getDisplayProperties() function returns an array of input options to present to the admin user to complete when adding the widget to their dashboard.

getDisplayPropertyByName()

public function getDisplayPropertyByName(string $name): ?array

This function takes a single argument: $name. If the widget type contains a display property which matches the given name, it will return the array of input data - otherwise returning null.

Display Data

The term "display data" refers to a computed value or set of values the widget displays to the admin user when it is rendered on their dashboard. The format and/or presence of this value typically depend on the particular display type chosen for the widget. For example, something like the Link widget does not need to return any value as its configurable properties dictate what is rendered whereas the Google CrUX History widget needs to return an array of data in a format its template can consume.

getDisplayData()

public function getDisplayData(?WidgetInstanceInterface $widgetInstance)

This function is responsible for providing widget data, typically for the purpose of rendering a widget instance. It receives a widget instance object as an optional argument which can be used to provide developers with access to the concrete input values the admin user has chosen.

Widget Permissions

In addition to the <acl> XML configuration, the PHP class for a given widget type can define additional access control logic in finer detail.

isAllowed()

public function isAllowed(?WidgetInstanceInterface $widgetInstance): bool

This function allows developers to implement custom permission-related logic for their widget type(s). It receives a widget instance object as an optional argument which can be used to determine permissions based on specific widget instance data.

The Hyva\AdminDashboardFramework\Model\WidgetType\AbstractWidget class provides a default implementation which will return false when the current admin user does not have access to the resource defined in the widgets <acl> XML configuration or the widget instance provided was created by another admin user.

This function is used to determine whether an admin user is able to create, update, delete, or view widgets of the given type.

Save Logic

Two extension points have been created to allow developers to intercept the process of saving a widget instance, should they need to perform additional actions before and/or after an instance of a particular widget type is saved. The Hyva\AdminDashboardFramework\Model\WidgetInstance\WidgetInstanceRepository::save() function handles the invocation of the necessary functions.

Note

These functions are conceptually similar to those of the same name in the Magento\Framework\Model\AbstractModel class and were created to promote extensibility - preventing developers from having to create plugins for the Hyva\AdminDashboardFramework\Model\WidgetInstance\WidgetInstanceRepository::save() function where they would be intercepting every call to write widget instance data to the database and identifying whether it was of a type they were interested in before applying their custom logic.

Tip

The CheckList and Links widget types are examples of where these functions have been used.

beforeSave()

public function beforeSave(WidgetInstanceInterface $widgetInstance): WidgetInstanceInterface

This function is called before data is persisted to the database. It receives a widget instance object as a parameter and must return a widget instance object - typically the same object as was input.

afterSave()

public function afterSave(WidgetInstanceInterface $widgetInstance): WidgetInstanceInterface

This function is called after data is persisted to the database. It receives a widget instance object as a parameter and must return a widget instance object - typically the same object as was input.