Skip to content

Upgrading to Hyvä Commerce 1.3.0

The 1.3.0 release for Hyvä Commerce introduces a backwards-incompatible refresh of the Admin Dashboard modules. It ships a dedicated contract package, a new Dashboard Views & Roles workflow, and an expanded set of built-in widgets.

GitLab installs: add the new repositories before upgrading

If you installed Hyvä Commerce from the Hyvä GitLab repositories (agency / technology partner, dev-main / --prefer-source), Composer can only resolve git-hosted packages that have a matching repositories entry. This release introduces packages that existing composer.json files won't have configured yet, so add them before running composer update, otherwise the update fails to resolve:

# New required dependencies of the core stack
composer config repositories.hyva-themes/commerce-module-admin-dashboard-api git git@gitlab.hyva.io:hyva-themes/commerce-module-admin-dashboard-api.git
composer config repositories.hyva-themes/commerce-module-cms-tailwind-jit-bridge git git@gitlab.hyva.io:hyva-commerce/commerce-module-cms-tailwind-jit-bridge.git

# Optional modules — add only the ones your project uses
composer config repositories.hyva-themes/commerce-module-admin-dashboard-cms-widgets git git@gitlab.hyva.io:hyva-commerce/module-admin-dashboard-cms-widgets.git
composer config repositories.hyva-themes/commerce-module-cms-google-maps git git@gitlab.hyva.io:hyva-commerce/module-cms-google-maps.git
composer config repositories.hyva-themes/commerce-module-menu-builder git git@gitlab.hyva.io:hyva-commerce/module-menu-builder.git

See the full repository list in the installation guide for the complete set. License-key (Packagist) installations do not need this step — composer update pulls the new dependencies automatically.

Admin Dashboard

This is a backwards-incompatible release for the admin dashboard modules. The widget contract has been extracted into a new Composer package, the database schema gains support for shared dashboards, and a number of internal APIs have been moved or renamed.

Where to start

Most existing dashboards continue to work without changes: legacy widgets are bridged at runtime by the new WidgetTypeDispatcher. The work in this guide is required only if you maintain custom widgets, custom admin roles, or any integration code that touches the dashboard's PHP API.

Overview

The release introduces:

  1. A dedicated API module — Hyva_AdminDashboardApi. Custom widgets now depend on this rather than the dashboard runtime, so they compile without the full dashboard installed.
  2. A new, composition-based widget contract. Widgets implement Hyva\AdminDashboardApi\Api\V1\WidgetTypeInterface (or one of the chart-type interfaces) and read shared defaults from an injected WidgetContextInterface instead of inheriting from AbstractWidgetType.
  3. Dashboard Views & Roles. Admins can save named dashboard layouts and assign them to admin roles. New tables and a data migration patch ship with this release.
  4. An expanded built-in widget set and a new Hyva_AdminDashboardCmsWidgets module that ships CMS-focused widgets when hyva-themes/commerce-module-admin-dashboard-cms-widgets is installed.

The legacy widget contract (Hyva\AdminDashboardFramework\Model\WidgetType\WidgetTypeInterface and AbstractWidgetType) continues to function — a bridging class performs runtime checks and calls each widget against the contract it implements.

Composer

hyva-themes/commerce-module-admin-dashboard now requires hyva-themes/commerce-module-admin-dashboard-api: ^2.0. The api package is pulled in transitively, but third-party widget modules should add it to their own require block so they compile against the contract package directly.

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

Widget Contract Migration

The biggest break is the move of the widget contract from Hyva\AdminDashboardFramework\Model\WidgetType\… to Hyva\AdminDashboardApi\Api\V1\…. The new methods receive a WidgetContextInterface as their first argument.

