Download the PHP package liip/theme-bundle without Composer

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.

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.

Installation

Installation is a quick (I promise!) 3 step process:

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

Step 1: Install LiipThemeBundle with composer

Run the following composer require command:

Step 2: Enable the bundle

Finally, enable the bundle in the kernel:

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.

In YAML:

Or if you prefer XML:

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.

Device specific themes/templates

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

Then in you can use parameter (with your device type as value)

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:

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:

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:

Cascading Order Patterns Placeholders

Change Active Theme

For that matter have a look at the ThemeRequestListener.

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:

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:

Now you can configure controllers per theme in your routing file:

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.

Assetic integration

Because of the way the LiipThemeBundle overrides the template locator service, assetic will only dump the assets of the active theme.

In order to dump the assets of all themes enable the assetic_integration option:

`

This will override the Twig formula loader and iterate over all of the themes, ensuring that all of the assets are dumped.

Note that this only works with AsseticBundle 2.1 or higher.

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:

`

Migrate to SyliusThemeBundle

This will show you the stepts to switch from the LiipThemeBundle to SyliusThemeBundle.

Remove the old theme bundle and install the SyliusThemeBundle:

Remove old configuration

The old liip_theme.yaml configuration needs to be removed:

In the next step you see how you configure the awesome theme using the SyliusThemeBundle.

Configure the SyliusThemeBundle:

In order to use the bundle you have to add the following default configuration:

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:

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:

Go to the Theme Configuration Reference for the detailed documentation about the configuration options.

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.

For example: %kernel.project_dir%/themes/awesome/theme.json

Update project structure

Your templates have to be placed in a templates directory next to the theme.json file.

For example: %kernel.project_dir%/themes/<theme-name>/templates

This results in the following project structure:

As you can see in the project structure, each theme must have their own theme.json configuration file next to the templates directory.

Create ThemeRequestListener

You need to create a ThemeRequestListener to set the theme based on the current $request data:

Have a look also at the SyliusThemeBundle Documentation.

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 :)

First install dependencies:

This will give you proper results: