Developed with love by KnpLabs Hire us for your project!
255

LiipThemeBundle

by liip

Provides theming support for #Symfony2 Bundles

Theme Bundle

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.

Build Status

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:

$ php composer.phar require liip/theme-bundle:dev-master

Step 2: Enable the bundle

Finally, enable the bundle in the kernel:

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

In YAML:

# app/config/routing.yml
liip_theme:
    resource: "@LiipThemeBundle/Resources/config/routing.xml"
    prefix: /theme

Or if you prefer 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.

# app/config/config.yml
liip_theme:
    themes: ['web', 'tablet', 'phone']
    active_theme: 'web'

Optional

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

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

It is also possible to automate setting the theme based on the user agent:

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

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

If your application doesn't allow the user to switch theme, you can deactivate
the controller shipped with the bundle:

# app/config/config.yml
liip_theme:
    load_controllers: false

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:

# 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

Placeholder
Representation
Example


%app_path%
Path where application resources are located
app/Resources


%bundle_path%
Path where bundle located, for example
src/Vendor/CoolBundle/VendorCoolBundle


%bundle_name%
Name of the bundle
VendorCoolBundle


%dir%
Directory, where resource should looking first



%current_theme%
Name of the current active theme



%current_device%
Name of the current device type
desktop, phone, tablet, plain


%template%
Template name
view.html.twig


%override_path%
Like template, but with views directory
views/list.html.twig

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:

$activeTheme = $container->get('liip_theme.active_theme');
echo $activeTheme->getName();
$activeTheme->setName("phone");

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:

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

Note that this only works with AsseticBundle 2.1 or higher.

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:

   composer.phar install --dev

This will give you proper results:

phpunit --coverage-text
Copyright (c) 2010-2011 Liip

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
liip_theme:
themes:

# Prototype
theme: []
active_theme: ~
path_patterns:
app_resource:

# Prototype
path: []
bundle_resource:

# Prototype
path: []
bundle_resource_dir:

# Prototype
path: []
cookie:
name: ~
lifetime: 31536000
path: /
domain:
secure: false
http_only: false
autodetect_theme: false
cache_warming: true
load_controllers: true
assetic_integration: false
  • Merge pull request #118 from dantleech/twig_formula_loader
    By lsmith77, 2 years ago
  • Added assetic twig formula loader
    By dantleech, 2 years ago
  • Merge pull request #117 from ruudk/patch-1
    By lsmith77, 2 years ago
  • Typo in Readme
    By ruudk, 2 years ago
  • Merge pull request #115 from XWB/crash
    By lsmith77, 2 years ago
  • Fixed crash in FileLocator
    By XWB, 2 years ago
  • ensure we set the user agent
    By lsmith77, 2 years ago
  • Merge pull request #113 from gtrias/patch-1
    By lsmith77, 2 years ago
  • Removing setCurrentTheme on FileLoctor contstuctor
    By gtrias, 2 years ago
  • Merge pull request #112 from liip/rawkode-bugfix/windows-phone-user-agent-detection
    By lsmith77, 2 years ago
  • minor tweaks
    By lsmith77, 2 years ago
  • Adding expression-language as a depdency - no need to add quirks to the TravisCI configuration
    By , 2 years ago
  • Security bundle needs to be 2.4.* to provide ExpressionFunctionProviderInterface, or symfony/expression-language:2.6.* - probably better going with expression-language rather than an old security-bundle?
    By rawkode, 2 years ago
  • Default env updated to symfony/expression-language:2.4
    By rawkode, 2 years ago
  • Symfony 2.3 framework-bundle doesn't have expression-language as a depdency, so this is needed
    By rawkode, 2 years ago
  • Windows Phone 8 reports user-agent with 'Windows Phone 8.0', so modified pattern match to utilise 'windows phone' rather than 'windows phone os'
    By rawkode, 2 years ago
  • Merge pull request #105 from RubenHarms/patch-1
    By lsmith77, 2 years ago
  • Update README.md
    By , 2 years ago
  • prepare 1.1.x
    By lsmith77, 2 years ago
  • Merge pull request #101 from RuslanZavacky/add-device-type-to-path-config
    By lsmith77, 2 years ago
  • Removed DeviceDetection where it can be optionable.
    By Ruslan Zavacky, 2 years ago
  • Updated documentation
    By Ruslan Zavacky, 2 years ago
  • Added docblocks
    By Ruslan Zavacky, 2 years ago
  • Device type to be used in path configuration
    By Ruslan Zavacky, 2 years ago
  • send slack messages to a different channel
    By lsmith77, 2 years ago
  • Merge pull request #100 from Nyholm/patch-1
    By lsmith77, 2 years ago
  • Added PHP 5.6 and HHVM to travis.yml
    By Nyholm, 2 years ago
  • Merge pull request #99 from dantleech/improved_exception
    By lsmith77, 2 years ago
  • Improved exception message for invalid active theme name
    By dantleech, 2 years ago
  • Merge pull request #94 from codingmusica/bug/cascorder0
    By lsmith77, 2 years ago