Legacy class / interface New equivalent
Hyva\AdminDashboardFramework\Model\WidgetType\WidgetTypeInterface Hyva\AdminDashboardApi\Api\V1\WidgetTypeInterface
Hyva\AdminDashboardFramework\Model\WidgetInstance\WidgetInstanceInterface Hyva\AdminDashboardApi\Api\V1\WidgetInstanceInterface (slim, read-only)
Hyva\AdminDashboardFramework\Model\WidgetType\AbstractWidgetType (no replacement — implement the interface directly and read defaults from $ctx)
Hyva\AdminDashboardBaseWidgets\Model\Widget\AbstractBarChart (and Line/Pie/Number) Implement the matching *WidgetTypeInterface from Hyva\AdminDashboardApi\Api\V1\ChartType\
WidgetTypeInterface::KEY_CONFIGURABLE_PROPERTIES, KEY_DISPLAY_PROPERTIES Hyva\AdminDashboardApi\Api\ConfigurationKeys::CONFIGURABLE_PROPERTIES, DISPLAY_PROPERTIES

Removed and Relocated APIs

  • The etc/adminhtml/hyva_dashboard_widget.xsd schema now ships from Hyva_AdminDashboardApi. Widget XML files should reference urn:magento:module:Hyva_AdminDashboardApi:etc/adminhtml/hyva_dashboard_widget.xsd. Files that still point at the old Hyva_AdminDashboardFramework URN will continue to validate during the bridged period but should be updated.
  • The framework-side Hyva\AdminDashboardFramework\Model\WidgetType\WidgetTypeInterface has been removed. References should resolve to Hyva\AdminDashboardApi\Api\V1\WidgetTypeInterface via DI preference, but direct use statements need to be updated.
  • The framework-side Hyva\AdminDashboardFramework\Model\WidgetInstance\WidgetInstanceInterface is replaced by the slim Hyva\AdminDashboardApi\Api\V1\WidgetInstanceInterface. Widget implementations now receive the API interface; framework-internal code that needs the wider repository interface should depend on Hyva\AdminDashboardFramework\Api\V1\WidgetInstance\WidgetInstanceRepositoryInterface.
  • The abstract chart base classes (Hyva\AdminDashboardFramework\Model\Widget\AbstractBarChart and the Line/Pie/Number variants) remain in place for legacy widgets. New widgets should implement the matching interface from Hyva\AdminDashboardApi\Api\V1\ChartType\ instead of extending the abstract class.

Mapping Legacy Methods to the New Contract

The mechanical migration rule is: every method gains WidgetContextInterface $ctx as its first argument, and every former parent::method(...) call becomes $ctx->method(...).

Legacy implementation (AbstractWidgetType subclass):

class DailyOrderVolume extends AbstractDateIntervalWidget
{
    public function getDisplayProperties(): array
    {
        return array_merge(parent::getDisplayProperties(), [
            'highlight_today' => ['label' => __('Highlight today'), 'input' => ['type' => 'toggle']],
        ]);
    }

    public function getDisplayData(WidgetInstanceInterface $widgetInstance)
    {
        return [/* ... */];
    }
}

New implementation (composition):

class DailyOrderVolume implements DateIntervalWidgetTypeInterface
{
    public function getDisplayProperties(WidgetContextInterface $ctx): array
    {
        return array_merge($ctx->getDisplayProperties(), [
            'highlight_today' => ['label' => __('Highlight today'), 'input' => ['type' => 'toggle']],
        ]);
    }

    public function getDisplayData(WidgetContextInterface $ctx, WidgetInstanceInterface $widgetInstance): mixed
    {
        return [/* ... */];
    }

    // Plus pass-through implementations of getTitle, getConfigurableProperties,
    // getTrailingAction, isAllowed, beforeSave, afterSave that all delegate to $ctx.
}

See Widget PHP Implementation for the full worked example with every method.

Reading and Writing Widget Instance Values

WidgetInstanceInterface::getPropertyValue() and getPropertyValues() replace the legacy getConfigurablePropertyValue() / getDisplayPropertyValue() accessors that were removed in 1.0.0. Use the constants from Hyva\AdminDashboardApi\Api\ConfigurationKeys:

$storeIds = $widgetInstance->getPropertyValue(ConfigurationKeys::CONFIGURABLE_PROPERTIES, 'store_ids');

