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, which can be created in 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 
/vendor/shopware/storefront/Resources/views/storefront.
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
custom/plugins/YourTheme/src/Resources/views/documents/

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.

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.

Was this article helpful?