BoltCM

Sophisticated, Lightweight and Simple

Jump to docs navigation
Edit on GitHub

Note: You are currently reading the documentation for Bolt 3.0. Looking for the documentation for Bolt 3.2 instead?

Extending » Basics » Extending Twig

Twig functions, filters, and template paths can be added to an extension using several built-in registration functions, and Twig templates can be simply rendered.

Note: This section is best used for Twig functionality for simple extensions that do a limited amount. For more complex extensions and functionality, you may find it useful to move your Twig logic to a class file and import the \Bolt\Extension\TwigTrait.

Rendering Twig Templates

Bolt provides a helper function for rendering Twig templates called renderTemplate().

$context = [
    'name' => 'Kenny Koala',
    'home' => 'Gum Tree Lane',
];
$this->renderTemplate('template.twig', $context);

When using this function, Bolt will automatically add the extension's templates/ directory to the Twig path array. If you need other directories or Twig namespaces added, see the Registering Twig Paths section below.

Registering Twig Functions

Twig functions are registered by creating a protected function called registerTwigFunctions() that returns an array.

Each array element's key will be the desired Twig function name as used in Twig, e.g. {{ koala() }}

The array value can either be a string or an array:

Registering Twig Filters

Twig filters are registered by creating a protected function called registerTwigFilters() that returns an array.

Each array element's key will be the desired Twig function name as used in Twig, e.g. {{ record.title|koala }}

The array value can either be a string, or an array:

Registering Twig Paths

When using the renderTemplate() function, Bolt will automatically add the extension's templates/ directory to the Twig path array, if it hasn't been added already.

However, this can be customised with the registerTwigPaths() function by returning an array of paths relative to the extension itself.

Additionally, each path can specify an array of options:

Example Extension

namespace Bolt\Extension\DropBear\KoalaCatcher;

use Bolt\Asset\File\JavaScript;
use Bolt\Extension\SimpleExtension;

/**
 * An extension for catching koalas.
 *
 * @author Kenny Koala <kenny@dropbear.com.au>
 */
class KoalaCatcherExtension extends SimpleExtension
{
    /**
     * {@inheritdoc}
     */
    protected function registerTwigFunctions()
    {
        return [
            'koala'    => 'koalaFunction',
            'kangaroo' => ['kangarooFunction', ['is_safe' => ['html']]]
        ];
    }

    /**
     * {@inheritdoc}
     */
    protected function registerTwigFilters()
    {
        return [
            'koala'    => 'koalaFilter',
            'kangaroo' => ['kangarooFilter', ['is_safe' => ['html']]]
        ];
    }

    /**
     * {@inheritdoc}
     */
    protected function registerTwigPaths()
    {
        return [
            'templates/normal',
            'templates/special' => ['position' => 'prepend', 'namespace' => 'DropBear']
        ];
    }

    /**
     * Render and return the Twig file templates/normal/koala.twig
     *
     * @return string
     */
    public function koalaFunction()
    {
        return $this->renderTemplate('koala.twig');
    }

    /**
     * Koala-case strings.
     *
     * @param string $input
     *
     * @return string
     */
    public function koalaFilter($input)
    {
        return strtolower($input);
    }

    /**
     * Render and return the Twig file templates/special/skippy.twig
     *
     * @return string
     */
    public function kangarooFunction()
    {
        return $this->renderTemplate('@DropBear/skippy.twig');
    }

    /**
     * Kangaroo-case strings.
     *
     * @param string $input
     *
     * @return string
     */
    public function kangarooFilter($input)
    {
        return ucwords($input);
    }
}

Note: Using these methods you can not add variables to Twig's global scope. If you have need of global Twig variables, that are available in all templates, see the section Extending the 'Global Twig' environment for instructions on how to do this.


Couldn't find what you were looking for? We are happy to help you in the forum, on Slack or on IRC.
Spotted a typo, or have something to add? Edit this page on GitHub.