Skip to content

Widget PHP Implementation

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\AbstractWidgetType. This abstraction provides a number of common dependencies, helper functions, and global configuration options.

Note

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

Widget Properties

Widget properties refer to a set of input options users can use to configure and customize their widgets. Widgets define the following property sets:

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.

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.

Property Helpers

getProperties()

public function getProperties(string $propertyType): array

This function takes a single argument: $propertyType. If the widget type contains a property set which matches the given $propertyType, it will return the set of input options for it - otherwise returning an empty array.

getPropertyByName()

public function getPropertyByName(string $propertyType, string $propertyName): ?array

This function takes two arguments: $propertyType and $propertyName. If the widget type contains a property set which matches the given $propertyType and that set contains a property which matches the given $propertyName, it will return the corresponding 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 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\AbstractWidgetType 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.

Widget Configuration

In some instances, widget configuration values will need to undergo some processing before they are used so accessor functions exist to perform these mutations.

getTitle()

public function getTitle(?WidgetInstanceInterface $widgetInstance): Phrase

This function is called when the widget title renders. It receives a widget instance object as an optional parameter to allow developers access to specific configuration values, should they be required. The default implementation returns the widget title as a translatable phrase for localisation.

See the XML <title> configuration documentation for more information.

getTrailingAction()

public function getTrailingAction(?WidgetInstanceInterface $widgetInstance): array

This function is called when the widget footer renders. It receives a widget instance object as an optional parameter to allow developers to access specific configuration values, should they be required. The default implementation returns an array the associated template uses to render a link.