Database Migration

A new column and three new tables are added:

  • hyva_admin_dashboard_widget_instance.view_id — nullable foreign key into hyva_admin_dashboard_view.
  • hyva_admin_dashboard_view — stores named dashboards.
  • hyva_admin_dashboard_view_role — pivot table assigning views to admin roles.
  • hyva_admin_dashboard_user_active_view — records each admin user's currently selected view.

Existing widget instances created against 1.0.0 have view_id = NULL. The data patch Hyva\AdminDashboardFramework\Setup\Patch\Data\MigrateWidgetsToViews runs during setup:upgrade and, for every admin user with orphaned widgets, creates a personal "My Dashboard" view and reattaches the widgets to it. The patch is idempotent — once every widget has a view_id, subsequent runs short-circuit immediately.

Backups

The migration is non-destructive, but as with any data patch we recommend taking a database backup before running setup:upgrade on a production install.

ACL Changes

Four new ACL resources are introduced under Hyva_AdminDashboardFramework::dashboard → dashboard_views:

  • Hyva_AdminDashboardFramework::dashboard_views_create
  • Hyva_AdminDashboardFramework::dashboard_views_save
  • Hyva_AdminDashboardFramework::dashboard_views_delete
  • Hyva_AdminDashboardFramework::dashboard_views_assign

Custom admin roles that previously had access to the dashboard will continue to render widgets, but the new view-management actions are gated by these resources. Review each custom role and grant the resources that make sense for it; the default Magento administrator role receives them automatically.

Upgrade Checklist

  1. Bump hyva-themes/commerce-module-admin-dashboard to ^2.0.0 (or upgrade the Hyvä Commerce metapackage to ^1.3.0).
  2. (Optional) Add hyva-themes/commerce-module-admin-dashboard-cms-widgets if you want the CMS-focused widgets.
  3. Update any widget module's composer.json to require hyva-themes/commerce-module-admin-dashboard-api: ^2.0.
  4. Run composer update and bin/magento setup:upgrade. The migration patch will move any existing widgets into per-user views.
  5. Audit custom admin roles and grant the four new dashboard_views_* ACL resources where appropriate.
  6. (Optional, recommended) Migrate custom widgets to the new contract:
    • Replace extends AbstractWidgetType (and the chart subclasses) with implements WidgetTypeInterface (or the matching *WidgetTypeInterface chart type) from Hyva\AdminDashboardApi\Api\V1.
    • Add WidgetContextInterface $ctx as the first argument of every public method.
    • Replace parent::method(...) with $ctx->method(...).
    • Replace WidgetTypeInterface::KEY_* and WidgetInstanceInterface::KEY_* constants with their counterparts on Hyva\AdminDashboardApi\Api\ConfigurationKeys.
    • Update widget XML to reference the new XSD URN.

Hyvä CMS

The 1.3.0 release ships Hyvä CMS 1.2.0, a major update with backwards-incompatible changes. The headline change is a move from in-browser Tailwind JIT to a server-side, per-entity scoped Tailwind compiler. Most pages and blocks keep rendering after upgrade — a bridge package serves the previously-compiled CSS — but custom content-type providers, custom component templates, and pages using the Grid / Columns component need attention.

Where to start

A standard install upgrades cleanly with composer update and setup:upgrade. The work below is required only if you maintain a custom ProviderInterface implementation, custom component templates that hand-write editor attributes, or pages built with the Grid / Columns component.

Composer

Hyvä CMS 1.2.0 swaps its Tailwind strategy and adds several dependencies. A composer update of the Hyvä Commerce stack pulls these in automatically:

  • Removed hyva-themes/magento2-cms-tailwind-jit (the in-browser JIT compiler).
  • Added hyva-themes/magento2-cms-tailwind-compiler (server-side compiler) and hyva-themes/commerce-module-cms-tailwind-jit-bridge. The bridge keeps previously-compiled CSS rendering until content is recompiled.
  • Added core dependencies magento/module-media-gallery-api, magento/module-media-gallery-synchronization-api, magento/module-email, and symfony/http-foundation (^5.4 || ^6.0 || ^7.0 || ^8.0).

