Extending for Other Content Types

Hyvä Commerce is an 'Early Access' product currently under development.

Early Access means that not all features of Hyvä Commerce are fully completed or released, and many areas are still under heavy development and may change. However, it means you can get your hands on everything currently available and being worked on, with a license. Find out more on our Early Access page.

This is an advanced topic and should only be attempted by experienced developers. Be prepared to debug cases specific to your content type integration.

This integration area may be particularly susceptible to breaking changes in future releases. When implementing custom content type integrations, be prepared to update your code when upgrading to new versions of Hyvä CMS.

The following is a general reference for extending Hyvä CMS for other content types. A lot of custom logic will be specific to your own implementation, but the following should give you a good starting point. See the Hyva_CmsMagento module for a more concrete example.

Step 1: Understanding core concepts

The Hyvä CMS Liveview editor provides an alternative content creation and editing experience to Magento's Page Builder. Hyvä CMS can be enabled:

Per individual content item.
For all content of a specific type (e.g., all CMS pages).
For all content types.

The editor identifies content through two key parameters:

type: Identifies the type of content being edited (e.g., 'cms_page', 'cms_block').
id: The unique identifier of the specific content item.

When creating new content, id is set to 0, signalling that a new record for the specified entity type should be created.

Hyvä CMS stores both a draft and a published version of the content.

Step 2: Name and Create Your Module

Choose a unique entity_type identifier for your content type. Following convention, this identifier should match the name of the database table you're extending Liveview for example cms_page, cms_block.

Create a dedicated module to implement your Liveview content type integration. To follow naming conventions, it should be named Vendor_HyvaCms[ContentTypeName] (e.g., Namespace_HyvaCmsBlog).

Step 3: Setup Database Tables, Models, and Interfaces

See [Hyva_CmsMagento::etc/db_schema.xml] for an example. And add necessary db_schema.xml, db_schema_whitelist.json, Model and API Interface classes to your module.

A table is required to store the main Hyvä CMS content and its properties, along with another for version history (e.g., hyva_commerce_cms_block & hyva_commerce_cms_page_version_history).

Tables should follow the column naming conventions used in Hyva_CmsMagento, especially for version history tables.

Step 4: Admin Settings and UI

Add system config to enable/disable Liveview for your content type: Path: hyva_commerce_cms/[your_content_type]/enabled This controls global availability of Liveview for this content type.
When Liveview is enabled for the content type:
- On your content listing page:
  - Add a Yes/No column for the is_liveview_enabled status.
  - Optionally add an action to open new content in the Liveview editor.
- On your content form:
  - Add a toggle for is_liveview_enabled.
  - Add a button/link to open the Liveview editor.
  - (Optional) Add a preview URL field if implementing custom previews.
- Add Logic to handle updating the data for your liveview entity once the form is saved. e.g. Hyva_CmsMagento::Observer/CmsPageSaveAfter.php

Note: After completing this step you should see the following error on the content form page and if you try to open the Liveview editor. We will fix this in the next step.

No content provider found for type: [name of your content type]

Step 5: Create a liveview provider

Create a provider class that implements Hyva\CmsLiveviewEditor\Api\ProviderInterface. This class will handle the content type-specific logic for Hyvä CMS. Register your provider in etc/di.xml to make it available to the provider pool.

example:

<type name="Hyva\CmsLiveviewEditor\Model\ProviderPool">
    <arguments>
        <argument name="contentProviders" xsi:type="array">
            <item name="cms_page" xsi:type="object">Hyva\CmsMagento\Model\LiveviewCmsPageProvider</item>
        </argument>
    </arguments>
</type>

It is worth reviewing how the ProviderInterface is implemented in Hyva_CmsMagento, as much of the logic may be adapted for your use.

Hyva\CmsMagento\Model\Provider\CmsBlockProvider
Hyva\CmsMagento\Model\Provider\CmsPageProvider

Step 6: Add Settings to the Liveview editor

Core settings handle non-content-related properties and enable the creation of new entities directly within the Hyvä CMS Liveview editor.

In liveview_editor_index.xml add a core-settings.[your content entity type] block to the core-settings block. It will require a ViewModel/Block to get formData, as well as an AJAX controller and model to handle saving the formData. Both frontend and backend form validation should be included.

example:

<referenceBlock name="core-settings">
    <block name="core-settings.cms_page" template="Hyva_CmsMagento::core-settings/page-form.phtml"/>
</referenceContainer>

Your block's template should dispatch two JavaScript events:

On initialisation, set the content label:

window.dispatchEvent(new CustomEvent('set-content-label', {
    detail: { label: '<?= $escaper->escapeHtml(__('Page')) ?>' }
}));

After saving the entity, notify listeners:

window.dispatchEvent(new CustomEvent('after-content-entity-saved', {
    detail: {
        entity_id: this.entityId,
        entity_type: this.entityType,
        is_active: this.formData.is_active ? 1 : 0,
        disabled_notice_message: this.disabledNoticeMessage
    }
}));

Step 7: Handle Liveview Display Logic

While your LiveviewProvider handles most of the Hyvä CMS specific logic, however in your own module you need to add logic to determine when to show Hyvä CMS content instead of Page Builder content, based on system configuration and content-specific settings.

In Hyva_CmsMagento this is handled with Plugin classes.

<type name="Magento\Cms\Api\Data\PageInterface">
    <plugin name="Hyva_CmsMagento::change_cms_page_content" type="Hyva\CmsMagento\Plugin\Model\Page" />
</type>
<type name="Magento\Cms\Api\Data\BlockInterface">
    <plugin name="Hyva_CmsMagento::change_cms_block_content" type="Hyva\CmsMagento\Plugin\Model\Block" />
</type>

Step 8: (Optional) Extend with Custom Components

See: Creating Components on Hyvä Documentation

Step 9: Testing and Validation

As this is an advanced integration, thorough testing is critical:

Test your implementation thoroughly, including:
- Content creation and editing
- Enabled vs disabled content
- Multi store view support
- Draft and published workflow
- Version history
- Form validation
- Content display logic
Be prepared to debug cases specific to your content type