Install instructions

To install Netgen Layouts, you need to have an existing Symfony full stack installation. For example, Netgen Layouts can be installed on eZ Platform, Sylius or Symfony Demo app or Symfony Website Skeleton.

Use Composer

Execute the following from your installation root:

$ composer require netgen/layouts-standard

Note

If you’re installing Netgen Layouts on eZ Platform, execute the following instead:

$ composer require netgen/layouts-standard netgen/layouts-ezplatform

Activate the bundles

Add the following bundles to your kernel:

new Knp\Bundle\MenuBundle\KnpMenuBundle(),
new FOS\HttpCacheBundle\FOSHttpCacheBundle(),
new Sensio\Bundle\FrameworkExtraBundle\SensioFrameworkExtraBundle(),
new Doctrine\Bundle\MigrationsBundle\DoctrineMigrationsBundle(),
new WhiteOctober\PagerfantaBundle\WhiteOctoberPagerfantaBundle(),
new Netgen\Bundle\ContentBrowserBundle\NetgenContentBrowserBundle(),
new Netgen\Bundle\ContentBrowserUIBundle\NetgenContentBrowserUIBundle(),
new Netgen\Bundle\ContentBrowserEzPlatformBundle\NetgenContentBrowserEzPlatformBundle(),
new Netgen\Bundle\BlockManagerBundle\NetgenBlockManagerBundle(),
new Netgen\Bundle\BlockManagerStandardBundle\NetgenBlockManagerStandardBundle(),
new Netgen\Bundle\BlockManagerUIBundle\NetgenBlockManagerUIBundle(),
new Netgen\Bundle\BlockManagerAdminBundle\NetgenBlockManagerAdminBundle(),

Note

If you’re installing Netgen Layouts on eZ Platform, activate the following bundle too after all of the bundles listed above:

new Netgen\Bundle\EzPublishBlockManagerBundle\NetgenEzPublishBlockManagerBundle(),

Add the following bundle to your kernel only for dev environment:

new Netgen\Bundle\BlockManagerDebugBundle\NetgenBlockManagerDebugBundle(),

Import database tables

Execute the following from your installation root to import Netgen Layouts database tables:

$ php bin/console doctrine:migrations:migrate --configuration=vendor/netgen/layouts-core/migrations/doctrine.yml

Configuration

Starting from version 1.12 of eZ Platform, there is a configuration that caches 404 pages with a low TTL to increase performance. This cache interferes with Netgen Layouts REST API endpoints which return 404 responses in their normal operation workflow.

To disable cache on Netgen Layouts API endpoints, add the following options to app/config/config.yml under the match key of fos_http_cache configuration responsible for caching 404 pages:

attributes:
    _route: "^(?!ngbm_api_|ngcb_api_)"

Routing and assets

Add the following routes to your main routing config file:

netgen_layouts:
    resource: "@NetgenBlockManagerBundle/Resources/config/routing.yml"
    prefix: "%netgen_layouts.route_prefix%"

netgen_content_browser:
    resource: "@NetgenContentBrowserBundle/Resources/config/routing.yml"
    prefix: "%netgen_content_browser.route_prefix%"

Run the following from your installation root to symlink assets:

$ php bin/console assets:install --symlink --relative

Note

If you’re installing Netgen Layouts on eZ Platform, you also need to dump Assetic assets:

$ php bin/console assetic:dump

Adjusting your full views

All of your full views need to extend ngbm.layoutTemplate variable (see below for example). If layout was resolved, this variable will hold the name of the template belonging to the resolved layout. In case when layout was not resolved, it will hold the name of your main pagelayout template (the one your full views previously extended). This makes it possible for your full view templates to be fully generic, that is, not depend whether there is a resolved layout or not:

{% extends ngbm.layoutTemplate %}

{% block content %}
    {# My full view code #}
{% endblock %}

Adjusting your base pagelayout template

To actually display the resolved layout template in your page, you need to modify your main pagelayout template to include a Twig block named layout which wraps everything between your opening and closing <body> tag:

<body>
    {% block layout %}
        {# Other Twig code #}

        {% block content %}{% endblock %}

        {# Other Twig code #}
    {% endblock %}
</body>

There are two goals to achieve with the above Twig block:

  • If no layout could be resolved for current page, your full view templates will just keep on working as before
  • If layout is resolved, it will use the layout block, in which case content Twig block and other Twig code will not be used. You will of course need to make sure that in this case, all your layouts have a full view block in one of the zones which will display your content Twig block from full view templates

Configuring the pagelayout

As written before, Netgen Layouts replaces the pagelayout in your full views with its dynamic variable called ngbm.layoutTemplate. It basically injects itself between rendering of your full view and your pagelayout. Since your full views do not extend from your main pagelayout any more, Netgen Layouts needs to know what was your original full view to fallback to it. You can configure your pagelayout in Netgen Layouts config like this:

netgen_block_manager:
    pagelayout: '@App/pagelayout.html.twig'

Note

If you’re installing Netgen Layouts on eZ Platform, your main pagelayout is taken from existing eZ Platform configuration, so you can skip this step.

Update Varnish VCL configuration

To enable caching and later cache clearing of block and layout HTTP caches, you will need to use Varnish. To make the cache clearing work, you need to modify your Varnish VCL and add the following rules somewhere in your vcl_recv function.

Note

If you’re using eZ Platform and the VCL supplied by it, the best place to put this is in ez_purge function (which is called from vcl_recv), right after if (req.http.X-Location-Id) { ... } block.

For Varnish 3:

if (req.http.X-Layout-Id) {
    ban( "obj.http.X-Layout-Id ~ " + req.http.X-Layout-Id);
    if (client.ip ~ debuggers) {
        set req.http.X-Debug = "Ban done for layout with ID " + req.http.X-Layout-Id;
    }
    error 200 "Banned";
}

if (req.http.X-Block-Id) {
    ban( "obj.http.X-Block-Id ~ " + req.http.X-Block-Id);
    if (client.ip ~ debuggers) {
        set req.http.X-Debug = "Ban done for block with ID " + req.http.X-Block-Id;
    }
    error 200 "Banned";
}

For Varnish 4 and later:

if (req.http.X-Layout-Id) {
    ban("obj.http.X-Layout-Id ~ " + req.http.X-Layout-Id);
    if (client.ip ~ debuggers) {
        set req.http.X-Debug = "Ban done for layout with ID " + req.http.X-Layout-Id;
    }
    return (synth(200, "Banned"));
}

if (req.http.X-Block-Id) {
    ban("obj.http.X-Block-Id ~ " + req.http.X-Block-Id);
    if (client.ip ~ debuggers) {
        set req.http.X-Debug = "Ban done for block with ID " + req.http.X-Block-Id;
    }
    return (synth(200, "Banned"));
}