Tailwind scoping — ProviderInterface::getScopeSelector() (breaking)

For custom content types implementing ProviderInterface, Per-entity Tailwind isolation moved from a class prefix to a CSS scope selector. Hyva\CmsLiveviewEditor\Api\ProviderInterface gains a required method:

public function getScopeSelector(int $entityId): string;

Implementations return a selector matching the entity's scope, e.g. '.hcms-page-' . $entityId. The old getTailwindClassPrefix() is deprecated and no longer called.

Any custom class implementing ProviderInterface (a custom content-type integration) will fatal until it adds getScopeSelector(). Mirror the built-in providers and return .hcms-{type}-{id} for your entity.

Recompiling existing content

Existing pages and blocks keep rendering via the bridge package, but their CSS is not yet scoped. To regenerate scoped CSS:

  • Per entity: re-save the page or block in the editor — its scoped CSS is recompiled on save.

  • In bulk: install hyva-themes/magento2-cms-tailwind-recompile and run:

    bin/magento hyva:cms-tailwind:recompile

    Use --background to queue for cron processing, --theme=Hyva/default to limit to one theme, and --status to inspect the queue. Bulk recompilation uses the compiler daemon; if it isn't running the command falls back to a slower shell compile.

Grid / Columns column direction fix (review existing pages)

A logic error in the Grid / Columns component applied the start / end column-width presets in reverse — start placed the wide column on the right and end on the left, independently per breakpoint. This is fixed in 1.2.0.

Pages may render mirrored after upgrade

Any page authored under 1.1.x using a start or end preset will render mirrored once the fix lands. Watch especially for authors who compensated for the old bug by choosing the opposite preset — they will now be wrong again. Review every Grid / Columns block using start/end (the center preset is unaffected) across mobile, tablet, and desktop, and switch back any preset that was set to work around the old behaviour.

Auto-attributes injection (custom component templates)

Components now inject their editor attributes — data-liveview-element, the block id, and getEditorAttrs() output — into the first HTML element of the rendered template automatically. Most templates no longer need to add these by hand.

For a custom component template that already renders these attributes manually, add the opt-out flag so the injector doesn't also act on the element:

$block->setData('auto_attributes', false);

Use the opt-out when your template hand-writes the attributes, has multiple or conditional root elements, or needs the attributes on an element other than the first (e.g. a <picture> rather than its wrapper).

Removed admin configuration (low impact)

  • The per-width preview fields under Stores → Configuration → Hyvä CMS → Preview (Mobile / Tablet Preview Width) are removed; preview sizing is now a per-user Editor Preferences setting seeded from hyva_cms/preview/devices. The PHP getters getMobileWidth() / getTabletWidth() are retained, but the ConfigInterface constants XPATH_MOBILE_WIDTH / XPATH_TABLET_WIDTH are removed — code reading those paths directly should call the getters.
  • The Text Prose Class field (hyva_cms/editor_settings/text_class) is replaced by Default Component Classes. A data patch copies any existing value across on setup:upgrade; no manual action.

Hyvä Menu Builder

The 1.3.0 release ships Hyvä Menu Builder 1.0.0, with one backwards-incompatible change to the Menu Content component and a new runtime dependency on Hyvä CMS 1.2.0.

"Menu Content is now a styled container, not a grid (breaking)" The Menu Content component no longer renders a built-in column grid. Its layout, max_cols, and min_col_size fields are removed; it is now a flex container with alignment and full-width options. Existing Menu Content blocks that used "Column Grid" or "Content Grid" do not error — they silently collapse to a single stacked column, because the stored grid fields are no longer read. Reconfigure each affected block after upgrade: open it in the Liveview editor and drop a Grid / Columns component inside to recreate the columns.

Changelogs

The changelog is available here.

Known Issues

  • None so far