How to wrap HTML code without including new files in Twig?

Question

I have divs with CSS that represent boxes, they wrap html code.

<div class="box indent">
  <div class="padding">
    my code here
  </div>
</div>

I created a "layoutbundle" where every HTML wrapper (such as boxes, tabs, grids, and so on) is put inside separate twig files. In such a way, views on other bundles can be implemented with other layouts.

But I get tired of includes. Every small html wrapper requires an include, and I wonder if there is a simpler way to wrap HTML code.

Let's have an example with a simple box. Actually, I created several files :

A box.html.twig file that contain the box and include the content :

<div class="box indent">
  <div class="padding">
    {% include content %}
  </div>
</div>

Several box-content.html.twig files, containing content of my boxes.

And finally, I create a box in a view by doing :

{%
  include 'AcmeDemoBundle:layout:box.html.twig'
  with {
    'content': 'ReusableBundle:feature:xxx.html.twig'
  }
%}

Is there a way to create wrappers such as :

a) I declare once a new wrapper :

{% wrapperheader "box" %}
    <div class="box indent">
      <div class="padding">
{% endwrapperheader %}

{% wrapperfooter "box" %}
      </div>
    </div>
{% endwrapperfooter %}

b) And then in my pages, I use :

{% wrapper "box" %}
  {# here my content #}
{% endwrapper %}

I think I'll need to add new tag extensions in Twig, but first I want to know if something similar is natively possible.

Answer 1

The block method

This method was proposed by Sebastiaan Stok on GitHub.

This idea uses the block function. It writes the given block contents, and can be called several times.

Wrappers file :

{# src/Fuz/LayoutBundle/Resources/views/Default/wrappers.html.twig #}

{% block box_head %}
    <div class="box indent">
      <div class="padding">
{% enblock %}

{% block box_foot %}
      </div>
    </div>
{% enblock %}

Feature page :

{{ block('box_head') }}
Some content
{{ block('box_foot') }}

---

The wrap extension with macros

This idea was proposed by Charles on GitHub.

First you declare a macro in a macro.html.twig file.

{% macro box(content) %}
    <div class="box indent">
      <div class="padding">
         {{ content | raw }}
      </div>
    </div>
{% endmacro %}

Amd then, instead of calling {{ macros.box('my content') }} (see the doc you develop a {% wrap %} tag that will handle the macro call, with what's between [% wrap %} and {% endwrap %} as parameter.

This extension was easy to develop. I thought it could be hard to access macros, but in fact, they are stored in the context as objects, and calls can be compiled easily.

Just some changes : we will use the following syntax :

{# to access a macro from an object #}
{% wrap macro_object macro_name %}
  my content here
{% endwrap %}

{# to access a macro declared in the same file #}
{% wrap macro_name %}
   macro
{% endwrap %}

In the following code, don't forget to change namespaces if you want to get it work!

First, add the extension in your services.yml:

parameters:
    fuz_tools.twig.wrap_extension.class: Fuz\ToolsBundle\Twig\Extension\WrapExtension

services:
  fuz_tools.twig.wrap_extension:
    class: '%fuz_tools.twig.wrap_extension.class%'
    tags:
      - { name: twig.extension }

Inside your bundle, create a Twig directory.

Add the extension, it will return the new TokenParser (in english: it will declare the new tag).

Twig/Extension/WrapExtension.php:

<?php

// src/Fuz/ToolsBundle/Twig/Extension/WrapExtension.php

namespace Fuz\ToolsBundle\Twig\Extension;

use Fuz\ToolsBundle\Twig\TokenParser\WrapHeaderTokenParser;
use Fuz\ToolsBundle\Twig\TokenParser\WrapFooterTokenParser;
use Fuz\ToolsBundle\Twig\TokenParser\WrapTokenParser;

class WrapExtension extends \Twig_Extension
{

    public function getTokenParsers()
    {
        return array (
                new WrapTokenParser(),
        );
    }

    public function getName()
    {
        return 'wrap';
    }

}

Then add the TokenParser itself, it will be met when the parser will find a {% wrap %} tag. This TokenParser will check if the tag is called correctly (for our example, it has 2 parameters), store those parameters and get the content between {% wrap %} and {% endwrap %}`.

Twig/TokenParser/WrapTokenParser.php:

<?php

// src/Fuz/ToolsBundle/Twig/TokenParser/WrapTokenParser.php

namespace Fuz\ToolsBundle\Twig\TokenParser;

use Fuz\ToolsBundle\Twig\Node\WrapNode;

class WrapTokenParser extends \Twig_TokenParser
{

    public function parse(\Twig_Token $token)
    {
        $lineno = $token->getLine();
        $stream = $this->parser->getStream();

        $object = null;
        $name = $stream->expect(\Twig_Token::NAME_TYPE)->getValue();

        if ($stream->test(\Twig_Token::BLOCK_END_TYPE))
        {
            if (!$this->parser->hasMacro($name))
            {
                throw new \Twig_Error_Syntax("The macro '$name' does not exist", $lineno);
            }
        }
        else
        {
            $object = $name;
            $name = $stream->expect(\Twig_Token::NAME_TYPE)->getValue();
        }

        $this->parser->getStream()->expect(\Twig_Token::BLOCK_END_TYPE);
        $body = $this->parser->subparse(array ($this, 'decideWrapEnd'), true);
        $this->parser->getStream()->expect(\Twig_Token::BLOCK_END_TYPE);

        return new WrapNode($object, $name, $body, $token->getLine(), $this->getTag());
    }

    public function decideWrapEnd(\Twig_Token $token)
    {
        return $token->test('endwrap');
    }

    public function getTag()
    {
        return 'wrap';
    }

}

Next, we need a compiler (a Node in the twig dialect), it will generate the PHP code associated with our {% wrap %} tag.

This tag is an alias of {{ macro_object.box(content) }}, so I wrote that line in a template and watched the resulting code in the resulting generated php file (stored in your app/cache/dev/twig directory). I got :

echo $this->getAttribute($this->getContext($context, "(macro object name)"), "(name)", array("(body)"), "method");

So my compiler became :

Twig/Node/WrapNode.php:

<?php

// src/Fuz/ToolsBundle/Twig/Node/WrapNode.php

namespace Fuz\ToolsBundle\Twig\Node;

class WrapNode extends \Twig_Node
{

    public function __construct($object, $name, $body, $lineno = 0, $tag = null)
    {
        parent::__construct(array ('body' => $body), array ('object' => $object, 'name' => $name), $lineno, $tag);
    }

    public function compile(\Twig_Compiler $compiler)
    {
        $compiler
           ->addDebugInfo($this)
           ->write('ob_start();');

        $compiler
           ->addDebugInfo($this)
           ->subcompile($this->getNode('body'));

        if (is_null($this->getAttribute('object')))
        {
            $compiler
               ->write(sprintf('echo $this->get%s(ob_get_clean());', $this->getAttribute('name')) . "\n");
        }
        else
        {
            $compiler
               ->write('echo $this->getAttribute($this->getContext($context, ')
               ->repr($this->getAttribute('object'))
               ->raw('), ')
               ->repr($this->getAttribute('name'))
               ->raw(', array(ob_get_clean()), "method");')
               ->raw("\n");
        }
    }

}

Note : to know how work the subparsing / subcompiling, I read the spaceless extension source code.

That's all! We get an alias that let us use macros with a large body. To try it:

macros.html.twig:

{% macro box(content) %}
    <div class="box indent">
      <div class="padding">
         {{ content | raw }} {# Don't forget the raw filter! #}
      </div>
    </div>
{% endmacro %}

some layout.html.twig:

{% import "FuzLayoutBundle:Default:macros.html.twig" as macros %}

{% wrap macros box %}
test
{% endwrap %}

{% macro test(content) %}
some {{ content | raw }} in the same file
{% endmacro %}

{% wrap test %}
macro
{% endwrap %}

Outputs:

    <div class="box indent">
      <div class="padding">
test
      </div>
    </div>

some macro in the same file

---

The wrapperheader, wrapperfooter, wrapper extension

This method is the one I tell you about in my question. You can read / implement it if you want to train yourself with token parsers, but functionnaly, that's less nice than the previous method.

In a wrapper.html.twig file, you declare all wrappers :

{% wrapperheader box %}
    <div class="box">
{% endwrapper %}
{% wrapperfooter box %}
    </div>
{% endwrapperfooter %}

In your features twig files, you use your wrappers :

{% wrapper box %}
This is my content
{% endwrapper %}

The following extension has 3 issues :

• There is no way to store data (such as context variables) in the Twig Environnement. So when you define a {% wrapperheader NAME %}, you have basically no clean way to check if a header for NAME is already defined (in this extension, I use static properties).

• When you include a twig file, it is parsed at runtime, not immediately (I mean, the included twig template is parsed while the generated file is executed, and not when the include tag is parsed). So that's not possible to know if a wrapper exists on a previousely included file when you parse the {% wrapper NAME %} tag. If your wrapper does not exist, this extension just displays what's between {% wrapper %} and {% endwrapper %} without any notice.

• The idea of this extension is : when the parser meet a wrapperheader and wrapperfooter tag, the compiler store the content of the tag somewhere for a later use with the wrapper tag. But the twig context is passed to {% include %} as a copy, not by reference. So that's not possible to store the {% wrapperheader %} and {% wrapperfooter %} information inside that context, for an usage at upper level (in files that include files). I needed to use a global context too.

Here is the code, take care to change your namespaces.

First we need to create an extension that will add new token parsers to Twig.

Inside services.yml of a bundle, add the following lines to activate the extension :

parameters:
    fuz_tools.twig.wrapper_extension.class: Fuz\ToolsBundle\Twig\Extension\WrapperExtension

services:
  fuz_tools.twig.wrapper_extension:
    class: '%fuz_tools.twig.wrapper_extension.class%'
    tags:
      - { name: twig.extension }

Inside your bundle, create a Twig directory.

Create the following Twig\Extension\WrapperExtension.php file :

<?php

// src/Fuz/ToolsBundle/Twig/Extension/WrapperExtension.php

namespace Fuz\ToolsBundle\Twig\Extension;

use Fuz\ToolsBundle\Twig\TokenParser\WrapperHeaderTokenParser;
use Fuz\ToolsBundle\Twig\TokenParser\WrapperFooterTokenParser;
use Fuz\ToolsBundle\Twig\TokenParser\WrapperTokenParser;

class WrapperExtension extends \Twig_Extension
{

    public function getTokenParsers()
    {
        return array(
            new WrapperHeaderTokenParser(),
            new WrapperFooterTokenParser(),
            new WrapperTokenParser(),
        );
    }

    public function getName()
    {
        return 'wrapper';
    }

}

Now we need to add the token parsers : our syntax is {% wrapper NAME %} ... {% endwrapper %} and the same with wrapperheader and wrapperfooter. So those token parsers are used to declare the tags, to retrive the wrapper's NAME, and to retrieve the body (what's between wrapper and endwrapper`).

The token parser for wrapper: Twig\TokenParser\WrapperTokenParser.php:

<?php

// src/Fuz/ToolsBundle/Twig/TokenParser/WrapperTokenParser.php

namespace Fuz\ToolsBundle\Twig\TokenParser;

use Fuz\ToolsBundle\Twig\Node\WrapperNode;

class WrapperTokenParser extends \Twig_TokenParser
{

    public function parse(\Twig_Token $token)
    {
        $stream = $this->parser->getStream();
        $name = $stream->expect(\Twig_Token::NAME_TYPE)->getValue();
        $this->parser->getStream()->expect(\Twig_Token::BLOCK_END_TYPE);
        $body = $this->parser->subparse(array($this, 'decideWrapperEnd'), true);
        $this->parser->getStream()->expect(\Twig_Token::BLOCK_END_TYPE);
        return new WrapperNode($name, $body, $token->getLine(), $this->getTag());
    }

    public function decideWrapperEnd(\Twig_Token $token)
    {
        return $token->test('endwrapper');
    }

    public function getTag()
    {
        return 'wrapper';
    }

}

The token parser for wrapperheader: Twig\TokenParser\WrapperHeaderTokenParser.php:

<?php

// src/Fuz/ToolsBundle/Twig/TokenParser/WrapperHeaderTokenParser.php

namespace Fuz\ToolsBundle\Twig\TokenParser;

use Fuz\ToolsBundle\Twig\Node\WrapperHeaderNode;

class WrapperHeaderTokenParser extends \Twig_TokenParser
{
    static public $wrappers = array ();

    public function parse(\Twig_Token $token)
    {
        $lineno = $token->getLine();
        $stream = $this->parser->getStream();

        $name = $stream->expect(\Twig_Token::NAME_TYPE)->getValue();
        if (in_array($name, self::$wrappers))
        {
            throw new \Twig_Error_Syntax("The wrapper '$name''s header has already been defined.", $lineno);
        }
        self::$wrappers[] = $name;

        $this->parser->getStream()->expect(\Twig_Token::BLOCK_END_TYPE);
        $body = $this->parser->subparse(array($this, 'decideWrapperHeaderEnd'), true);
        $this->parser->getStream()->expect(\Twig_Token::BLOCK_END_TYPE);
        return new WrapperHeaderNode($name, $body, $token->getLine(), $this->getTag());
    }

    public function decideWrapperHeaderEnd(\Twig_Token $token)
    {
        return $token->test('endwrapperheader');
    }

    public function getTag()
    {
        return 'wrapperheader';
    }

}

The token parser for wrapperfooter: Twig\TokenParser\WrapperFooterTokenParser.php:

<?php

// src/Fuz/ToolsBundle/Twig/TokenParser/WrapperFooterTokenParser.php

namespace Fuz\ToolsBundle\Twig\TokenParser;

use Fuz\ToolsBundle\Twig\Node\WrapperFooterNode;

class WrapperFooterTokenParser extends \Twig_TokenParser
{

    static public $wrappers = array ();

    public function parse(\Twig_Token $token)
    {
        $lineno = $token->getLine();
        $stream = $this->parser->getStream();

        $name = $stream->expect(\Twig_Token::NAME_TYPE)->getValue();
        if (in_array($name, self::$wrappers))
        {
            throw new \Twig_Error_Syntax("The wrapper '$name''s footer has already been defined.", $lineno);
        }
        self::$wrappers[] = $name;

        $this->parser->getStream()->expect(\Twig_Token::BLOCK_END_TYPE);
        $body = $this->parser->subparse(array($this, 'decideWrapperFooterEnd'), true);
        $this->parser->getStream()->expect(\Twig_Token::BLOCK_END_TYPE);
        return new WrapperFooterNode($name, $body, $token->getLine(), $this->getTag());
    }

    public function decideWrapperFooterEnd(\Twig_Token $token)
    {
        return $token->test('endwrapperfooter');
    }

    public function getTag()
    {
        return 'wrapperfooter';
    }

}

The token parsers retrieve all the required information, we now need to compile those information into PHP. This PHP code will be generated by the twig engine inside a Twig_Template implementation (you can find generated classes in your cache directory). It generates code in a method, and the context of included files is not available (because the context array is not given by reference). In such a way, this is not possible to access what's inside the included file without a global context. That's why here, I use static attributes... That's not nice at all but I don't know how to avoid them (if you have ideas, please let me know! :)).

Compiler for the wrapper tag : Twig\Nodes\WrapperNode.php

<?php

// src/Fuz/ToolsBundle/Twig/Node/WrapperNode.php

namespace Fuz\ToolsBundle\Twig\Node;

class WrapperNode extends \Twig_Node
{

    public function __construct($name, $body, $lineno = 0, $tag = null)
    {
        parent::__construct(array ('body' => $body), array ('name' => $name), $lineno, $tag);
    }

    public function compile(\Twig_Compiler $compiler)
    {
        $compiler
           ->addDebugInfo($this)
           ->write('if (isset(\\')
           ->raw(__NAMESPACE__)
           ->raw('\WrapperHeaderNode::$headers[')
           ->repr($this->getAttribute('name'))
           ->raw('])) {')
           ->raw("\n")
           ->indent()
           ->write('echo \\')
           ->raw(__NAMESPACE__)
           ->raw('\WrapperHeaderNode::$headers[')
           ->repr($this->getAttribute('name'))
           ->raw('];')
           ->raw("\n")
           ->outdent()
           ->write('}')
           ->raw("\n");

        $compiler
           ->addDebugInfo($this)
           ->subcompile($this->getNode('body'));

        $compiler
           ->addDebugInfo($this)
           ->write('if (isset(\\')
           ->raw(__NAMESPACE__)
           ->raw('\WrapperFooterNode::$footers[')
           ->repr($this->getAttribute('name'))
           ->raw('])) {')
           ->raw("\n")
           ->indent()
           ->write('echo \\')
           ->raw(__NAMESPACE__)
           ->raw('\WrapperFooterNode::$footers[')
           ->repr($this->getAttribute('name'))
           ->raw('];')
           ->raw("\n")
           ->outdent()
           ->write('}')
           ->raw("\n");
    }

}

Compiler for the wrapperheader tag : Twig\Nodes\WrapperHeaderNode.php

<?php

// src/Fuz/ToolsBundle/Twig/Node/WrapperHeaderNode.php

namespace Fuz\ToolsBundle\Twig\Node;

/**
 * @author alain tiemblo
 */
class WrapperHeaderNode extends \Twig_Node
{

    static public $headers = array();

    public function __construct($name, $body, $lineno = 0, $tag = null)
    {
        parent::__construct(array ('body' => $body), array ('name' => $name), $lineno, $tag);
    }

    public function compile(\Twig_Compiler $compiler)
    {
        $compiler
           ->write("ob_start();")
           ->raw("\n")
           ->subcompile($this->getNode('body'))
           ->write(__CLASS__)
           ->raw('::$headers[')
           ->repr($this->getAttribute('name'))
           ->raw('] = ob_get_clean();')
           ->raw("\n");
    }

}

Compiler for the wrapperfooter tag : Twig\Nodes\WrapperFooterNode.php

<?php

// src/Fuz/ToolsBundle/Twig/Node/WrapperFooterNode.php

namespace Fuz\ToolsBundle\Twig\Node;

class WrapperFooterNode extends \Twig_Node
{

    static public $footers = array();

    public function __construct($name, $body, $lineno = 0, $tag = null)
    {
        parent::__construct(array ('body' => $body), array ('name' => $name), $lineno, $tag);
    }

    public function compile(\Twig_Compiler $compiler)
    {
        $compiler
           ->write("ob_start();")
           ->raw("\n")
           ->subcompile($this->getNode('body'))
           ->write(__CLASS__)
           ->raw('::$footers[')
           ->repr($this->getAttribute('name'))
           ->raw('] = ob_get_clean();')
           ->raw("\n");
    }

}

The implementation is ok now. Let's try it!

Create a view named wrappers.html.twig :

{# src/Fuz/LayoutBundle/Resources/views/Default/wrappers.html.twig #}

{% wrapperheader demo %}
HEAD
{% endwrapperheader %}

{% wrapperfooter demo %}
FOOT
{% endwrapperfooter %}

Create a view named what you want.html.twig :

{# src/Fuz/HomeBundle/Resources/views/Default/index.html.twig #}

{% include 'FuzLayoutBundle:Default:wrappers.html.twig' %}

{% wrapper demo %}
O YEAH
{% endwrapper %}

This shows up :

HEAD O YEAH FOOT

Answer 2

There's a fairly straight forward method with Twig variables and macros.

<div class="box indent">
  <div class="padding">
    my code here
  </div>
</div>

Create a macro:

{% macro box(content) %}
    <div class="box indent">
        <div class="padding">
            {{ content }}
        </div>
    </div>
{% endmacro %}

And call it like this:

{% set content %}
    my code here
{% endset %}

{{ _self.box(content) }}

Not particularly elegant but less mountains of code!