Skip to content

Overriding Existing Components

Hyvä CMS allows developers to override existing components to customize their appearance and functionality. This page explains how to override Hyvä CMS components for both visual-only changes and functional modifications, including field customization, template overrides, and legacy template support for disabled components.

Two Approaches to Overriding Hyvä CMS Components

Hyvä CMS supports two distinct override approaches, and selecting the correct method depends on the type of customization you need to make. Visual-only changes require overriding template files in your theme directory, while functional changes—such as modifying component fields, settings, or behavior—require overriding the component JSON definition in a custom module.

The two approaches are:

  1. Template override: For visual changes only (markup and styling)
  2. Component definition override: For functional and structural changes (fields, settings, behavior)

Overriding Templates for Visual Changes

To make visual-only changes to Hyvä CMS components, override the component's template file in your theme directory. This approach gives you control over the markup and styling without modifying the component's underlying structure or functionality. Template overrides work for any component distributed by Hyvä CMS or custom components in your project.

Template Override File Location

Place overridden template files in your custom theme directory following the module namespace and path structure. The override location matches the original template's module path under your theme directory.

For example, to override the Image Component template file (Hyva_CmsBase::elements/image.phtml), place your customized template at: {themedir}/Hyva_CmsBase/templates/elements/image.phtml.

This template override pattern applies to all Hyvä CMS component templates. The theme-level override takes precedence over the module's default template, allowing you to customize the visual presentation while preserving the component's original functionality and field definitions.

When to Use Template Overrides

Use template overrides when you need to change component styling, HTML structure, or visual layout without modifying the component's fields, configuration options, or backend behavior. Template overrides are ideal for theme-specific customizations that don't affect content structure.

Overriding Component Definitions for Functional Changes

When you need to modify a Hyvä CMS component beyond visual changes—such as adding new fields, changing field types, removing configuration options, or altering component behavior—you must override the entire component JSON definition in a custom module. Hyvä CMS uses full component overrides rather than partial extensions to ensure complete control and predictable behavior.

Creating a Component Definition Override

To override an existing Hyvä CMS component definition, create a custom module that depends on Hyva_CmsBase and redeclare the component in your module's components.json file. The component key must match the original component key to replace it successfully.

Step 1: Configure Module Dependencies

First, ensure your custom module declares Hyva_CmsBase as a dependency in your module's etc/module.xml file. This dependency ensures your component override loads after the base component definitions.

app/code/Vendor/Module/etc/module.xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Vendor_Module">
        <sequence>
            <!-- Dependency ensures this module loads after Hyva_CmsBase -->
            <module name="Hyva_CmsBase" />
        </sequence>
    </module>
</config>

Step 2: Override Component Definition

In your module's etc/hyva_cms/components.json file, copy the original component declaration from Hyva_CmsBase (or the module that defines it) and make your required modifications. The component key must remain identical to the original for the override to work—changing the key creates a new component instead of overriding the existing one.

Your overridden component definition replaces the original component completely. You can add fields, remove fields, change field types, modify configuration options, or update the component's template path. The override gives you full control over the component's structure and behavior.

app/code/Vendor/Module/etc/hyva_cms/components.json
{
  "components": {
    "image": {
      "_comment": "Override of Hyva_CmsBase image component with custom fields",
      "template": "Vendor_Module::elements/image.phtml",
      "fields": {
        "image": {
          "type": "image",
          "label": "Image"
        },
        "custom_field": {
          "type": "text",
          "label": "Custom Field for Project-Specific Needs"
        }
      }
    }
  }
}

Full Override Behavior

Overriding a Hyvä CMS component completely replaces the original component declaration. Your override definition has full control over the component's structure, fields, and functionality without being constrained by the original implementation. Any fields or settings not included in your override will not be available in the overridden component.

Alternative: Disabling Components and Creating Replacements

Instead of overriding an existing component, you can disable the original component and create a replacement component with a new component key. This approach is useful when you want to preserve the original component for reference or when your replacement diverges significantly from the original.

To disable a component, set the disabled property to true in your component declaration:

app/code/Vendor/Module/etc/hyva_cms/components.json
{
  "components": {
    "image": {
      "_comment": "Disable the original image component",
      "disabled": true
    },
    "custom_image": {
      "_comment": "New component to replace the disabled image component",
      "template": "Vendor_Module::elements/custom-image.phtml",
      "fields": {
        "image": {
          "type": "image",
          "label": "Image"
        }
      }
    }
  }
}

Disabling Components Affects Existing Content

When you disable a Hyvä CMS component, existing pages that use that component may break unless you configure legacy template support. See the Legacy Template Support section below to maintain backward compatibility with existing content.

Overriding Component Template Paths

