Eine Vorlage ist einfach eine Textdatei, mit der sich jedes textbasierte Format (HTML, PDF usw.) erzeugen lässt. Per Konvention haben alle unsere Vorlagendateien die Endung .twig.

Eine Vorlage enthält Variablen oder Ausdrücke, die bei der Auswertung der Vorlage durch Werte ersetzt werden, sowie Tags, die die Logik der Vorlage steuern. Nachfolgend finden Sie eine minimale Vorlage, die einige Grundlagen veranschaulicht. Weitere Details behandeln wir später:

Innerhalb einer twig-Vorlage werden zwei primäre Trennzeichen verwendet: {% …​ %} und {{ …​ }}. Das erste wird verwendet, um Anweisungen auszuführen, die den Kontrollfluss der Vorlage ändern können (if-Anweisung), eine Vorlage mit include einzubinden, einen neuen Block zu definieren usw. Das zweite gibt das Ergebnis eines Ausdrucks in der Vorlage aus. Ausdrücke können sehr einfach sein (z. B. ein Variablenname) oder deutlich komplexer (z. B. ein mathematischer Ausdruck).

Die Anwendung übergibt Variablen an die Vorlagen zur Bearbeitung in der Vorlage. Variablen können auch Attribute oder Elemente besitzen, auf die Sie zugreifen können. Die visuelle Darstellung einer Variablen hängt stark von der Anwendung ab, die sie bereitstellt.

Sie können einen Punkt . verwenden, um auf Attribute einer Variablen zuzugreifen.

Sie können Variablen innerhalb von Codeblöcken mit dem set-Tag Werte zuweisen:

