Themes and the child theme

The look of the front office is set by a theme — a folder in themes with Smarty templates, styles and scripts. The standard theme is called classic. Its files must not be edited: a shop upgrade puts them back to their original state. Instead you create a child theme: it inherits everything from the parent and holds only the changed files.

What a theme consists of

themes/classic/
├── assets/          styles, scripts, images
├── config/
│   └── theme.yml    the theme description
├── modules/         module templates changed by the theme
├── templates/       page templates
└── preview.png      the picture for the back office

Creating a child theme

Create the folder themes/acme by hand with three files in it:

themes/acme/
├── assets/
│   └── css/
│       └── custom.css
├── config/
│   └── theme.yml
└── preview.png

# themes/acme/config/theme.yml
parent: classic
name: acme
display_name: Acme
version: 1.0.0
assets:
  use_parent_assets: true
  css:
    all:
      - id: acme-style
        path: assets/css/custom.css
        priority: 200

The parent line makes the theme a child. name matches the folder name. use_parent_assets loads the parent's styles and scripts, and the css block adds your file on top of them.

/* themes/acme/assets/css/custom.css */
#header {
    border-bottom: 3px solid #2563eb;
}

Enabling it

Open "Design → Theme & Logo" in the back office. The "Acme" theme is in the list — press "Use this theme". Refresh the storefront: it looks like classic, but a blue line has appeared under the header.

Overriding a template

To change a template, copy it from the parent theme into the child theme at the same path and edit the copy. The engine looks for a template in the child theme first, then in the parent.

Replacing one block

You do not have to copy a whole template — you can extend it and override one block:

{* themes/acme/templates/catalog/product.tpl *}
{extends file='parent:catalog/product.tpl'}
 
{block name='product_description_short'}
    {$smarty.block.parent}
    <p class="acme-note">{l s='Delivery in two days' d='Shop.Theme.Catalog'}</p>
{/block}

The parent: prefix points to the parent theme's template. {$smarty.block.parent} prints the original content of the block, and the line below it is added after the short product description. Such a file survives an upgrade of the classic theme better than a full copy.

A module template

A theme can replace a module template too. It goes into the theme's modules folder, repeating the path inside the module:

{* themes/acme/modules/acmehello/views/templates/hook/home.tpl *}
<section class="acme-hello acme-hello--banner">
    <p>{$greeting}</p>
</section>

Now the greeting on the home page is rendered by this template, and the file in the module itself is untouched. This works because the module gives the path with the module: prefix — with it the engine looks for the file in the theme first.

What goes where

Hooks in a theme

Places for modules are set in templates by the theme: {hook h='displayFooterProduct' product=$product}. If you remove such a call in your template, the blocks of all modules on that hook disappear. Keep the hook calls when copying templates.

Common mistake

You changed a template or a style, but the site looks the same. With the "Never recompile template files" setting Smarty does not look at the file date. While editing, switch compilation to "Recompile templates if the files have been updated" on the "Advanced Parameters → Performance" page, or press "Clear cache" there.