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.

Tip: 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.

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 regarding the installation and the download links are available in the following articles:

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' %}

Placing your own content in blocks

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:

Adding content according to the original content of the block:

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

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

Adding content in front of the original content of the block:

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

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

Overwriting 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.

Displaying a ThemeWare® variable

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

{# from Shopware 6.4 #}
{{ theme_config('twt-body-class') }}

{# Shopware 6.3 or lower #}
{{ shopware.theme['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". #}

{# from Shopware 6.4 #}

{% 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 "..." #}

{# from Shopware 6.4 #}

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