Download the PHP package ju1ius/twig-buffers-extension without Composer
On this page you can find all versions of the php package ju1ius/twig-buffers-extension. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package twig-buffers-extension
Twig Buffers Extension
This extension allows you to define buffers into which you can insert content from another part of the template or from included, embedded or child templates. It is similar in functionality to Blade stacks.
Installation
Basic usage
Let's start with what will probably be the most frequent use case.
Given the following templates:
Rendering page.html.twig
Will output:
The buffer tag
The buffer tag does two things:
- it opens a named buffer if a buffer of the same name doesn't exist.
- it references the named buffer so that it's content can be displayed at the tag's location.
A named buffer can therefore be referenced several times:
By default, the contents of the buffer are joined using the empty string, but you can customize the joining string:
You can also provide a «final glue», similarly to the join
twig filter:
As we just saw, even when using automatic escaping, the joining strings will not be automatically escaped. You'll have to escape them yourself if they come from untrusted sources:
Inserting content into buffers
This is done via the append
and prepend
tags.
They share the same syntax apart from their respective tag names.
As with the block
tag, you can use a short or a long syntax:
As the name implies, the append
tag appends content to the buffer.
The prepend
tag however, doesn't prepend content to the buffer,
but instead appends content to the head of the buffer:
Trying to insert content into a buffer that does not exist or is not
in scope will throw an UnknownBuffer
exception.
Inserting to potentially undefined buffers
If you want to insert content into a buffer that may not exist or may not be in scope, you have two solutions:
1.
If `my_buffer` doesn't exist or is not [in scope](#the-scope-of-a-buffer),
this is a no-op.
2.
If `my_buffer` doesn't exist or is not [in scope](#the-scope-of-a-buffer),
first open the buffer, then insert content into it.
Unique insertions
You can tag insertions with a unique id in order to prevent the same content to be inserted more than once.
Clearing the contents of a buffer
You can use the clear_buffer
function:
Attempting to clear the content of a buffer that does not exist or is not
in scope will throw an UnknownBuffer
exception.
Checking if a buffer exists
You can use the buffer
test:
The buffer
test will return true
if
the buffer exists and is in scope.
Checking if a buffer is empty
You can use the empty_buffer
test:
Or for a more practical example:
The empty_buffer
test will return true
if:
- the buffer exists and is empty
- the buffer doesn't exist or is not in scope.
The scope of a buffer
When a template contains a {% buffer %}
tag,
the corresponding buffers are opened as soon as the template begins to render.
Once opened, a buffer remains available until the end of the topmost render call.
Therefore, a buffer is available:
- in the whole template it is referenced in and in all it's included, embedded or child templates.
- in all subsequent siblings of the template it is referenced in.
To clarify, lets look at some examples.
The following works because of rule n°1:
The following also works because of rule n°1:
The following works because of rule n°2:
However, because of rule n°2, the following does not work: