Twig Functions

Square Online page templates support the following core Twig functions:

attribute	block	country_names	country_timezones	currency_names
cycle	date	html_classes	include	language_names
local_names	max	min	parent	random
range	script_names	source	timezone_names

Square Online page templates support the Twig template language (version 3.x). For your convenience, excerpts of documentation for supported Twig functions are provided here under the BSD 3-Clause “New” or “Revised” License. Copyright © 2009-present by the Twig Team.

attribute

The attribute function can be used to access a “dynamic” attribute of a variable:

{{ attribute(object, method) }}
{{ attribute(object, method, arguments) }}
{{ attribute(array, item) }}

In addition, the defined test can check for the existence of a dynamic attribute:

{{ attribute(object, method) is defined ? 'Method exists' : 'Method does not exist' }}

The resolution algorithm is the same as the one used for the . notation, except that the item can be any valid expression.

block

When a template uses inheritance and if you want to print a block multiple times, use the block function:

<title>{% block title %}{% endblock %}</title>

<h1>{{ block('title') }}</h1>

{% block body %}{% endblock %}

The block function can also be used to display one block from another template:

{{ block("title", "common_blocks.twig") }}

Use the defined test to check if a block exists in the context of the current template:

{% if block("footer") is defined %}
    ...
{% endif %}

{% if block("footer", "common_blocks.twig") is defined %}
    ...
{% endif %}

country_names

The country_names function returns the names of the countries:

{# Afghanistan, Åland Islands, ... #}
{{ country_names()|join(', ') }}

By default, the function uses the current locale. You can pass it explicitly:

{# Afghanistan, Afrique du Sud, ... #}
{{ country_names('fr')|join(', ') }}

Arguments

locale: The locale

country_timezones

The country_timezones function returns the names of the timezones associated with a given country code:

{# Europe/Paris #}
{{ country_timezones('FR')|join(', ') }}

currency_names

The currency_names function returns the names of the currencies:

{# Afghan Afghani, Afghan Afghani (1927–2002), ... #}
{{ currency_names()|join(', ') }}

By default, the function uses the current locale. You can pass it explicitly:

{# afghani (1927–2002), afghani afghan, ... #}
{{ currency_names('fr')|join(', ') }}

Arguments

locale: The locale

cycle

The cycle function cycles on an array of values:

{% set start_year = date() | date('Y') %}
{% set end_year = start_year + 5 %}

{% for year in start_year..end_year %}
    {{ cycle(['odd', 'even'], loop.index0) }}
{% endfor %}

{# outputs

    odd
    even
    odd
    even
    odd
    even
    
#}

The array can contain any number of values:

{% set fruits = ['apple', 'orange', 'citrus'] %}

{% for i in 0..10 %}
    {{ cycle(fruits, i) }}
{% endfor %}

{# outputs

    apple
    orange
    citrus
    apple
    orange
    citrus
    apple
    orange
    citrus
    apple
    orange

#}

Arguments

values: The list of values to cycle on
position: The cycle position

date

Converts an argument to a date to allow date comparison:

{% if date(user.created_at) < date('-2days') %}
    {# do something #}
{% endif %}

You can pass a timezone as the second argument:

{% if date(user.created_at) < date('-2days', 'Europe/Paris') %}
    {# do something #}
{% endif %}

If no argument is passed, the function returns the current date:

{% if date(user.created_at) < date() %}
    {# always! #}
{% endif %}

Arguments

date: The date
timezone: The timezone

html_classes

The html_classes function returns a string by conditionally joining class names together:

<p class="{{ html_classes('a-class', 'another-class', {
    'errored': object.errored,
    'finished': object.finished,
    'pending': object.pending,
}) }}">How are you doing?</p>

include

The include function returns the rendered content of a template:

{{ include('template.html') }}
{{ include(some_var) }}

Included templates have access to the variables of the active context.

Note that this means the template referenced inside the include function does NOT make use of any schema it has.

If you are using the filesystem loader, the templates are looked for in the paths defined by it.

The context is passed by default to the template but you can also pass additional variables:

{# template.html will have access to the variables from the current context and the additional ones provided #}
{{ include('template.html', {foo: 'bar'}) }}

You can disable access to the context by setting with_context to false:

{# only the foo variable will be accessible #}
{{ include('template.html', {foo: 'bar'}, with_context = false) }}

{# no variables will be accessible #}
{{ include('template.html', with_context = false) }}

When you set the ignore_missing flag, Twig will return an empty string if the template does not exist:

{{ include('sidebar.html', ignore_missing = true) }}

You can also provide a list of templates that are checked for existence before inclusion. The first template that exists will be rendered:

{{ include(['page_detailed.html', 'page.html']) }}

If ignore_missing is set, it will fall back to rendering nothing if none of the templates exist, otherwise it will throw an exception.

Arguments

template: The template to render
variables: The variables to pass to the template
with_context: Whether to pass the current context variables or not
ignore_missing: Whether to ignore missing templates or not

language_names

The language_names function returns the names of the languages:

{# Abkhazian, Achinese, ... #}
{{ language_names()|join(', ') }}

By default, the function uses the current locale. You can pass it explicitly:

{# abkhaze, aceh, ... #}
{{ language_names('fr')|join(', ') }}

Arguments

locale: The locale

locale_names

The locale_names function returns the names of the locales:

{# Afrikaans, Afrikaans (Namibia), ... #}
{{ locale_names()|join(', ') }}

By default, the function uses the current locale. You can pass it explicitly:

{# afrikaans, afrikaans (Afrique du Sud), ... #}
{{ locale_names('fr')|join(', ') }}

Arguments

locale: The locale

max

max returns the biggest value of a sequence or a set of values:

{{ max(1, 3, 2) }}
{{ max([1, 3, 2]) }}

When called with a mapping, max ignores keys and only compares values:

{{ max({2: "e", 1: "a", 3: "b", 5: "d", 4: "c"}) }}
{# returns "e" #}

min

min returns the lowest value of a sequence or a set of values:

{{ min(1, 3, 2) }}
{{ min([1, 3, 2]) }}

When called with a mapping, min ignores keys and only compares values:

{{ min({2: "e", 3: "a", 1: "b", 5: "d", 4: "c"}) }}
{# returns "a" #}

parent

When a template uses inheritance, it’s possible to render the contents of the parent block when overriding a block by using the parent function:

{% extends "base.html" %}

{% block sidebar %}
    <h3>Table Of Contents</h3>
    ...
    {{ parent() }}
{% endblock %}

The parent() call will return the content of the sidebar block as defined in the base.html template.

random

The random function returns a random value depending on the supplied parameter type:

a random item from a sequence;
a random character from a string;
a random integer between 0 and the integer parameter (inclusive).
a random integer between the integer parameter (when negative) and 0 (inclusive).
a random integer between the first integer and the second integer parameter (inclusive).

{{ random(['apple', 'orange', 'citrus']) }} {# example output: orange #}
{{ random('ABC') }}                         {# example output: C #}
{{ random() }}                              {# example output: 15386094 (works as the native PHP mt_rand function) #}
{{ random(5) }}                             {# example output: 3 #}
{{ random(50, 100) }}                       {# example output: 63 #}

Arguments

values: The values
max: The max value when values is an integer

range

Returns a list containing an arithmetic progression of integers:

{% for i in range(0, 3) %}
    {{ i }},
{% endfor %}

{# outputs 0, 1, 2, 3, #}

When step is given (as the third parameter), it specifies the increment (or decrement for negative values):

{% for i in range(0, 6, 2) %}
    {{ i }},
{% endfor %}

{# outputs 0, 2, 4, 6, #}

Note that if the start is greater than the end, range assumes a step of -1:

{% for i in range(3, 0) %}
    {{ i }},
{% endfor %}

{# outputs 3, 2, 1, 0, #}

The Twig built-in .. operator is just syntactic sugar for the range function (with a step of 1, or -1 if the start is greater than the end):

{% for i in 0..3 %}
    {{ i }},
{% endfor %}

Arguments

low: The first value of the sequence.
high: The highest possible value of the sequence.
step: The increment between elements of the sequence.

script_names

The script_names function returns the names of the scripts:

{# Adlam, Afaka, ... #}
{{ script_names()|join(', ') }}

By default, the function uses the current locale. You can pass it explicitly:

{# Adlam, Afaka, ... #}
{{ script_names('fr')|join(', ') }}

Arguments

locale: The locale

source

The source function returns the content of a template without rendering it:

{{ source('template.html') }}
{{ source(some_var) }}

When you set the ignore_missing flag, Twig will return an empty string if the template does not exist:

{{ source('template.html', ignore_missing = true) }}

The function uses the same template loaders as the ones used to include templates. So, if you are using the filesystem loader, the templates are looked for in the paths defined by it.

Arguments

name: The name of the template to read
ignore_missing: Whether to ignore missing templates or not

timezone_names

he timezone_names function returns the names of the timezones:

{# Acre Time (Eirunepe), Acre Time (Rio Branco), ... #}
{{ timezone_names()|join(', ') }}

By default, the function uses the current locale. You can pass it explicitly:

{# heure : Antarctique (Casey), heure : Canada (Montreal), ... #}
{{ timezone_names('fr')|join(', ') }}

Arguments

locale: The locale