README

Warning - There is many changes between versions 1.0 and 2.0, Read the doc carefully before upgrading !

A basic & efficient White-Label Branding Bundle for Symfony2 (2.7+) that allows you to easily override twig templates (also with PHP templates) & twig globals.

This bundle is inspired by https://github.com/alexandresalome/multisite-bundle. Parts of which have been copyed and/or modified.

Requirements:

FrameworkExtraBundle
TwigBundle

Features

Templates overriding per site
Templates extending per site
Specific configuration per site
Globals overriding per site
Load remote parts (header, footer), and cache them
Declare multiple matching hosts (eg. one for development, one for production)

Installation

Download the bundle via composer

php composer.phar require simonoche/white-label-bundle

Simply load the bundle in you AppKernel.php

# app/AppKernel.php

public function registerBundles()
{
    $bundles = array(

        // your other bundles....

        /* White Label Bundle */
        new Slame\WhiteLabelBundle\SlameWhiteLabelBundle(),

    );
}

Configuration

Add this section to your app/config/config.yml file:

# app/config/config.yml
slame_white_label:
    # Enable/Disable the bundle globally
    enabled: true
    # Your partner list
    partners:
        # Partner 1
        partner1:
            # Enable or disable only this partner
            enable: true
            # Hosts to match
            hosts: [ 'mypartner.website.dev', 'mypartner.mysite.com' ]
            # Parts & Cache
            parts_cache: 86400 # (seconds) 1 day
            remote_parts:
                footer: "http://www.mypartner.com/?template_part=footer"
                header: "http://www.mypartner.com/?template_part=header"
                localfile:  "%kernel.root_dir%/../web/static/partner/test-local.html"
            # The partner's namespace
            namespace: partner1
            # Twig Global Overrides
            globals:
                phone: "08 00 00 00 00"
            # Partner's custom config, accessible via the service @site_context in templates or controllers
            locals:
                register: true
                foor: bar

Twig - Get remote parts

# AcmeDemoBundle::partner1/example_parts.html.twig

{# Get the whole file #}
{{ slame_getRemotePart('header')|raw }}

{# Get a specific DOM node #}
{{ slame_getRemotePart('header', 'body')|raw }}

<div id="container">
    {% block testblock %}
        bla bla
    {% endblock %}
</div>

{# Get the whole file #}
{{ slame_getRemotePart('footer')|raw }}

Twig globals overriding

In each partner's section, you can define the twig globals that you want to be replaced, when the system find a matching partner.

Given your twig configuration is :

# app/config/config.yml
twig:
    # ...
    globals:
        phone: 1234
        name: %example_parameter%
        foo: bar
        gaid: ABCD-1234

If the visitor is browsing your partner's website (hostname) - so at http://partner1.mywebsite.com, the twig global will be automatically replaced by the value of you partner's globals (in this case, {{ phone }} will now display : "08 00 00 00 00")

You don't have to copy every "root" globals. Just the ones you want to be overrided automatically;

Twig templates overriding

If you want to change a template for a specific site, create a similarly named file with branding option in it:

Given your template is AcmeDemoBundle::contact.html.twig.

You can override it with branding by copying it in a subdirectory named by your partner's namespace:

AcmeDemoBundle::partner1/contact.html.twig

Just create the file and it will automatically be loaded in place of the previous one.

This method works with any kind of twig templates (layouts, includes, etc). For example, given your base template (general layout) is ::layout.html.twig (located in app/view/layout.html.twig).

You can easily override it with branding by copying it in a subdirectory named by your partner's namespace:

::partner1/layout.html.twig

Twig templates extending

If you just want to extend a template for a specific site, because you only need to override a few blocks, variables, or so.. Then just create a similarly named file with branding option in it:

Given your template is AcmeDemoBundle::test.html.twig.

You can override it with branding by copying it in a subdirectory named by your partner's namespace:

AcmeDemoBundle::partner1/test.html.twig

Just create the file and it will automatically be loaded in place of the previous one.

Then, you will need to extend the original template. So just extend the template, and don't forget to add a hashtag : # before your template file name. This hashtag indicates that you WANT to load the original file.

# AcmeDemoBundle::partner1/test.html.twig

{# Force extending the original file #}
{% extends "#AcmeDemoBundle::test.html.twig" %}

{# Overriding only some blocks, etc... #}
{% block sidebar %}
    {% set foo = bar %}
    Overriding the sidebar contents...
{% endblock %}

{% block body %}
    The partner's body, etc...
{% endblock %}

Read the site context

From templates, use the global variable site_context, which returns a Slame\WhiteLabelBundle\Branding\SiteContext instance:

Get the whole partner's configuraton {{ site_context.getContext }}

You can also read options from config with: These options correspond to the "locals" section of your partner (in config.yml)

The option register is {{ site_context.option('register') ? 'enabled': 'not enabled' }}

In your controllers, use service site_context:

public function indexAction()
{
    $this->get('site_context')->getOption('register');
}

Warning

Be carefull when playing with includes and extends, as you can be quickly stuck in a non-end loop, if you don't pay attention of what you do :) Read the section Twig templates extending if needed.

simonoche / white-label-bundle

Maintainers

Details