README

This Twig extension allows you to "push" content from child views into a named "stack" which can be rendered in another view or layout. This is perfect for many scenarios, like pushing scripts or styles used by components.

This plugin is heavily inspired by filhocodes/twig-stack-extension and refactored to work with Twig ^3.9.0.

Installation

You can install the package via Composer:

composer require futureplc/twig-stack-extension

Setup in your project

First, add the extension to the Twig instance:

$twig->addExtension(new \Future\TwigStackExtension\StackExtension());

Next, we need to modify the output of the content rendered by Twig in order to ensure the stacks are injected into the right place properly.

One way this can be done is by using the custom Environment class provided by the package.

- use Twig\Environment;
+ use Future\TwigStackExtension\Environment;

// ...

$twig = new Environment($loader);

If you don't want to override your Environment, you can manually call the extension on the rendered output.

$result = $twig->render('view.html.twig');

$result = $twig
    ->getExtension(\Future\TwigStackExtension\StackExtension::class)
    ->getStackManager()
    ->replaceStackPlaceholdersWithStackContent($result);

It's all set up and ready to be used.

Usage

In Twig templates, you will have three new tags to use, {% push %} and {% pushonce %} to push content to a named stack, and {% stack %} to render the named stack.

Pushing to a stack

Wrap any content you want "pushed" to the stack each time this part of the Twig template is parsed.

<!-- partial.twig -->
{% push 'scripts' %}
    <script>console.log('Pushed script executed')</script>
{% endpush %}

Using {% push %} will push the contents to the stack every time it is called.

If you want to push only the first time the code is referenced, for example, including a library needed for a component, you can use the {% pushonce %} tag instead.

<!-- components/datepicker.twig -->
<input type="text" class="datepicker" />

{% pushonce 'scripts' %}
    <script src="/path/to/datepicker-lib.js" />
{% endpushonce %}

Rendering a stack

You can use the {% stack %} tag to render the contents of the stack.

<!-- layout.twig -->
<html>
    <head>...</head>
    <body>
        ...
        {% stack 'scripts' %}
    </body>
</html>

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

futureplc / twig-stack-extension

Maintainers

Details