When you override a Hyvä CMS component definition, you can specify a custom template path in your component JSON definition. If you don't specify a template path, Hyvä CMS automatically generates the path based on your module namespace: [Vendor]_[Module]::elements/[component-name].phtml.

To override variant templates (template variations within a component), define the new template paths in your components.json file while preserving the original template filename. This filename preservation ensures the variant system correctly identifies and loads the template variation.

For example, to override the variant template Hyva_CmsBase::elements/banner/text.phtml, keep the text.phtml filename but change the directory path: MyCompany_Module::elements/my-banners/text.phtml.

Template Path Configuration

When overriding component definitions:

  • Specify the main template path in the template property of your component JSON definition
  • For variant templates, maintain the original filename (e.g., text.phtml) while changing the directory path
  • If no template path is specified, the path defaults to [Vendor]_[Module]::elements/[component-name].phtml
  • Template path changes in component definitions don't require theme-level file overrides

Why Hyvä CMS Uses Full Component Overrides

Hyvä CMS intentionally requires full component overrides rather than supporting partial component extensions or inheritance. This design decision provides several advantages for component customization and long-term project maintenance.

Complete Control and Ownership

Full component overrides give developers complete control over component structure and functionality. When you override a Hyvä CMS component, you can modify any aspect of the component definition without restrictions or constraints from the original implementation. This approach allows precise customization for project-specific requirements.

Clear Separation of Responsibilities

Overriding a component definition creates a clear boundary between base components provided by Hyvä CMS and your project-specific customizations. This separation clarifies which components are your responsibility to maintain and test when updating Hyvä CMS. You explicitly take ownership of overridden components, making it obvious which components require review during upgrades.

Manageable Scope

Most Magento sites using Hyvä CMS typically require only 20-30 components to support their content needs. Managing full component overrides for this limited number of components is reasonable and doesn't create excessive maintenance burden. The benefits of complete control and predictable behavior outweigh the cost of occasionally reviewing base component updates when upgrading Hyvä CMS.

Component Count as a Design Signal

Adding too many components to a Hyvä CMS installation is generally a sign of inconsistent content structure and design decisions. Excessive components make the CMS interface difficult for content creators to navigate and understand. Aim for a focused set of well-designed components rather than a large library of specialized variations.

Base Components as Reference and Starting Point

The base components provided by Hyvä CMS in the Hyva_CmsBase module serve as a quick start and reference guide for common content types. Many agencies build their own custom component suites tailored to their clients' specific content needs rather than relying entirely on base components. Creating custom Hyvä CMS components is a quick and straightforward process, making it practical to build project-specific component libraries.

Legacy Template Support

When you disable or remove a Hyvä CMS component from your project, existing pages that use that component may fail to render unless you configure legacy template support. Legacy template configuration allows disabled components to continue rendering existing content correctly while preventing the component from appearing in the component picker for new content.

This feature is particularly useful during component migrations, when replacing old components with improved versions, or when cleaning up unused components from your project while maintaining backward compatibility with historical content.

Configuring Legacy Templates

To enable legacy template support for disabled components, add a legacy template configuration to your module's etc/di.xml file. The configuration specifies which template files should remain valid for rendering even though their associated components are disabled.

Add the configuration to the ComponentValidator class using dependency injection:

app/code/Vendor/Module/etc/di.xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Hyva\CmsLiveviewEditor\Model\Security\ComponentValidator">
        <arguments>
            <argument name="legacyComponents" xsi:type="array">

                <!-- Single legacy template (component with no variants) -->
                <!-- Use xsi:type="string" for components with one template -->
                <item name="banner" xsi:type="string">Hyva_CmsBase::elements/banner/basic.phtml</item>

                <!-- Multiple legacy templates (component with variant templates) -->
                <!-- Use xsi:type="array" when preserving multiple variant templates -->
                <item name="cta" xsi:type="array">
                    <item name="0" xsi:type="string">Hyva_CmsBase::elements/cta/image.phtml</item>
                    <item name="1" xsi:type="string">Hyva_CmsBase::elements/cta/split.phtml</item>
                    <item name="2" xsi:type="string">Hyva_CmsBase::elements/cta/text.phtml</item>
                </item>

            </argument>
        </arguments>
    </type>
</config>

The legacyComponents argument accepts either a single template path (using xsi:type="string") or an array of template paths (using xsi:type="array"). Use the array format when the disabled component has multiple variant templates that need legacy support.

  • Creating Custom Components - Learn how to build custom Hyvä CMS components from scratch with custom fields and templates
  • Component Variants - Configure template variants to offer multiple visual presentations for a single component
  • Component Field Types - Reference documentation for all available field types when defining component structures