Skip to content

Creating Hyvä CMS Components

This guide explains how to create new custom components for the Hyvä CMS Liveview Editor. Hyvä CMS components are reusable content blocks that content editors can drag and drop onto pages through the visual editor. Well-designed components provide a great editor experience and help maintain consistent design patterns across your site.

Component Structure Overview

A Hyvä CMS component consists of two main parts that work together:

  1. Component Declaration: A JSON configuration file defining the component's ID, label, editable fields, and template path. This declaration determines what options appear in the Hyvä CMS editor interface.
  2. Component Template: A PHTML file that renders the component's HTML output using data from the component declaration fields.

Both files must be created in your custom Magento module to register a new Hyvä CMS component.

Creating a Basic Hyvä CMS Component

Follow these steps to create a functional Hyvä CMS component with editable fields.

Step 1: Create the Component Declaration JSON File

The component declaration defines how the component appears in the Hyvä CMS editor. Create a components JSON file in your module's etc/hyva_cms/ directory.

Create the file at etc/hyva_cms/components.json in your module:

app/code/Vendor/Module/etc/hyva_cms/components.json
{
  "my_component": {
    "label": "My Component",
    "template": "Vendor_Module::elements/my_component.phtml",
    "content": {
      "title": {
        "type": "text",
        "label": "Title",
        "default_value": "Default Title"
      },
      "description": {
        "type": "textarea",
        "label": "Description",
        "attributes": {
          "placeholder": "Enter description here"
        }
      }
    }
  }
}

The example above creates a component named my_component with two editable fields: a text field for the title and a textarea for the description. The content section contains the fields that appear in the component's Content tab within the Hyvä CMS editor.

For detailed information about all available component declaration options, see Component Declaration Schema.

Step 2: Create the Component Template PHTML File

The component template renders the HTML output using data from the component declaration. Create a PHTML template at the path specified in your component declaration (or at the default path if you omitted the template property).

Create the file at view/frontend/templates/elements/my_component.phtml:

app/code/Vendor/Module/view/frontend/templates/elements/my_component.phtml
<?php
declare(strict_types=1);

use Hyva\CmsLiveviewEditor\Block\Element;
use Magento\Framework\Escaper;

/**
 * Hyvä CMS Component Template: My Component
 * Renders a title and description with editor integration
 * 
 * @var Element $block - Provides access to component field data and editor methods
 * @var Escaper $escaper - Magento HTML escaper for security
 */

// Retrieve field values from the component declaration
// These correspond to the "title" and "description" fields defined in components.json
$title = $block->getTitle() ?? null;
$description = $block->getDescription() ?? null;
?>
<div>
    <!-- getEditorAttrs('title') enables click-to-edit for the title field in the preview -->
    <h2 <?= /** @noEscape */ $block->getEditorAttrs('title') ?>>
        <?= $escaper->escapeHtml($title) ?>
    </h2>

    <!-- Each editable field gets its own getEditorAttrs() call with the field name -->
    <div <?= /** @noEscape */ $block->getEditorAttrs('description') ?>>
        <?= $escaper->escapeHtml($description) ?>
    </div>
</div>

The template accesses field data using getter methods on the $block object. Field names from the component declaration (like title and description) become camelCase getter methods (like getTitle() and getDescription()).

Automatic Editor Attributes

Available since Hyvä CMS 1.2.0

Automatic injection of editor attributes was added in Hyvä CMS 1.2.0. In earlier versions, add getEditorAttrs() to the root element of each component template yourself.

Hyvä CMS automatically injects the editor integration attributes into the first HTML element of your component's rendered output. This includes data-liveview-element, the block id (when a block ID is set), and the root getEditorAttrs() values. You no longer need to add getEditorAttrs() to the root element of your component yourself, which is why the example above leaves the wrapping <div> plain.

Keep adding getEditorAttrs('field_name') to individual fields, though. Field-level attributes are what enable click-to-edit for each field in the preview, and they are not auto-injected.

All editor attributes appear only in preview mode and are stripped from the final storefront output.

Taking manual control of editor attributes

If your component has multiple root elements, or you need precise control over where editor attributes land, opt out of automatic injection by setting auto_attributes to false (it must be the boolean false), then add the attributes yourself:

<?php $block->setData('auto_attributes', false) ?>
<div
    <?= /** @noEscape */ $block->getEditorAttrs() ?>
    <?= /** @noEscape */ $block->renderBlockId() ?>
    data-liveview-element="my_component"
>

Available Field Types for Hyvä CMS Components

The Hyvä CMS editor supports many field types for building rich component interfaces. Each field type provides a different editing experience in the CMS editor and returns different data structures to your component template.

Commonly used field types include:

  • text and textarea: single-line and multi-line plain text input
  • richtext: WYSIWYG rich text editor (TipTap) with link, image, widget, and variable insertion
  • image: image upload with media gallery browser
  • link: link builder with URL, label, and target options
  • select, multiselect, and searchable_select: dropdown and multi-checkbox selection
  • products, category_selector, and widget: catalog and widget selectors
  • variant: template variant selector for different component styles
  • custom_type: a custom field type implemented by an extension

For the complete, authoritative list of field types (including boolean, color, date, datetime, html, number, range, preset, text-align, url, and category_importer) with their configuration options and data structures, see the Component Declaration Schema field types reference.

Next Steps

With a basic component in place, these pages cover more advanced component development: