The documentation you are reading pertains to a product currently under development. As it is still evolving, the features, specifications, and details provided herein are subject to change without notice. We recommend checking back regularly for the most up-to-date information.

Creating Components

This guide explains how to create new components for Hyvä CMS Liveview 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:
1. Component Declaration - A JSON configuration defining the component and its editable fields 2. Component Template - A PHTML file rendering the component's HTML

Creating a Component

Step 1: Create Component Declaration

Create a components JSON file in your module's etc/hyva_cms/ directory:
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"
        }
      }
    }
  }
}

template

You can omit the template property, in which case a default path is used in the current module: [Vendor]_[Module]::elements/[component-name].phtml

content, design & advanced sections

The content property is used to define the fields that will be displayed in the component's content section. You can similarly add fields to the design and advanced sections.

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

Step 2: Create Component Template

Create a PHTML template at the path specified in your component declaration or the default path: [Vendor]_[Module]::elements/[component-name].phtml.

<?php
declare(strict_types=1);

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

/**
 * @var Element $block
 * @var Escaper $escaper
 */
?>
<div <?= /** @noEscape */ $block->getEditorAttrs() ?>>
    <h2 <?= /** @noEscape */ $block->getEditorAttrs('title') ?>><?= $block->escapeHtml($title) ?></h2>

    <div <?= /** @noEscape */ $block->getEditorAttrs('description') ?>>
        <?= $block->escapeHtml($description) ?>
    </div>
</div>

getEditorAttrs

The getEditorAttrs() method adds special attributes that allow the Hyvä CMS liveview editor to interact with content. When a user clicks on content in preview mode, these attributes ensure the correct form opens for editing. These attributes are only added in preview mode and are not present in the final rendered output.

Adding more to your component

Field Types Reference

Explore the full range of field types to create rich component interfaces:. The following field types are supported:

boolean children color date html image link multiselect number products richtext select text text-align textarea variant custom_type

custom_type

The custom_type field type is reserved, soon it will allow developers to create their own field types.

Field Attributes and Validation

Add context and validation to your fields with attributes:

{
  "my_component": {
    "content": {
      "text_field": {
        "type": "text",
        "label": "Text Field",
        "attributes": {
          "required": true,
          "minlength": "1",
          "maxlength": "100",
          "comment": "This is a comment",
          "placeholder": "Enter text here"
        }
      }
    }
  }
}

Child Components

Create parent-child component relationships:

"content": {
  "items": {
    "type": "children",
    "label": "Items",
    "config": {
      "accepts": ["item"]
    }
  }
}

accepts

The accepts property is used to specify the allowed child components. If omitted, all components are allowed.

Including Shared Fields

Reuse common fields across components. Useful for common design and advanced settings. The includes property accepts both an array of paths or a single path.

"design": {
  "includes": "Hyva_CmsBase::etc/hyva_cms/default_design.json"
}

Using Variants

Create component variations with different templates:

"content": {
  "variant": {
    "type": "variant",
    "label": "Style Variant",
    "options": [
      {"label": "Default", "value": "Vendor_Module::elements/my_component/default.phtml"},
      {"label": "Alternative", "value": "Vendor_Module::elements/my_component/alternative.phtml"}
    ]
  }
}

More Examples

See the Hyva_CmsBase module for more examples of components.