You are currently viewing the article on an older Shopware version!

Changing a template

General Information

Never make adjustments in the default theme, always create a derived theme.

Please note that a derived theme is not a duplicate of the default theme that can be created through the Administration.

Create your own Theme

You can create an independent theme, in which you can then derive from the default theme, as follows:

First of all, you create a theme via the console using the command 

php bin/console theme:create

that generates the theme.
This then provides a plugin, which is listed in the plugin manager (Settings > System > Plugins).
To use the theme, you must install the plug-in in the plug-in manager and then activate it.
You can find information about the plug-in manager here.

The theme is then ready for use and can be assigned in the settings within the sales channel.

Basic functions

Derive file in own theme

As mentioned at the beginning, the adjustments should always be made in a separate theme.
You can derive the file in which you want to make adjustments from your theme.
The basis for the extension of the frontend theme are the files in the directory 
The derivation is done in the file and is possible for the storefront as follows

{% sw_extends '@Storefront/storefront/folder1/folder2/file.html.twig' %}

The derived file is also given the file extension ".html.twig", meaning also the name of the original file.
Then place the file in the directory 
/custom/plugins/YourTheme/src/Resources/views/storefront/folder1/folder2 on your server

YourTheme is the placeholder for the name of your theme.
The folder1 and folder2 correspond to the structure of the original directory. Use the corresponding original name here.

Functions within the .html.twig file

Output all available variables

{{ dump() }}

This provides an overview of the variables available on the page in the frontend. To obtain the list, you must call the frontend in the developer environment. How this is done, find a more detailed explanation here.

Include block from the derived file

{% block name_of_the_block %}

This allows you to include a block from the derived original file. This allows you to customize the content of the block.

Using content of the parent block

{{ parent() }}

If you want to place additional content in a block, it is not necessary to completely insert the content of the original file.

For example, this could look as follows.

{% block name_of_the_block %}
    {{ parent() }}
    {{ "snippet"|trans }}
{% endblock %}

This is where the content of the original block is included first. Then an additional text module is inserted below.

Including snippets

{{ 'snippetName'|trans }}

You can find the name of the text module in the admin in the area Settings > Shop > Snippets. Further information about the snippets can be found here.
The addition "|trans" ensures that the translations of the individual snippets are taken into account.

Display your own snippets in the frontend

If you did not create the favored textblocks yet, you can do this in the admin under Settings > Shop > Snippets. Further information about the text modules can be found here.

Include snippets

In this example, a user-defined text module is to be included in the footer. The same procedure can be adopted for other page areas.

To customize the footer you will need the file footer.html.twig from the directory   /vendor/shopware/storefront/Resources/views/storefront/layout/footer.
You can then derivate this file in your own theme under  /custom/plugins/MyTheme/src/Resources/views/storefront/layout/footer.

The derivation could look as follows

{% sw_extends '@Storefront/storefront/layout/footer/footer.html.twig' %}

{% block layout_footer_service_menu_content %}
    {{ parent() }}
    {{ "sw.test.footer1"|trans }}
{% endblock %}

The text module "sw.test.footer1" is included here as an example.

Lastly, it may be necessary to empty the shop cache. This can be done in the server console using the command

php bin/console cache:clear

Changing the document template

The basic information for the documents (delivery note, invoice etc.) can be maintained directly in the administration in the item Settings > Shop > Documents.
If you want to make bigger changes to the documents, this is possible at file level.

The document templates are structured as follows.
The file base.html.twig in the directory /vendor/shopware/Core/Framework/Resources/views/documents/ serves as a foundation.
This file provides all essential information.
In addition, there is a separate file for each document type (e.g. for invoices the invoice.html.twig), which extends the base.html.twig by the information relevant for the document type.

In the following example the base.html.twig is derived. This file is the foundation for the individual documents and is specified for the individual document types using derived files. For example, the invoice.html.twig extends the base file with the information for the invoice.
All original files are stored in the directory /vendor/shopware/Core/Framework/Resources/views/documents/.

As already explained at the beginning of this article, you should never change the original files directly, but always in a derived file in your own theme.
The path where the derived files are stored is

Please note that it may be necessary to create some of the directories and files.

In the file you can then derive the original file and make your desired adjustments.
The derivation is done using

{% sw_extends '@Framework/documents/base.html.twig' %}

