themes.rst

.. index::
   single: Themes

Themes

Theming is a method of customizing how your channels look like in Sylius. Each channel can have a different theme.

What is the purpose of using themes?

There are some criteria that you have to analyze before choosing either :doc:`standard Symfony template overriding </customization/template>` or themes.

When you should choose standard template overriding:

• you have only one channel
• or you do not need different looks/themes on each of you channels
• you need only basic changes in the views (changing colors, some blocks rearranging)

When you should use Sylius themes:

• you have more than one channel for a single Sylius instance
• and you want each channel to have their own look and behaviour
• you change a lot of things in the views

How to enable themes in a project?

To use themes inside of your project you need to add these few lines to your config/packages/sylius_theme.yaml.

sylius_theme:
    sources:
        filesystem:
            directories:
                 - "%kernel.project_dir%/themes"

How to create themes?

Let's see how to customize the login view inside of your custom theme.

1. Inside of the themes/ directory create a new directory for your theme:

Let it be CrimsonTheme/ for instance.

2. Create composer.json for your theme:

{
    "name": "acme/crimson-theme",
    "authors": [
        {
            "name": "James Potter",
            "email": "prongs@example.com"
        }
    ],
    "extra": {
        "sylius-theme": {
            "title": "Crimson Theme"
        }
    }
}

3. Install theme assets

Theme assets are installed by running the sylius:theme:assets:install command, which is supplementary for and should be used after assets:install.

bin/console sylius:theme:assets:install

The command run with --symlink or --relative parameters creates symlinks for every installed asset file, not for entire asset directory (eg. if AcmeBundle/Resources/public/asset.js exists, it creates symlink public/bundles/acme/asset.js leading to AcmeBundle/Resources/public/asset.js instead of symlink public/bundles/acme/ leading to AcmeBundle/Resources/public/). When you create a new asset or delete an existing one, it is required to rerun this command to apply changes (just as the hard copy option works).

Note

Whenever you install a new bundle with assets you will need to run sylius:theme:assets:install again to make sure they are accessible in your theme.

4. Customize a template:

In order to customize the login view you should take the content of @SyliusShopBundle/views/login.html.twig file and ...

• Before theme-bundle v2, paste it to your theme directory: themes/CrimsonTheme/SyliusShopBundle/views/login.html.twig (There are more informations in the official documentation about theme structure v1.5.1)
• From theme-bundle v2, paste it to your theme directory: themes/CrimsonTheme/templates/bundle/SyliusShopBundle/login.html.twig (There are more informations in the official documentation about theme structure v2.0.0)

Let's remove the registration column in this example:

{% extends '@SyliusShop/layout.html.twig' %}

{% form_theme form '@SyliusShop/Form/theme.html.twig' %}

{% block title %}{{ 'sylius.ui.customer_login'|trans }} | {{ parent() }}{% endblock %}

{% block content %}
    {% include '@SyliusShop/Login/_header.html.twig' %}

    {{ sylius_template_event('sylius.shop.login.after_content_header') }}

    <div class="ui padded segment">
        <div class="ui one column very relaxed stackable grid">
            <div class="column">
                {{ sylius_template_event('sylius.shop.login.main_column', _context) }}
            </div>
        </div>
    </div>
{% endblock %}

Tip

Learn more about customizing templates :doc:`here </customization/template>`.

You can check major modifications in theme-bundle structure and configuration here

5. Choose your new theme on the channel:

In the administration panel go to channels and change the theme of your desired channel to Crimson Theme.

6. If changes are not yet visible, clear the cache:

php bin/console cache:clear

Learn more

• Theme - Bundle Documentation.