liip/theme-bundle

Provides theming support for #Symfony2 Bundles

Theme Bundle

This project is not longer maintained and recommends to use SyliusThemeBundle instead for support of Symfony 5 and Twig 3. For migration have a look at Migrate to SyliusThemeBundle., _(*1)

This bundle provides you the possibility to add themes to each bundle. In your bundle directory it will look under Resources/themes/<themename> or fall back to the normal Resources/views if no matching file was found., _(*2)

, _(*3)

Installation

Installation is a quick (I promise!) 3 step process:, _(*4)

1. Download LiipThemeBundle
2. Enable the Bundle
3. Import LiipThemeBundle routing

Step 1: Install LiipThemeBundle with composer

Run the following composer require command:, _(*5)

``` bash $ php composer.phar require liip/theme-bundle, <sub>(*6)</sub>

### Step 2: Enable the bundle

Finally, enable the bundle in the kernel:

``` php
<?php
// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new Liip\ThemeBundle\LiipThemeBundle(),
    );
}

Step 3: Import LiipThemeBundle routing files

Now that you have activated and configured the bundle, all that is left to do is import the LiipThemeBundle routing files., <sub>(*7)</sub>

In YAML:, <sub>(*8)</sub>

``` yaml, <sub>(*9)</sub>

app/config/routing.yml

liip_theme: resource: "@LiipThemeBundle/Resources/config/routing.xml" prefix: /theme, <sub>(*10)</sub>

Or if you prefer XML:

``` xml
<!-- app/config/routing.xml -->
<import resource="@LiipThemeBundle/Resources/config/routing.xml" prefix="/theme" />

Configuration

You will have to set your possible themes and the currently active theme. It is required that the active theme is part of the themes list., <sub>(*11)</sub>

``` yaml, <sub>(*12)</sub>

app/config/config.yml

liip_theme: themes: ['standardTheme', 'winter_theme', 'weekend'] active_theme: 'standardTheme', <sub>(*13)</sub>

### Device specific themes/templates

You can provide specific themes or even templates for different devices (like: desktop, tablet, phone, plain). Set option ```autodetect_theme``` to true for setting ```current_device``` parameter based on the user agent:

``` yaml
# app/config/config.yml
liip_theme:
    autodetect_theme: true

Then in path_patterns you can use %%current_device%% parameter (with your device type as value), <sub>(*14)</sub>

``` yaml, <sub>(*15)</sub>

app/config/config.yml

liip_theme: path_patterns: app_resource: - %%app_path%%/themes/%%current_theme%%/%%current_device%%/%%template%% - %%app_path%%/themes/fallback_theme/%%current_device%%/%%template%% - %%app_path%%/views/%%current_device%%/%%template%%, <sub>(*16)</sub>

Optionally ``autodetect_theme`` can also be set to a DIC service id that implements
the ``Liip\ThemeBundle\Helper\DeviceDetectionInterface`` interface.

### Get active theme information from cookie

If you want to select the active theme based on a cookie you can add:

``` yaml
# app/config/config.yml
liip_theme:
    cookie:
        name: NameOfTheCookie
        lifetime: 31536000 # 1 year in seconds
        path: /
        domain: ~
        secure: false
        http_only: false

Disable controller based theme switching

If your application doesn't allow the user to switch theme, you can deactivate the controller shipped with the bundle:, <sub>(*17)</sub>

