Creating Components

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 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\CmsLiveviewEditor\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 should be included for the Hyvä CMS editor to interact with content preview. It is not required on every field in your component but should at least be added to the root element for your component.

Useful Block Methods

Bellow is a summary of some of the more useful methods available to you in your component template. Review the Hyva\CmsLiveviewEditor\Block\Element class for more details.

getEditorAttrs

getEditorAttrs(string $field = '', ?string $childUid = null): string

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

renderEditorMessage

renderEditorMessage(array $arguments = [], ?string $type = null, ?string $template = null): string

Renders a message visible only in the CMS editor. Useful for showing a placeholder when no default_value is set.This method is used to render a message in the editor only.

<?= /** @noEscape */ $liveview->renderEditorMessage([
    'preview_message' => __('No image selected'),
    'button_text' => __('Select Image'),
]) ?>

validPreview

validPreview(): bool

This method checks if the current request is a valid preview request. Returns false if the request is for public facing content, returns true if viewing a preview of the content in a new tab or from within the Hyvä CMS editor. Useful for conditionally adding content which should only be rendered in preview mode.

getImagePath

getImagePath(string $imagePath): string

This method returns the full path to an image file in the media directory.

buildClasses

buildClasses(array $baseClasses, ?string $configKey = null, bool $includeElementClasses = true): string

This method builds a string of CSS classes based on the provided classes and any additional classes specified in the component configuration.

$classes = $block->buildClasses('my-custom-class', [$block->getData('classes')]);

getLinkPath

getLinkPath(string $linkPath): string

This method returns the full path to a link for the link field type.

<?php $link = $block->getLink() ?? []; ?>
<a href="<?= $escaper->escapeUrl($block->getLinkPath($link)) ?>">

Adding more to your component

Check out the the Component Declaration JSON Schema for more information on the component declaration options, below are some examples on what is available.

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 range products richtext select searchable_select text text-align textarea variant custom_type

Field Attributes and Validation

Add context and HTML5 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:

"media_content": {
  "media_items": {
    "type": "children",
    "label": "Media Items",
    "config": {
      "accepts": ["image", "banner"]
    }
  }
}

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.