README

hyva-themes/commerce-module-admin-dashboard-api

The purpose of this module is to let modules add dashboard widgets while remaining installable without Hyvä Commerce: only this contract module — distributed under the OSL — is required as a dependency, not the dashboard runtime itself.

This module only ships only PHP interfaces, an XSD, and a small reusable WidgetContext value object — no runtime, no controllers, no templates.

Modules that implement custom dashboard widgets only need to depend on this package; they do not need hyva-themes/commerce-module-admin-dashboard to be installed for bin/magento setup:di:compile to succeed.

Installation

This module usually is installed as a transitive dependency of packages implementing Hyvä Commerce Admin Dashboard Widgets.

To install it explicitly, use

composer require hyva-themes/commerce-module-admin-dashboard-api
bin/magento setup:upgrade

Scope

This package provides the contract for Hyvä Admin Dashboard widgets:

• Hyva\AdminDashboardApi\Api\V1\WidgetTypeInterface — the widget contract; methods receive a WidgetContextInterface as the first argument
• Hyva\AdminDashboardApi\Api\V1\WidgetContextInterface — read-only context exposed to widgets (merged config, ACL helper, chart-type defaults)
• Hyva\AdminDashboardApi\Api\V1\WidgetInstanceInterface — slim read-only view of a saved widget instance
• Hyva\AdminDashboardApi\Api\V1\WidgetAuthInterface — minimal ACL/authentication contract
• Hyva\AdminDashboardApi\Api\V1\Defaults\WidgetTypeDefaultsInterface — backs $ctx->getDisplayProperties() / getConfigurableProperties()
• Hyva\AdminDashboardApi\Api\V1\Source\WidgetDateIntervalSourceInterface — option source for date-interval widgets
• Hyva\AdminDashboardApi\Api\V1\Service\WidgetDateIntervalHelperInterface — interval-data helper for date-interval widgets
• Hyva\AdminDashboardApi\Api\V1\ChartType\*WidgetTypeInterface — five marker interfaces for bar / line / pie / number / date-interval widgets
• Hyva\AdminDashboardApi\Api\WidgetOptions and ConfigurationKeys — constant holders
• Hyva\AdminDashboardApi\Model\WidgetContext — concrete reusable WidgetContextInterface implementation
• etc/adminhtml/hyva_dashboard_widget.xsd — XML schema for <widget> declarations

The runtime that actually renders the dashboard lives in hyva-themes/commerce-module-admin-dashboard.

Implementing a widget

See docs/implementing-a-widget.md for a full guide to implementing a custom dashboard widget.

Backward compatibility

The legacy contract Hyva\AdminDashboardFramework\Model\WidgetType\WidgetTypeInterface and the AbstractWidgetType base class continue to work unchanged. The dashboard runtime in hyva-themes/commerce-module-admin-dashboard dispatches to both contracts via runtime instanceof checks.

License

This package is licensed under the Open Software License (OSL 3.0).

• Copyright: Copyright © Hyvä Themes. All rights reserved.
• License Text (OSL 3.0): The full text of the OSL 3.0 license can be found in the LICENSE.txt file within this package, and is also available online at http://opensource.org/licenses/osl-3.0.php.