Um einen Teil einer Zeile in einer Vorlage auszukommentieren, verwenden Sie die Kommentarsyntax {# …​ #}. Das ist nützlich zum Debuggen oder um Informationen für andere Vorlagengestalter oder sich selbst hinzuzufügen:

Eine Kontrollstruktur bezeichnet all jene Dinge, die den Ablauf eines Programms steuern, etwa Bedingungen (d. h. if/elseif/else), for-Schleifen sowie Konstrukte wie Blöcke. Kontrollstrukturen erscheinen innerhalb von {% …​ %}-Blöcken. Um zum Beispiel eine Liste von Benutzern anzuzeigen, die in einer Variablen namens users bereitgestellt wird, verwenden Sie den for-Tag:

Mit dem if-Tag lässt sich ein Ausdruck prüfen:

Die mächtigste Funktion ist die Vorlagenvererbung. Die Vorlagenvererbung ermöglicht es Ihnen, eine Basisvorlage als "Skelett" zu erstellen, die alle gemeinsamen Elemente Ihrer Website enthält und Blöcke definiert, die untergeordnete Vorlagen überschreiben können. Kurze Erläuterungen, wie Sie eine Vorlage erben und nur einen Teil davon anpassen können, finden Sie bei den Tags extends und block.

XSS-Schwachstellen sind die häufigsten Arten von Sicherheitslücken in Webanwendungen, und um sie zu vermeiden, müssen Sie potenziell unsichere Daten mit Escaping versehen, bevor Sie sie dem Endbenutzer anzeigen. In allen twig-Vorlagen ist das Autoescaping standardmässig aktiviert. Das Autoescaping kann deaktiviert werden; in diesem Fall können der autoescape-Tag und der escape-Filter für ein feineres manuelles Escaping verwendet werden.

Dates to return range for.

String representation of date range.

The datetimeRange function is used to format date ranges with date and time information. The formatting takes current user’s locale into consideration while formatting.

If user’s locale is English USA (en_US), the output would be:

If user’s locale is German (de_DE), the output would be:

The json function returns the JSON representation of a value:

The max function will return the largest of its numerical arguments.

The min function will return the smallest of its numerical arguments.

The range function returns a list containing an arithmetic progression of numbers:

The abbreviate filter will abbreviate a string using an ellipsis (…​). It takes one argument which is the maximal length of the desired output including the length of the ellipsis.

The above example will output the following:

The abs filter takes a number as the input and returns its absolute value.

The barCode filter generates a bar code image link with specified parameters.

This will generate an image tag. The image will point to an URL which renders sometext as a bar code or QR code.

Different types of bar codes have different restrictions on length or what characters can be a part of the string:

The capitalize filter capitalizes the first letter of the input string. See also title filter.

The above example will output the following:

The darken filter decreased the lightness of a color in the HSL color space by an absolute amount.

The date filter is used to format date. The formatting takes the current user’s locale into consideration while formatting.

If user’s locale is English USA (en_US), the output would be:

If user’s locale is German (de_DE), the output would be:

The datetime filter is used to format date with date and time information. The formatting takes the current user’s locale into consideration while formatting.

If user’s locale is English USA (en_US), the output would be:

If user’s locale is German (de_DE), the output would be:

The default filter will render a default value if and only if the value being filtered is empty. A variable is empty if it is null, an empty string, an empty collection, or an empty map.

In the following example, if foo, bar, or baz are null the output will become an empty string which is a perfect use case for the default filter:

The escape filter escapes a string, to avoid XSS vulnerability, for safe insertion into the final output. It supports different escaping strategies depending on the template context.

The above example is equivalent to:

Please read the escaping section for more information about escaping.

The first filter will return the first item of a collection, or the first letter of a string.

The formatAddress filter is used to format a modular address.

The formatAmount filter formats a given number based on the passed currency and current user locale. The arguments described below can be used to override the locale settings.

The join filter will concatenate all items of a collection or array into a string. An optional argument can be given to be used as the separator between items.

The last filter will return the last item of a collection, or the last letter of a string.

The length filter returns the number of items of collection, map or the length of a string:

The length filter can be used inside if tag to make as a conditional

The lighten filter increased the lightness of a color in the HSL color space by an absolute amount.

The lineItemTotalAmountExcludingTax filter calculates the total amount without taxes from a list of line items.

The above example will output the following:

The lineItemTotalAmountIncludingTax filter calculates the total amount with taxes from a list of line items.

The above example will output the following:

The lineItemTotalDiscountExcludingTax filter calculates the total discount excluding taxes from a list of line items.

The above example will output the following:

The lineItemTotalDiscountIncludingTax filter calculates the total discount including taxes from a list of line items.

The above example will output the following:

The lineItemTotalTaxAmount filter calculates the total tax amount from a list of line items.

The above example will output the following:

The lineItemTotalTaxAmountsByRate filter calculates the total tax amounts per tax rate from a list of line items.

The above example will output the following:

The lineItemTotalUndiscountedAmountExcludingTax filter calculates the total undiscounted amount without taxes from a list of line items.

The above example will output the following:

The lineItemTotalUndiscountedAmountIncludingTax filter calculates the total undiscounted amount including taxes from a list of line items.

The above example will output the following:

The lower filter converts all letters of an input string into lower case.

The above example will output the following:

The negate filter takes a number as the input and returns its negative value.

The numberformat filter is used to format a decimal number.

You can round the decimal number to whole number by not defining fractional numbers:

To define different formats for positive and negative numbers use ; to separate positive and negative sub-patterns.

You can use any digit from 0 to 9 in format pattern which will be output literally if the number is .

To format number always with two fractional digits even if the number is not decimal, you can define following format:

Another use of digits can be if you want to prefix number smaller than format:

The qrCode filter generates a bar code image link with specified parameters.

This will generate an image tag. The image will point to an URL which renders sometext as a QR code.

The raw filter prevents the output of an expression from being escaped by the autoescaper. The raw filter must be the very last operation performed within the expression otherwise the autoescaper will deem the expression as potentially unsafe and escape it regardless.

If the raw filter is not the last operation performed then the expression will be escaped:

The regexp filter formats a regular expression so it can be used in JavaScript.

The replace filter formats a given string by replacing the placeholders (placeholders are free-form):

The resourcepath filter takes a relative resource path and returns a fully qualified URL (Uniform Resource Locator) to a resource.

The round filter takes a number as the input and returns the rounded value.

The rsort filter will sort an input list in reversed order.

The slice filter returns a portion of a list, array or string.

The sort filter will sort an input list in reversed order.

The split filter splits an input string by the given separator and returns a list of strings:

If a separator is an empty string, then the input value will be split into a list of characters.

The strip filter strips all HTML tags from its input and leaves only text.

The temporalAmount filter is used to format an amount of time, such as "6 hours", "2 days" or "3 years and 2 months".

Example with defaultValue:

The time filter is used to format date with only time information. The formatting takes current user’s locale into consideration while formatting.

If user’s locale is English USA (en_US), the output would be:

If user’s locale is German (de_DE), the output would be:

The title filter will capitalize the first letter of each word.

The above example will output the following:

The translate filter is used to support internationalization by translating input string into user’s language. In case you want to use the translations provided by the platform you should not touch the translation strings. However, you have the option to provide your own output but you will have to maintain it for every language yourself in that case.

If user’s language is English, the output would be:

If user’s language is German, the output would be:

The translate filter can accept a map of arguments which should be replaced by its placeholders in message. Message placeholder is written inside curly brackets ({…​}).

All messages in twig templates are fully translated for supported languages. Changing the message in twig template If you do not change messages or use the same messages which are filtered with translate filter, you will benefit from having everything automatically localized.

In case you want to customize translated messages and provide your own translations, you can achieve this by editing desired twig template using resource editor under Space > Resources > Editor. Editing of resource is bound to a context which consists of language and Space or Space View.

At the upper-left corner of the resource editor you can select desired Space, Space View and Language, and click to open a resource in context. Opening will automatically create new resource for the current context. When you are finished with customization, click save button to persist all changes.

Sometimes there is a need to translate different messages based on a number. Typically, translations for singular and plural differ and that’s where the translatePlural filter can help. The translatePlural can be used to translate singular and plural messages. The input string of translatePlural filter is a singular message. The plural message is passed as a pluralText argument.

Assuming that apple tree has 99 apples, the above example would output:

The trim filter strips whitespace from the beginning and end of an input string:

The above example will output the following:

The upper filter makes an entire string upper case.

The above example will output the following:

The urlencode filter translates an input string into application/x-www-form-urlencoded format using the UTF-8 encoding scheme.

The above example will output the following:

The autoescape tag can be used to temporarily disable or re-enable the autoescaper, as well as change the escaping strategy for a portion of the template.

Whether automatic escaping is enabled or not, you can mark a section of a template to be escaped or not by using the autoescape tag:

When automatic escaping is enabled everything is escaped by default except for values explicitly marked as safe. Those can be marked in the template by using the raw filter:

See the escaping section for more details on how escaping works.

The block tag provides a way to change how a certain part of a template is rendered but it does not interfere in any way with the logic around it. The blocks are mainly used for inheritance and act as placeholders and replacements at the same time.

The block tag is immediately followed by the name of the block. This name will be the same name a child template uses to override it. The endblock tag can optionally contain the block’s name for readability. A simple definition of a block with the name title would look like this:

Let’s take the following example to illustrate how a block works and more importantly, how it does not work:

If you render this template, the result would be exactly the same with or without the block tag. The block inside the for loop is just a way to make it overridable by a child template:

Now, when rendering the child template, the loop is going to use the block defined in the child template instead of the one defined in the base one.

The executed template is then equivalent to the following one:

Let’s take another example: a block included within an if statement:

Contrary to what you might think, this template does not define a block conditionally, it just makes overridable, by a child template, the output of what will be rendered when the condition is true.

If you want the output to be displayed conditionally, use the following instead:

The extends tag allows to extend a twig template from another one in order to modify it by changing or adding features. By extending a parent template, a child template inherits all content of the parent template. This allows a child template to customize the parts of the parent template. To better understande the concept, let’s define a parent template which we will call base.twig:

In this example, the block tags define three blocks (title, content and footer) that child templates can override or fill in.

All the block tag does is to tell the template engine that a child template may override those parts of the template.

A child template might look like this:

The extends tag is the key here, and it tells the template engine that this template inherits everything from parent template. When the template system evaluates this template, it first locates the parent. The extends tag must be the first tag in the template.

There is no limit to how long of an inheritance chain you can create, i.e. a child template can itself have a child template. A lot of potential comes from this fact because you can create a hierarchy of templates to minimize how much content you have to write on the lower levels.

Note that since the child template doesn’t define the footer block, the value from the parent template is used instead.

You can’t define multiple block tags with the same name in the same template. This limitation exists because a block tag works in "both" directions. That is, a block tag doesn’t just provide a hole to fill - it also defines the content that fills the hole in the parent. If there were two block tags with the same name in a template, that template’s parent wouldn’t know which one of the blocks' content to use.

The filter tag allow you to apply regular filters on a block of template data. Just wrap the code in the special filter section:

You can also chain filters:

The for tag is used to iterate through arrays, lists, collections as well as maps.

Inside of a for loop block you can access some special variables:

The for tag also provides a convenient way to check if the iterable object is empty with the included else tag.

Iterating over maps can be done like so:

The if tag can be used to change the flow of template rendering, depending on the result of an expression.

The include tag allows you to insert the rendered output of another template directly into the current template.

The included template will have access to the same variables that the current template does. You can add additional variables, to the included template, by passing them after the with keyword:

The set tag allows to define a variable in the current context, whether it currently exists or not.

The defined checks if a variable is defined in the current context. The defined test works with variable names and attributes on variable names.

The empty test checks if a variable is empty. A variable is empty if it is null, an empty string, an empty collection, or an empty map.

The even test checks if a number is even.

The existing test checks if a resource path exists.

The iterable test checks if a variable is capable of being iterated.

The map test checks if a variable is an instance of a map data type.

The null test checks if a variable is null.

The odd test checks if a number is odd.

An arithmetic operator takes numerical values as their operands and returns a single numerical value. All the regular math operators (+, -, /, %, *) are available for use within expression blocks. Order of operations applies to all operators.

Logical operators are typically used with logical values (true and false) or with expressions which return logical value.

The and and or operators are available to join boolean expressions.

A comparison operator compares its operands and returns a logical value based on whether the comparison is true. The operands can be numerical, string, logical, or object values.

The following comparison operators are available in any expression: ==, !=, <, >, <=, >=.

The test operators apply one of the test tags to a variable and produce a logical result.