Individual template customizations (Twig, HTML)

In this article you will learn how to perform individual template customizations using the "ThemeWare® Customizing Plugin".

In case you want to change the appearance of ThemeWare® individually by means of a template customization, you will find useful tips for working with template files in this article.

Tip: Creating a ThemeWare® duplicate is not necessary for template customizations.

---

Introduction

For individual template customizations in Shopware 6 you need an own theme or a separate extension (plugin or app) and not – as in Shopware 5 – a theme derivative.

• Check whether there already is a suitable extension in the Shopware Community Store

• Alternatively, you may use the manual method using our "ThemeWare® Customizing Plugin" or the "ThemeWare® Customizing App" (see section "Integrating template customizations (for experienced users)").

---

Viewing the source code

The basic structure (folders, template files, Twig blocks, etc.) is given by the Shopware theme, "Shopware default theme" since ThemeWare® is technically an "extension" of it.

Note: Currently there is no possibility to view files of extensions (plugins, apps or themes) in the Shopware Cloud.

Attention: Do Never edit original files of Shopware or any extensions (plugins, apps or themes)!

ThemeWare® Pro Edition

custom/plugins/TcinnThemeWareXYZ/src/Resources/views
custom/plugins/TcinnThemeWareXYZ/src/Resources/views/themeware

ThemeWare® Cloud Edition

custom/apps/TcinnThemeWareXYZApp/Resources/views/storefront
custom/apps/TcinnThemeWareXYZApp/Resources/views/storefront/themeware

ThemeWare® only derives the necessary template files within the scope of our HC-Architecture® and adds for its own functions and features (e.g. widgets) its own template files.

In addition, please find the source code of the Shopware default theme on GitHub. The folder "views/storefront" contains all template files which are relevant for the storefront.

Finding the appropriate template file

When looking for a specific place in the templates, you can use e.g. the inspector of your browser to find a CSS class which is located at the corresponding element or at least in the immediate vicinity of the corresponding element.

Now you can search for this CSS class in the Shopware Git repository. In most cases a suitable template file will be found quite soon.

Example

For example, if you want to add something below the product description, take a closer look at the HTML code of the description:

...
<div class="product-detail-description tab-pane-container">
        <h2 class="product-detail-description-title">
                Product information "Main product with reviews"
        </h2>
        
        <div class="product-detail-description-text" itemprop="description">
                Lorem ipsum dolor sit amet, consetetur sadipscing elitr, ...
        </div>       
</div>
...

The description is surrounded by a <div> with the class product-detail-description-text.

We search in the Git repository for this CSS class and find the file description.html.twig (see GitHub).

A look at the source code of this file shows that the <div> with the product-detail-description-text class is located in the Twig block component_product_description_content_text.

...
{% block component_product_description_content_text %}
    <div class="product-detail-description-text"
         itemprop="description">
        {{ product.translated.description|raw }}
    </div>
{% endblock %}
...

So derive the file description.html.twig for your template customisation and extend the Twig block component_product_description_content_text.

Further information on deriving and extending template files can be found below.

---

Integrating template customizations (for experienced users)

Currently, Shopware 6 lacks a full-fledged child theme that allows you to include files and make changes (like Shopware 5). As a workaround, we have developed a small free "ThemeWare® Customizing Plugin" or "ThemeWare® Customizing App" for integrating individual customizations and your own files.

All information about the extensions, installation and download links can be found in the following articles:

Individual customizations with the ThemeWare® Customizing PluginIndividual customizations with the ThemeWare® Customizing App (Cloud)

---

Helpful Twig Basics

Shopware 6 uses Twig as template engine and no longer Smarty as used in Shopware 5. However, many things are the same or at least very similar in TwigIn order to give you a rough overview of Twig, we have briefly summarized the most important information in the following.

Note: Advanced links concerning the topic "Twig", please find in the Twig documentation: https://twig.symfony.com

Deriving a template file

In the first line of the file it has to be defined from which superior file it is derived.

{% sw_extends '@Storefront/storefront/page/product-detail/headline.html.twig' %}

Add content to Twig block

In order to place your own content in front of or behind the actual content of the block, you do not have to copy the entire code of the block. You can use the parent command as follows:

Add content after the original content of the block:

{% block name_of_the block %}
  {{ parent() }}

  {# Place new content here #}
{% endblock %}

Add content before the original content of the block:

{% block name_of_the block %}
  {# Place new content here #}

  {{ parent() }}
{% endblock %}

Overwriting Twig block

In case you want to replace the original content of the block completely, you can omit the parent command to empty the block.

{% block page_product_detail_name_container %}
  {# Place new content here #}
{% endblock %}

Displaying all variables

The output of all variables available on the page can be obtained with the dump command. The output has to be in a block and is only available in developer mode

{{ dump() }}

Including text snippets

The name of the desired snippet is available in the snippet management of your administration ("Settings" => "Shop" => "Snippets").

In order that the translations of the individual snippets are being considered, use the addition |trans.

{% block name_of_the block %}
  {{ parent() }}
  
  {{ "twt.widget.communities.headline"|trans }}
{% endblock %}

Outputting custom fields in the storefront

An additional field at the product level is output as follows:

{{ page.product.translated.customFields.technischer_name_zusatzfeld }}

An additional field for categories will be output as follows:

{{ page.footer.navigation.active.translated.customFields.technischer_name_zusatzfeld }}

Note: More information about custom fields are available in the Shopware-Documentation.

Querying a ThemeWare® variable

The query of a theme variable (e.g. the ThemeWare® configuration "Body class") in a Twig block works as follows:

{% if theme_config('twt-body-class') %}
    ...
{% endif %}

Outputting a ThemeWare® variable

The output of a theme variable must also take place in a Twig block. The following example shows the ThemeWare® configuration "Body class" (Tab "Others" => Block "Expert settings" => Section "Individual CSS class" => Field "Body class").

{{ theme_config('twt-body-class') }}

---

Additional ThemeWare® knowledge

Finding ThemeWare® variables

Our ThemeWare® Config Finder provides you with the opportunity to have all ThemeWare® variables displayed. The "technical name" in this overview is the name of the corresponding variable you can use in Twig or SCSS.

Delimitation for ThemeWare® customizations

In case a template customization is only relevant for a certain sales channel, you have the possibility to limit your customization for example via the ThemeWare® configuration with the "Body class".

For this purpose, enter a unique name for this sales channel (e.g. myshopname) in the theme duplicate for the corresponding sales channel using Tab "Others" => Block "Expert settings" => Section "Individual CSS class" => Field "Body class".

This name can then be used for Twig in an additional loop.

{# Customization only for theme with the body class "myshopname". #}

{% if theme_config('twt-body-class') == "meinshopname" %}
  {# Theme has body class "myshopname" #}
  ...
  {{ parent() }}
{% else %}
  {# Theme does not have body class "myshopname" #}
  {{ parent() }}
{% endif %}

Alternatively, you may also bind your customization to the ID of the sales channel:

{# Customization for a sales channel with the ID "..." #}

{% if context.salesChannel.id == "..." %}
  {# Sales channel has the ID "..." #}
  ...
  {{ parent() }}
{% else %}
  {# Sales channel does not have the ID "..." #}
  {{ parent() }}
{% endif %}