Themes and overriding templates

A theme is the look of the storefront: templates, styles, pictures. The default theme is the Twig files in catalog/view/template/ and the stylesheet catalog/view/stylesheet/stylesheet.css. Editing them directly is a bad idea — an update overwrites them. Version 4 gives three ways to change the look from the outside.

The ways

The theme editor

Open Design → Theme Editor, choose a template in the tree, for example common/footer, change the code and save. The changed copy is stored in the database, the file stays as it was. The page shows the copy from the database; a reset button returns the original.

Overriding a template from an extension

Version 4 has no folder where a template with the same name replaces the core one. The replacement is done with an event: a handler of view/.../before changes the path of the template.

Copy the core template into the extension and change it there:

extension/acme_hello/catalog/view/template/common/footer.twig

Add the handler to the storefront controller of the module:

// extension/acme_hello/catalog/controller/module/acme_hello.php
// trigger: catalog/view/common/footer/before
public function footerTemplate(string &$route, array &$data): void
{
    $route = 'extension/acme_hello/common/footer';
}

Register the event in install() with the trigger catalog/view/common/footer/before and the action extension/acme_hello/module/acme_hello.footerTemplate, then reinstall the module. Open any storefront page — the footer is rendered from your file, with the same data the core controller prepared.

To replace many templates, one handler is subscribed to catalog/view/*/before and changes the route only for paths from its own list.

Your own styles

A stylesheet is added through $this->document before the header is rendered:

// trigger: catalog/controller/common/header/before
public function addStyles(string &$route, array &$args): void
{
    $this->document->addStyle('extension/acme_hello/catalog/view/stylesheet/acme.css');
}

/* extension/acme_hello/catalog/view/stylesheet/acme.css */
.acme-note {
    color: #b45309;
    font-weight: 600;
}

Open the source of any storefront page — the head contains a link to acme.css, and the paragraph added in the events lesson is orange.

A theme extension

A complete theme is an extension of the type theme: it has a settings page in admin/controller/theme/, and it is chosen in the store settings, System → Settings, the General tab. Inside it uses the same technique — events that replace template paths and add styles. The way a theme is registered at the start of a request changed between releases 4.0 and 4.1, so take a working theme for your release as a sample.

Common mistake

The template is copied into the extension once and forgotten. After an update of the shop the core template gets a new variable or a fixed form, and the copy stays old — a button on the page stops working. Override as few templates as possible, and after every update compare your copies with the new core files.