Twig Components / Twig filters

Note: You are currently reading the documentation for Bolt 5.0. Looking for the documentation for Bolt 5.2 instead?

current¶

date¶

{{ content.datecreated|date("M d, ’y")}}

See the various options for 'date' on the PHP website.

Note: This filter does not display a localized version of the date. Use the {{ localdate }}-filter if you want to display dates in other languages than English.

edit_link¶

Returns the edit link for the record in the Bolt backend.

excerpt¶

The Excerpt filter creates a short, text-only, excerpt of a record or a string. It's useful to get short blurbs of text for overview pages, listings, et cetera. If you pass it a string, it will simply strip out HTML and, reduce it to a given length:

{% set text = "Bonum patria: miserum exilium. Ut optime, secundum" %}
{{ text|excerpt(10) }}

=> Bonum pat…

If you get an excerpt of a Record, Bolt will attempt to get an excerpt that's representative of the Record. If it has a recognisable title, it will start with that, and it will use the other text-fields to complete it. In fact, it's the same function that's used in the Bolt backend, on the dashboard. See also extras.

{% setcontent page = "pages/1" %}
{{ page|excerpt(200) }}

=> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Videsne quam sit magna
dissensio? Cum ageremus, inquit, vitae beatum et eundem supremum diem, scribebamus haec.
Duo Reges: constructio int…

It is also possible to highlight a keyword in an excerpt, which can be used in search results.

