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

.. code-block:: yaml

   sylius_theme:
       sources:
           filesystem:
               scan_depth: 1
               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:

.. code-block:: yaml

   {
       "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``.

.. code-block:: bash

   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 is more information in the official documentation about `theme structure v1.5.1 <https://github.com/Sylius/SyliusThemeBundle/blob/v1.5.1/docs/your_first_theme.md#theme-structure>`_)


* From `theme-bundle v2 <https://github.com/Sylius/SyliusThemeBundle/releases/tag/v2.0.0>`_,
  paste it to your theme directory: ``themes/CrimsonTheme/templates/bundles/SyliusShopBundle/login.html.twig``
  (There is more information in the official documentation about `theme structure v2.0.0 <https://github.com/Sylius/SyliusThemeBundle/blob/v2.0.0/docs/your_first_theme.md#theme-structure>`_)

Let's remove the registration column in this example:

.. code-block:: twig

   {% 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 <https://github.com/Sylius/SyliusThemeBundle/blob/master/docs/important_changes.md>`_

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

.. image:: ../../_images/channel_theme.png
   :align: center

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

.. code-block:: bash

   php bin/console cache:clear

Learn more
----------

* `Theme - Bundle Documentation <https://github.com/Sylius/SyliusThemeBundle/blob/master/docs/index.md>`_.