Skip to content

Dashboard API

The Hyva_AdminDashboardApi module is the stable contract for the Hyvä Admin Dashboard widget system. It ships only PHP interfaces, a reusable WidgetContext value object, the widget XML schema, and a small set of constants - no controllers, no templates, no runtime.

Modules that expose custom widgets should depend on the API module, not on the dashboard runtime. This means bin/magento setup:di:compile succeeds on any project that has the API module installed, even when the dashboard itself is not yet present.

The package is released under the OSL-3.0 license so that third-party widget modules can depend on it without license-compatibility concerns. The reference implementation that consumes these interfaces ships in Hyva_AdminDashboardFramework.

Public Interfaces

Core Widget Contract

The core widget contract in Hyva\AdminDashboardApi\Api\V1\ defines how every custom widget interacts with the framework:

  • WidgetTypeInterface - the composition-based widget contract. Every method takes a WidgetContextInterface as its first argument. See Widget PHP Implementation for the full method-by-method reference and worked examples.
  • WidgetContextInterface - read-only context passed to every widget method. Carries the merged widget XML and the chart-type defaults. Default implementation: Hyva\AdminDashboardApi\Model\WidgetContext.
  • WidgetInstanceInterface - slim read-only view of a saved widget instance. Exposes getInstanceId(), getWidgetTypeId(), getCreatedBy(), getConfiguration(), getPropertyValues(string $propertyType), and getPropertyValue(string $propertyType, string $propertyName).
  • WidgetAuthInterface - minimal auth contract used by WidgetContext::isAllowed(). Exposes isAllowedAcl(?string $resource) and getCurrentAdminUserId().

Chart Interfaces

The five chart interfaces in Hyva\AdminDashboardApi\Api\V1\ChartType\ extend WidgetTypeInterface without adding any methods. Their purpose is to tag a widget so that the framework's WidgetContextFactory wires the matching defaults provider into the context:

  • BarChartWidgetTypeInterface
  • LineChartWidgetTypeInterface
  • PieChartWidgetTypeInterface
  • NumberWidgetTypeInterface
  • DateIntervalWidgetTypeInterface

The expected data shape for each chart type is defined by the framework template that consumes it. See the Charts reference for the built-in chart implementations.

Supporting Interfaces

The supporting interfaces provide defaults, date-interval helpers, and option sources without coupling widget classes to the framework:

  • Hyva\AdminDashboardApi\Api\V1\Defaults\WidgetTypeDefaultsInterface - supplies chart-type-specific default property definitions to the context. Implementations live in the framework module; widget classes never reference this interface directly.
  • Hyva\AdminDashboardApi\Api\V1\Service\WidgetDateIntervalHelperInterface - helper for date-interval widgets. Inject it directly into a widget class so the widget does not need to extend the framework's AbstractDateIntervalWidget. Exposes getDateIntervalsAsOptions() and getIntervalDataWithTimestamps().
  • Hyva\AdminDashboardApi\Api\V1\Source\WidgetDateIntervalSourceInterface - extends Magento\Framework\Data\OptionSourceInterface and adds getIntervals() so consumers can read interval configurations without coupling to the concrete framework source model.

Constants

The API module centralizes the string keys the framework reads so you never have to hardcode magic strings:

  • Hyva\AdminDashboardApi\Api\ConfigurationKeys
    • CONFIGURABLE_PROPERTIES = 'configurable_properties'
    • DISPLAY_PROPERTIES = 'display_properties'
  • Hyva\AdminDashboardApi\Api\WidgetOptions - string constants for every widget XML element and attribute the framework reads. Use these instead of magic strings when constructing or inspecting widget XML programmatically.

Installing Without the Runtime

A widget module can depend on the Dashboard API alone, so it compiles on projects that do not have the dashboard runtime installed. The module's composer.json only needs to require this package:

{
    "require": {
        "hyva-themes/commerce-module-admin-dashboard-api": "^2.0"
    }
}

With only the API package required, bin/magento setup:di:compile succeeds regardless of whether the dashboard runtime is installed. End users see the widget only on installations that also have hyva-themes/commerce-module-admin-dashboard available.

  • Widget PHP Implementation - Worked example of writing a widget against the API.
  • XML Configuration - Full reference for etc/adminhtml/hyva_dashboard_widget.xml.
  • Available Widget Types - The built-in widgets shipped by Hyva_AdminDashboardWidgets, the CMS-widgets module, and the CrUX history module.
  • Module Structure - How the API package fits alongside the framework, widget, and advanced-widget modules.