{% set keyword = 'ageremus' %}{# this is the keyword you want to highlight #}
{% set include_title = false %}{# this will include the title in the results #}
{% setcontent page = "pages/1" %}
{{ page|excerpt(200, include_title, keyword|default('')) ) }}

=> …consectetur adipiscing elit. Videsne quam sit magna dissensio? Cum <mark>ageremus</mark>,
inquit, vitae beatum et eundem supremum diem, scribebamus haec. Duo Reges: constructio int…

image¶

Use this modifier to create a link to an image of your choosing.

For details, see extras.

json_records¶

Encodes the given array of records into json.

json_decode¶

This method parses a string with JSON into an array / object. It is the opposite of json_encode:

Example:

{% set json_string = '{"selected":"search","zoom":"10","search":"Vienna, Austria","lat":48.2081743,"long":16.3738189}' %}

{% if json_string is json %}
    {{ dump(json_string|json_decode()) }}
{% else %}
    <code>json_string</code> is not valid JSON
{% endif %}

json_encode¶

This method renders an array into a JSON string. It is the opposite of json_decode.

Example:

{% set array = {selected: "search", zoom: "10", search: "Vienna, Austria", lat: 48.2081743, long: 16.3738189 } %}

{{ dump(array|json_encode()) }}

label¶

Returns the label of the field, as defined in the field's contenttypes.yaml definition.

localdate¶

Outputs a localized, readable version of a timestamp.

To check all available date formats, please refer to the official php documentation https://www.php.net/manual/en/function.date.php

    {{ record.publishedAt|localdate }} {# Display published date with default format and locale #}
    {{ record.publishedAt|localdate(format='F j, Y H:i') }} {# Display published date with custom format and default locale #}
    {{ record.publishedAt|localdate(locale='nl') }} {# Display published date with default format and custom locale #}
    {{ record.publishedAt|localdate(format='F j, Y H:i', locale='nl') }} {# Display published date with default format and custom locale #}

    {{ "now"|localdate }} {# Display the current date and time #}

markdown¶

Transforms the given markdown content into HTML content, i.e. parses markdown into HTML.

media¶

Returns the media array associated with the field. Note, this should only be used with image and file fields.

normalize_records¶

Returns an array of normalized records.

order¶

In most cases the results of {% setcontent %} or {{ record|related() }} are in the desired order. In some cases you might want to reorder them, by using the order-filter.

{% set relatedrecords = record|related() %}
<p class="meta">Related content:
    <ul>
    {% for related in relatedrecords|order('publishedAt') %}
        <li><a href="{{ related|link }}">{{ related.title }}</a></li>
    {%  endfor %}
    </ul>
</p>

or:

{# get the 10 latest entries by date, but sort them on the title and subtitle fields #}
{% setcontent entries = "entries" latest limit 10 %}

<ul>
{% for entry in entries|order('title', 'subtitle') %}
    <li><a href="{{ entry|link }}">{{ entry.title }}</a></li>
{%  endfor %}
</ul>

Note: Ordering with the order-filter is case sensitive. This means that 'banana' will come before 'Apple'. If you're sorting on a title or name field and this case sensitivity is undesirable, you can use |order('slug') instead. The slug is always lowercase, so this will normalize the ordering.

ordering using Twig's sort filter.¶

You can also order records using Twig's default sort filter, which may give you finer control over the ordering. For example, you can order the related pages by their group in ascending order like so:

<ul>
{% for page in record|related|sort((a, b) => a|taxonomies['groups'] <=> b|taxonomies['groups']) %}
    <li><a href="{{ page|link }}">{{ page.title }}</a></li>
{% endfor %}
</ul>

Or, to rder them in descending order, simply add |reverse after the sort filter like so:

{% for page in record|related|sort((a, b) => a|taxonomies['groups'] <=> b|taxonomies['groups'])|reverse %}
    <li><a href="{{ page|link }}">{{ page.title }}</a></li>
{% endfor %}
</ul>

plaintext¶

Use this modifier to return a "plaintext" version of the string. For example:

{% set text = "Bonum patria: señor & <em>éxilium</em>!" %}
{{ text|plaintext }}

=> Bonum patria: señor & éxilium!

This returns a string with letters, numbers and common extra characters, but without HTML tags. This makes the output very suited for - for example - use in <title> tags.

The main difference between this filter and |striptags is that the output of this filter is marked as HTML in Twig, meaning that characters like & and ' will not be escaped. If you wish these to be escaped, use |striptags instead.

popup¶

See popup function

preg_replace¶

Makes PHPs preg_replace() function available as twig filter. Example usage:

{{ content.text|preg_replace('/[^a-z]+/', '_') }}

previous and next¶

previous¶

Returns the previous record from the database. By default, |previous finds the left adjacent element for the same contenttype using the record's database id.

{% set record_before = record|previous %}

next¶

Returns the next record from the database. By default, |next finds the right adjacent element for the same contenttype using the record's database id.

{% set record_after = record|next %}

raw¶

If the content contains HTML-fields, they will be rendered with escaped characters by default. If you want to use the HTML as-is, add the raw modifier:

{{ page.tite|raw }}

If we didn't add the raw modifier, all '<' and '>' characters in the body would be output as '&lt;' and '&gt;' respectively. If 'body' is an HTML field in our ContentType, we want it to be output as normal HTML, so we have to add the raw modifier.

related¶

Returns an array of records that are related to the given record.

{% set relatedrecords = record|related() %}
<p class="meta">Related content:
    <ul>
    {% for related in relatedrecords %}
        <li><a href="{{ related|link }}">{{ related|title }}</a></li>
    {%  endfor %}
    </ul>
</p>

related_by_type¶

Returns a two-dimensional array of related records, where the first key is the contenttype.

    [
        'entries' => [ related_entry_1, related_entry_2, ... ],
        'pages' => [ related_page_1, related_page_2, ... ]
    ]

related_first¶

Returns the first of the returned related records.

round, ceil and floor¶

The round modifier can be used to round numbers (or strings containing a numerical-like values) to the nearest integer, which basically means "whole number".

{% set pi = 3.141592 %}

Rounded, Pi is {{ pi|round }} {# "3" #}

The constant Pi is somewhere between {{ pi|round(1, 'floor') }} and {{ pi|round(1, 'ceil') }}
{# "3 and 4" #}

If you need fancier number formatting than this, you can use the built-in Twig number_format-filter. See the docs here.

safestring¶

Use this modifier to return a "safe" version of the string. For example:

{% set text = "Bonum patria: miserum exilium. Ut optime, secundum" %}
{{ text|safestring(true) }}

=> bonum-patria-miserum-exilium-ut-optime-secundum

Characters in the string are converted to lowercase, accented ones are converted to their lowercase ASCII equivalent. Punctuation signs, and trailing space if present, are replaced by hyphens.

You can specify two parameters: strict mode and extrachars.

• Strict mode (boolean, default to false): spaces are converted to hyphens.
• Extra chars (string, default to empty): A string containing extra non-alphabetical characters to keep in result.

{# Default settings #}
{% set text = "Bonum patria: miserum exilium. Ut optime, secundum" %}
{{ text|safestring() }}

=> bonum patria-miserum exilium-ut optime-secundum

{# Strict mode #}
{% set text = "Bonum patria: miserum exilium. Ut optime, secundum" %}
{{ text|safestring(true) }}

=> bonum-patria-miserum-exilium-ut-optime-secundum

{# Keep dots #}
{% set text = "my beautiful image.jpg" %}
{{ text|safestring(true, ".") }}

=> my-beautiful-image.jpg

showimage¶

Use this filter to insert an image in the HTML. You can optionally provide the width and height parameters, like you can do with the thumbnail filter. The parsed image will be cropped using the 'contain' mode.

{{ record.photo|showimage(800, 600) }}
or
{{ showimage("2020-03/foo.jpg", 800, 600) }}

You can also add loading="lazy" in the HTML output:

{{ record.photo|showimage(500, 700, lazy = true) }}

selected¶

Returns all selected records from the content select field. Note, this filter should only be used on select fields that select from a list of Content, as opposed to a list of items.

For a Content select field with multiple: false:

{% set selected_record = record.select_field|selected %}

{{ selected_record.id }} {{ selected_record|title }}<br>

For a Content select field with multiple: true:

{% set selected_records = record.select_field|selected %}

{% for selected_record in selected_records %}
    {{ selected_record.id }} {{ selected_record|title }} <br>
{% endfor %}

shuffle¶

Randomly shuffles the passed array.

shy¶

The "soft hyphenate" filter can be used for strings without spaces, that would otherwise break the layout of your page. By adding these soft hyphens, the browser knows it can wrap to the next line. For example:

|                         |
| Before: {{ file }}      |
| MyVeryLongFilenameWithoutSpacesOrDashesOrWhatever.jpg |
|                         |
| After: {{ file|shy }}   |
| MyVeryLongFilenameWith- |
| outSpacesOrDashesOrWha- |
| tever.jpg               |
|                         |

slug¶

The slug filter can be used to transform any string into a slug-like value. This can be very useful when you're hand-crafting links to categories, pages or other structures where you need a URL-safe representation of a string.

In this example, we build links to all category listing pages:

<ul>
{% for category in app.config.get('taxonomy/categories/options') %}
    <li><a href="/category/{{ category|slug }}">{{ category }}</a></li>
{% endfor %}
<ul>

svg¶

Use this filter to render an inlined SVG image. For example:

{{ content.photo|svg }}

If content.photo is an svg image (see image filter), this filter will output the contents of the svg file as plain HTML, for example:

<svg height="100" width="100">
  <circle cx="50" cy="50" r="40" stroke="black" stroke-width="3" fill="red" />
  Sorry, your browser does not support inline SVG.
</svg>

If the |svg filter is called on a variable that is not an svg image, it will not output anything.

To render an inlined svg, and a standard <img> tag otherwise, use this:

{% if content.photo|split('.')|last == 'svg' %} {# if extension is `.svg` #}
    {{ content.photo|svg }}
{% else %}
    {{ content.photo|showimage }}
{% endif %}

Note:Bolt renders the code inside the .svg file "as is". If your site uses multiple inline .svg's on one page that use the same `id` names, this will make the outputted HTML invalid and may lead to unexpected results.

taxonomies¶

Returns an array of all taxonomies linked to the record.

thumbnail¶

Use this modifier to create a link to an automatically generated thumbnail of a size of your choosing. For example:

<img src="{{ content.image|thumbnail(320, 240) }}">

If content.image is an image in your files/ folder, like foo.jpg, this modifier will output a link like /thumbs/320x240/foo.jpg. This is useful for creating absolute links to a thumbnail, regardless of whether Bolt is installed in the root of your domain, a subdomain or a folder.

The mode of cropping is important if you're requesting a thumbnail that has different proportions than the original image. Valid options for cropping are:

• n ('contain', 'default') - Makes sure you always get an image that fits the specified width and height. The image is not transformed, so it will be resized to fit the boundaries that are necessary.
• m ('max') - Resizes the image to fit within the width and height boundaries without cropping, distorting or altering the aspect ratio, and will also not increase the size of the image if it is smaller than the output size.
• f ('fill') - Resizes the image to fit within the width and height boundaries without cropping or distorting the image, and the remaining space is filled with the background color. The resulting image will match the constraining dimensions.
• s ('stretch') - Stretches the image to fit the constraining dimensions exactly. The resulting image will fill the dimensions, and will not maintain the aspect ratio of the input image.
• c ('crop') - Resizes the image to fill the width and height boundaries and crops any excess image data. The resulting image will match the width and height constraints without distorting the image.

Use the fit parameter like this:

<img src="{{ content.image|thumbnail(width=100, height=100, fit="f") }}">

If you omit the width and height altogether, the thumbnail will use the 'default' size and cropping mode. Remember to add quotes around the cropping mode.

<img src="{{ content.image|thumbnail }}">

title¶

The Title filter creates a short, text-only, title of a record. It'll produce a suitable title-like output that can be used for overview pages, listings, et cetera. It does this, regardless of the actual structure of the ContentType. It looks at fields named 'title' or 'heading', or at the fields used in the slug, but as long as there's any text fields, you'll get a consistent and usable output.

Note: Twig supports named parameters. So, if you want to set the length of the title, without having to explicitly set the locale, you can use this: {{ record|title(length = 100) }}.

translate¶

Returns the field translate into the requested locale.

    {% set image_nl = record.image|translate('nl') %}

Note: The |translate filter will return the field in the requested locale, but it will also change the locale of the record.image itself.

type¶

Returns the field type of the field, as defined in the field's contenttypes.yaml definition.

ucwords¶

Converts the first character of every word into upper case.

url_decode¶

This filter does the opposite of Twig's built-in url_encode filter: It decodes a given URL-encoded string, replacing any %## encoding in the given string. Plus symbols ('+') are decoded to a space character.

{{ "Mot%C3%B6rhead%20and%20Mg%C5%82a%20are%20cool"|url_decode }}

=> Motörhead and Mgła are cool

It works both on plain strings, as well as encoded arrays of URL parameters:

{% set params = {'param1': 'value', 'foo': 'bar', 'qux': 'Motörhead and Mgła are cool'} %}

{{ dump(params) }}
{{ dump(params|url_encode) }}
{{ dump(params|url_encode|url_decode) }}

Note: If you're simply trying to get a parameter from the URL, you might want to use the built-in app.request instead. For example: {{ app.request.get('foo') }}.