Twig filters & functions

The following filters and functions are available in Twig via the Frontend application.

The Twig helpers can be registered via the Twig extension that is available as part of the symfony-frontend package.

Filters

• build_version

• excerpt

• fix_url

• slugify

Functions

• all_not_empty

• not_empty

• staging_banner

• table_of_contents

Tests

• is_prod

Filters

build_version

Add a build version to src file in HTML, helping you bust the cache when making changes to CSS and JS files.

Usage:

{{ '/path/to/file' | build_version }}

For example:

{{ '/assets/styles.css' | build_version }}

Returns: /assets/styles.css?v=8b7973c7

This filter attempts to read the file, if the path is not relative then it tries to load the file relative to the document root (defined by the $_SERVER['DOCUMENT_ROOT']). It creates a short 8-character hash of the file to help create a unique version identifier for the file.

excerpt

Cut a string to a maximum length, but cut on the nearest word (so words are not split).

Usage:

{{ 'string' | excerpt(length, more_text) }}

Example:

{{ 'Mary had a little lamb, Its fleece was white as snow' | excerpt(30) }}

Returns: Mary had a little lamb, Its…

fix_url

Fixes a URL by prepending with http:// or https:// so you can safely use it in a hyperlink.

This function only adds the http scheme if required and otherwise will leave the URL untouched.

Usage:

{{ website_url | fix_url(scheme) }}

Example:

{{ 'example.com' | fix_url }}

Returns: https://example.com

By default the https scheme is added if missing. You can also choose the http scheme by adding a second argument:

{{ 'example.com' | fix_url('http') }}

Returns: http://example.com

slugify

Generate a URL friendly slug from a string. This replaces space with dashes and lower-cases the string. It also filters the string and removes any character that is not a unicode letter, number or dash -

Usage:

{{ title | slugify }}

Example:

{{ 'My name is Earl' | slugify }}

Returns: my-name-is-earl

Functions

all_not_empty

Will return true if all of the items passed to it are defined and have non-empty values.

Usage:

<div data-gb-custom-block data-tag="if" data-0='item1' data-1='item1' data-2='item1' data-3='3' data-4='3' data-5='a test string' data-6=', ' data-7=', ' data-8=''>

    <!-- do something -->

</div>

Example that returns true:

<div data-gb-custom-block data-tag="if" data-0='item1' data-1='item1' data-2='1' data-3='1' data-4=', 3, '></div>

Example that returns false:

<div data-gb-custom-block data-tag="if" data-0='item1, ' data-1='item1, ' data-2='' data-3='testing'></div>

not_empty

Will return true if one or more items passed to it are defined and have a non-empty value.

Usage:

{{ not_empty('item1', 3, null, 'a test string', '') }}

Example that returns true:

{{ not_empty('item1', 3, null) }}

Example that returns false:

{{ not_empty(0, '', null) }}

staging_banner

Outputs a staging banner detailing the current environment.

{{ staging_banner(app.environment) }}

This has default styling using the CSS selector .staging-banner. You can easily override this using CSS with a higher specificity. E.g.

div.staging-banner {
  background-color: red;
}

The staging banner also has a class name equal to the current environment.

You can alter the message outputted by passing a second argument. The string '%s' is replaced with the current environment name. E.g.

{{ staging_banner(app.environment, 'Environment: %s') }}

Please note this defaults to expect prod for the production environment. If you use a different production environment name you can pass this as the third argument. E.g.

{{ staging_banner(app.environment, 'You are on %s', live') }}

Tests

is_prod

Note: this may be replaced by a global view strata object

Returns where this is the production (live) environment.

<div data-gb-custom-block data-tag="if"></div>

Please note this defaults to expect prod for the production environment. If you use a different production environment name you can pass this as the second argument. E.g.

<div data-gb-custom-block data-tag="if" data-0='live' data-1='live' data-2='live' data-3='live' data-4='live'></div>

To output content when not on production:

<div data-gb-custom-block data-tag="if"></div>