Now you can overwrite individual blocks.
The names of the individual blocks can be found in the standard file under /vendor/shopware/core/Framework/Resources/views/documents/.

The customization of the document templates is applied to all sales channels, regardless of the activation of the theme.
If the customization is only to be used for individual sales channels, it is necessary to restrict this within the customization.

Add missing information to the documents

You can specify the company's email address and website in the settings of a document. However, these are not printed on the documents when using the default template. To add them, you will need to modify base.html.twig. The derivation is done in the directory custom/plugins/YourTheme/src/Resources/views/documents/.
If the file and/or directory does not yet exist, create it accordingly.

Add the following to the file:

{% sw_extends '@Framework/documents/base.html.twig' %}

{% block document_footer_first_column %}
    {{ parent() }}
        {% block document_footer_companyEmail %}
            {% if config.companyEmail %} 
                <li class="bold">E-Mail</li>
                <li class&amp;amp;gt;<a href="mailto:{{ config.companyEmail }}">{{ config.companyEmail }}</a></li>
            {% endif %}
        {% endblock %}
        {% block document_footer_companyUrl %}
            {% if config.companyUrl  %} 
                <li class="bold">Webseite</li>
            <li ><a href="{{ config.companyUrl }}"> {{ config.companyUrl }}</a></li>
            {% endif %}
        {% endblock %}
{% endblock %}

It may then be necessary to empty the shop cache. You can do this using the console with the command

php bin/console cache:clear

or in Admin under Settings > System > Caches & Indexes > Clear Caches.

Restrict adjustment to individual sales channels

Restriction to individual sales channels is possible, e.g. by using an IF query within the derived file.

As an example, a derivation can look like this:

{% sw_extends '@Framework/documents/base.html.twig' %}
{% block document_base %}
   {% if order.salesChannelId == "1438751ce3f0b496bbea293e096aec1fb" %}
      Test 123
   {% else %}
      {{ parent() }}
   {% endif %}
{% endblock %}

In the above example, the ID of the sales channel is used to define through an IF whether the entire document_base block should be overwritten.
If the ID matches, the content is replaced by a test 123.
If the ID does not match, the

{{ parent() }}

the block from the parent file is included.

You can find the ID of the sales channel in the database in the table "sales_channel_translation" from the column "sales_channel_id". Please note that the prefixed "0x" does not belong to the ID and must not be included in the template.

Show custom fields in the storefront

Depending on where you want to show the custom field in the storefront, it is important to choose the right kind of custom field. This can be done by selecting the field use for and is explained in detail in the documentation of the custom fields.

As an example, we would like to show an custom field at product level. The content is to be included on the product details page in the description tab.

For this purpose, the file description.html.twig must be adapted.
Therefore a derivation of the file description.html.twig is needed now.
This is stored in the directory /custom/plugins/YourTheme/src/Resources/views/storefront/page/product-details/
filed. If the directory path or file does not exist, create it.

The derivation in the file starts with the line

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

The further content of the file depends on where the content of the additional field should be displayed.
In our example, this should be done below the description text.
In the next step it is therefore necessary to include the original content of the block page_product_detail_description_content_text.
This is possible using the

{% block page_product_detail_description_content_text %}

as well as

{{ parent() }}


For the integration of the custom field

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

is used.
You can find the technical name in the settings of the additional field. This starts with custom_ in the standard system.

The complete, derived file description.html.twig looks like this.

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

{% block page_product_detail_description_content_text %}
    {{ parent() }}
    {{ page.product.translated.customFields.technischer_name_zusatzfeld }}
{% endblock %}

Structure of the variables

The variables of the custom fields consist on the one hand of the general part and on the other hand of the technical name. The general part depends on the area for which the custom field was made available.
Please note that the availability also depends on the type of page you are on.
To get a list of all available variables, use the dump function.

{{ }}

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

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

Freitextfelder zu Kunden sind nur verfügbar, wenn der Kunde eingeloggt ist.
{{ page.customer.customFields.technischer_name_zusatzfeld }}
{{ context.customer.customFields.technischer_name_zusatzfeld }}
Über die Variable {{ context... }} ist bei eingeloggten Kunden an vielen Stellen die Information verfügbar.

{{ page.address.customFields.technischer_name_zusatzfeld }}

{{ context.salesChannel.translated.customFields.technischer_name_zusatzfeld }}

Was this article helpful?