``` yaml, <sub>(*18)</sub>

app/config/config.yml

liip_theme: load_controllers: false, <sub>(*19)</sub>

### Theme Cascading Order

The following order is applied when checking for templates that live in a bundle, for example `@BundleName/Resources/template.html.twig`
with theme name ``phone`` is located at:

1. Override themes directory: `app/Resources/themes/phone/BundleName/template.html.twig`
2. Override view directory: `app/Resources/BundleName/views/template.html.twig`
3. Bundle theme directory: `src/BundleName/Resources/themes/phone/template.html.twig`
4. Bundle view directory: `src/BundleName/Resources/views/template.html.twig`

For example, if you want to integrate some TwigBundle custom error pages regarding your theme
architecture, you will have to use this directory structure :
`app/Resources/themes/phone/TwigBundle/Exception/error404.html.twig`

The following order is applied when checking for application-wide base templates, for example `::template.html.twig`
with theme name ``phone`` is located at:

1. Override themes directory: `app/Resources/themes/phone/template.html.twig`
2. Override view directory: `app/Resources/views/template.html.twig`

#### Change Theme Cascading Order

You able change cascading order via configurations directives: `path_patterns.app_resource`, `path_patterns.bundle_resource`, `path_patterns.bundle_resource_dir`. For example:

``` yaml
# app/config/config.yml
liip_theme:
    path_patterns:
        app_resource:
            - %%app_path%%/themes/%%current_theme%%/%%template%%
            - %%app_path%%/themes/fallback_theme/%%template%%
            - %%app_path%%/views/%%template%%
        bundle_resource:
            - %%bundle_path%%/Resources/themes/%%current_theme%%_%%current_device%%/%%template%%
            - %%bundle_path%%/Resources/themes/%%current_theme%%/%%template%%
            - %%bundle_path%%/Resources/themes/fallback_theme/%%template%%
        bundle_resource_dir:
            - %%dir%%/themes/%%current_theme%%/%%bundle_name%%/%%template%%
            - %%dir%%/themes/fallback_theme/%%bundle_name%%/%%template%%
            - %%dir%%/%%bundle_name%%/%%override_path%%

Cascading Order Patterns Placeholders

Change Active Theme

For that matter have a look at the ThemeRequestListener., <sub>(*20)</sub>

If you are early in the request cycle and no template has been rendered you can still change the theme without problems. For this the theme service exists at:, <sub>(*21)</sub>

``` php $activeTheme = $container->get('liip_theme.active_theme'); echo $activeTheme->getName(); $activeTheme->setName("phone");, <sub>(*22)</sub>

### Theme Specific Controllers

In some situations, a different template is not enough and you need a different 
controller for a specific theme. We encountered this with A/B testing. Do not 
abuse this feature and check whether your use case is still to be considered a 
theme.

This feature is not active by default as there is an additional request 
listener involved. Enable it by setting `theme_specific_controllers` in your 
configuration:


```yaml
# app/config/config.yml
liip_theme:
    # ...
    theme_specific_controllers: true

Now you can configure controllers per theme in your routing file:, <sub>(*23)</sub>

my_route:
    path: /x/y
    defaults:
        _controller: my_service:fooAction
        theme_controllers:
            a: my_other_service:fooAction
            b: App:Other:foo

As usual, you can use both the service notation or the namespace notation for the controllers. Just specify the controller by theme under the key theme_controllers., <sub>(*24)</sub>

Assetic integration

Because of the way the LiipThemeBundle overrides the template locator service, assetic will only dump the assets of the active theme., <sub>(*25)</sub>

In order to dump the assets of all themes enable the assetic_integration option:, <sub>(*26)</sub>

# app/config/config.yml
liip_theme:
    # ...
    assetic_integration: true

This will override the Twig formula loader and iterate over all of the themes, ensuring that all of the assets are dumped., <sub>(*27)</sub>

Note that this only works with AsseticBundle 2.1 or higher., <sub>(*28)</sub>

Override the Device Detection

It is possible to override the service used for the device detection. Make sure to either extend DeviceDetection or implement DeviceDetectionInterface:, <sub>(*29)</sub>

# app/config/config.yml
services:
    my_devcice_detection:
        class: SomeClass

liip_theme:
    # ...
    device_detection: my_devcice_detection

Migrate to SyliusThemeBundle

This will show you the stepts to switch from the LiipThemeBundle to SyliusThemeBundle., <sub>(*30)</sub>

Remove the old theme bundle and install the SyliusThemeBundle:

# Remove old theme-bundle
composer remove liip/theme-bundle --no-update

