Skip to content

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

Overriding Approaches

There are 2 main ways to override a component, and the correct approach depends on your objective:

  1. Visual changes only
  2. Functional (and visual) changes

Making Only Visual Changes to a Component

For visual only changes, we recommend overriding the components frontend template file(s) in your projects theme under the relevant matching module and path. This gives you full control over changing the markup and styles of your component.

For example, to override the template file for the Image Component (Hyva_CmsBase::elements/image.phtml), the overridden file would be placed within your custom theme at the following location: {themedir}/Hyva_CmsBase/templates/elements/image.phtml.

Making Functional Changes to a Component

If you need to make changes deeper than just visual updates, such as adding, changing or removing a components fields or other settings, then you will need to override the entire component JSON definition.

How to Override a Component

To customise existing components, you can override the component declaration in your own module. Hyvä CMS supports full overrides rather than partial changes.

Make sure your module's etc/module.xml file depends on Hyva_CmsBase. 

<module name="Vendor_Module" />
    <sequence>
        <module name="Hyva_CmsBase" />
    </sequence>
</module>
In our module's etc/hyva_cms/components.json file, copy the existing component declaration and make your changes as needed. The only thing which needs to remain the same is the component key.

You may also override the component's frontend template file then as needed.

Overriding completely replaces the original component declaration, giving you full control over its structure and functionality without being constrained by the original implementation.

If you prefer you can also disable the original component by setting the disabled property to true in the component declaration and creating your replacement, overridden component with a new key.

Why Full Overrides Instead of Extending Components

Hyvä CMS intentionally uses a full override approach rather than partial component extension for several important reasons:

Complete Control and Ownership

When you override a component, you gain full control over its structure and functionality. This gives you the freedom to make precisely the modifications needed for your project without being constrained by the original implementation.

Clear Separation of Responsibilities

By redeclaring a component, you're making a conscious decision to take ownership of that component going forward. This creates a clear boundary between the base components and your customizations.

Manageable Scope

Since most sites typically use only 20-30 components, managing full overrides is a reasonable approach that doesn't create an excessive maintenance burden. The benefits of control and predictability outweigh the cost of occasionally reviewing base component updates.

Adding too many components is generally a sign of inconsistent content structure and design. Excessive components can make the CMS difficult to manage for most content creators.

Reference and Starting Point

The base components provided by Hyvä can be viewed as a quick start and reference guide for common content types. Many agencies will build their own suite of components tailored to their merchants' specific needs, as creating custom components is a quick and straightforward process with Hyvä CMS.