Extending for Other Content Types

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

4.1System Config

Add system config to enable/disable Hyvä CMS Liveview for your content type:

Path: hyva_commerce_cms/[your_content_type]/enabled
This controls global availability of Liveview for this content type.

4.2 Content Listing Page

On your content listing page, when Liveview is enabled:

Add a Yes/No column for the is_liveview_enabled status.
Optionally add an action to open new content in the Liveview editor.

4.3 Content Form

On your content form, when Liveview is enabled:

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.

4.4 Automatic CSP Frame Policies

To enable Automatic CSP Frame Policies for multi-domain setups without manual configuration, add new routes that display the preview (e.g. the content form from section 4.3) to your module's etc/adminhtml/di.xml file.

<type name="Hyva\CmsLiveviewEditor\Model\Security\IsValidAdminPreviewRequest">
    <arguments>
        <argument name="allowedRoutes" xsi:type="array">
            <item name="blog/page/edit" xsi:type="string">blog/page/edit</item>
        </argument>
    </arguments>
</type>

An example of this can be found in:

vendor/hyva-themes/commerce-module-cms/src/magento-cms/etc/adminhtml/di.xml

Note: This is required to support Automatic CSP Frame Policies for multi-domain setups without manual configuration. Otherwise, Magento instances running their admin area in CSP strict mode (as opposed to report-only mode) won't be able to display the preview.

4.5 Save Logic

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.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.

Use liveview_editor.xml instead of liveview_editor_index.xml to ensure compatibility with all the liveview editor functionality, e.g. scheduling.

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,
        is_tailwindcss_jit_enabled: this.formData.is_tailwindcss_jit_enabled ? 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: (Optional) Add Scheduling Support

If you want your custom content type to support scheduling functionality, you'll need to implement additional interfaces and handle scheduled content rendering:

Required Changes for Scheduling

Provider Interface Updates: Include the scheduledItemId parameter in your Hyva\CmsLiveviewEditor\Api\ProviderInterface::getStoreContentData() method implementation to support scheduling.
Implement ScheduleProviderInterface: Your content type provider must implement Hyva\CmsScheduling\Api\ScheduleProviderInterface to enable scheduling capabilities.
Handle Scheduled Content URL Parameter: Update your provider to handle the scheduled_item URL parameter when rendering scheduled content. See Hyva\CmsMagento\Plugin\Model\Page for implementation reference.

Step 10: 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