# Install new theme-bundle
composer require sylius/theme-bundle:"^2.0"

Remove old configuration

The old liip_theme.yaml configuration needs to be removed:, <sub>(*31)</sub>

-liip_theme:
-    themes: ['awesome']
-    active_theme: 'awesome'

In the next step you see how you configure the awesome theme using the SyliusThemeBundle., <sub>(*32)</sub>

Configure the SyliusThemeBundle:

In order to use the bundle you have to add the following default configuration:, <sub>(*33)</sub>

# ./config/packages/sylius_theme.yaml

sylius_theme:
    sources:
        filesystem: ~

By default, the bundle seeks for the themes in the %kernel.project_dir%/themes directory and looks for a configuration file named composer.json. This can be changed via the yaml configuration:, <sub>(*34)</sub>

sylius_theme:
    sources:
        filesystem:
            filename: theme.json

Convert Theme Configuration

In the SyliusThemeBundle every theme must have its own configuration file in form of a theme.json. Add a theme.json file and add the following minimal configuration:, <sub>(*35)</sub>

{
    "name": "app/awesome"
}

Go to the Theme Configuration Reference for the detailed documentation about the configuration options., <sub>(*36)</sub>

Most likely you have to change the theme name. It is important, that the name matches the naming convention of composer (vendor/name). Furthermore the theme.json has to be moved into the directory for this specific theme., <sub>(*37)</sub>

For example: %kernel.project_dir%/themes/awesome/theme.json, <sub>(*38)</sub>

Update project structure

Your templates have to be placed in a templates directory next to the theme.json file., <sub>(*39)</sub>

For example: %kernel.project_dir%/themes/<theme-name>/templates, <sub>(*40)</sub>

This results in the following project structure:, <sub>(*41)</sub>

ProjectName
├── composer.json
├── assets
├── bin
├── config
├── templates
├── themes
│   ├── awesome
│   │   ├── templates
│   │   │   └── base.html.twig
│   │   └── theme.json
│   └── <theme-name-2>
│       ├── templates
│       │   └── base.html.twig
│       └── theme.json
├── ...
└── ...

As you can see in the project structure, each theme must have their own theme.json configuration file next to the templates directory., <sub>(*42)</sub>

Create ThemeRequestListener

You need to create a ThemeRequestListener to set the theme based on the current $request data:, <sub>(*43)</sub>

use Sylius\Bundle\ThemeBundle\Context\SettableThemeContext;
use Sylius\Bundle\ThemeBundle\Repository\ThemeRepositoryInterface;
use Symfony\Component\HttpKernel\Event\GetResponseEvent;
use Symfony\Component\HttpKernel\HttpKernelInterface;

final class ThemeRequestListener
{
    /** @var ThemeRepositoryInterface */
    private $themeRepository;

    /** @var SettableThemeContext */
    private $themeContext;

    public function __construct(ThemeRepositoryInterface $themeRepository, SettableThemeContext $themeContext)
    {
        $this->themeRepository = $themeRepository;
        $this->themeContext = $themeContext;
    }

    public function onKernelRequest(GetResponseEvent $event): void
    {
        if (HttpKernelInterface::MASTER_REQUEST !== $event->getRequestType()) {
            // don't do anything if it's not the master request
            return;
        }

        $themeName = 'app/awesome';

        // here you can set the $themeName based on $event->getRequest() object

        $this->themeContext->setTheme(
            $this->themeRepository->findOneByName($themeName)
        );
    }
}

Have a look also at the SyliusThemeBundle Documentation., <sub>(*44)</sub>

Contribution

Active contribution and patches are very welcome. To keep things in shape we have quite a bunch of unit tests. If you're submitting pull requests please make sure that they are still passing and if you add functionality please take a look at the coverage as well it should be pretty high :), <sub>(*45)</sub>

First install dependencies:, <sub>(*46)</sub>

   composer.phar install --dev

This will give you proper results:, <sub>(*47)</sub>

bash phpunit --coverage-text, <sub>(*48)</sub>