Skip to content

Twig Functions Reference

Symfony and Twig template functions/filters/tags

For the template functionality provided by Symfony Framework, see Symfony Twig Extensions Reference page. For those provided by the underlying Twig template engine, see Twig Reference page

In addition to the native functions provided by Twig, eZ Platform offers the following:

  • ez_content_name - displays a Content item's name in the current language
  • ez_field_description - returns the description from the FieldDefinition of a Content item's Field in the current language
  • ez_field_name - returns the name from the FieldDefinition of a Content item's Field in the current language
  • ez_field_value - returns a Content item's Field value in the current language
  • ez_field - returns a Field from a Content item in the current language
  • ez_file_size - returns the size of a file as string
  • ez_first_filled_image_field_identifier - returns the identifier of the first image field that is not empty
  • ez_full_datetime - outputs date and time in full format
  • ez_full_date - outputs date in full format
  • ez_full_time - outputs time in full format
  • ez_image_alias - displays a selected variation of an image
  • ez_is_field_empty - checks if a Content item's Field value is considered empty in the current language
  • ez_short_datetime - outputs date and time in short format
  • ez_short_date - outputs date in short format
  • ez_short_time - outputs time in short format
  • ez_render_field - displays a Content item's Field value, taking advantage of the template block exposed by the Field Type used
  • ez_trans_prop - gets the translated value of a multi valued(translations) property
  • ez_urlalias - is a special route name for generating URLs for a Location from the given parameters

ez_content_name

Description

ez_content_name() is a Twig helper which displays a Content item's name in the current language.

If the Content item does not have a translation in the current language, the name in the main language is always returned. This behavior is identical when forcing a language.

If languages were specified during retrieval of Content object, you can render name directly using $content->getName() (Twig: content.name) and it will take the prioritised languages into account. If not, it falls back to the main language, just like ez_content_name() does. For usage with ContentInfo, see examples below.

Prototype and Arguments

ez_content_name ( eZ\Publish\API\Repository\Values\Content\Content content [, string forcedLanguage ] ) : string

ez_content_name ( contentInfo [, string forcedLanguage ] ) : string

Argument name Type Description
content eZ\Publish\API\Repository\Values\Content\Content or eZ\Publish\API\Repository\Values\Content\ContentInfo Content or ContentInfo object the displayable field belongs to.
forcedLanguage string Locale you want the content name translation in (e.g. "fre-FR"). Null by default (takes current locale)

Usage

1
2
3
<h2>Content name in current language: {{ ez_content_name( content ) }}</h2>
<h2>Content name in current language, from ContentInfo: {{ ez_content_name( content.contentInfo ) }}</h2>
<h2>Content name in French (forced): {{ ez_content_name( content, "fre-FR" ) }}</h2>

Equivalent PHP code

Getting the translated name for a Content item
1
2
3
4
5
6
7
// Assuming you're in a controller action
$translationHelper = $this->get( 'ezpublish.translation_helper' );
 
// From Content
$translatedContentName = $translationHelper->getTranslatedContentName( $content );
// From ContentInfo
$translatedContentName = $translationHelper->getTranslatedContentNameByContentInfo( $contentInfo );
Forcing a specific language
1
2
// Assuming you're in a controller action
$translatedContentName = $this->get( 'ezpublish.translation_helper' )->getTranslatedName( $content, 'fre-FR' );

ez_field_description

Description

ez_field_description() is a Twig helper which returns the description from the FieldDefinition of a Content item's Field in the current language.

This can be useful when you don't want to use a sub-request and custom controller to be able to display this information.

If the Content item does not have a translation in the current language, the main language will be used. This behavior is identical when forcing a language using forcedLanguage.

Prototype and Arguments

ez_field_description ( Content|ContentInfo content, string fieldDefIdentifier [, string forcedLanguage ] ) : string|null

Argument name Type Description
content eZ\Publish\API\Repository\Values\Content\Content or eZ\Publish\API\Repository\Values\Content\ContentInfo Content/ContentInfo object the fieldDefIdentifier belongs to.
fieldDefIdentifier string Identifier of the Field you want to get the FieldDefinition description from.
forcedLanguage string Language you want to force (e.g. "eng-US"), otherwise takes prioritized languages from SiteAccess settings.

Usage

1
<p id="ez-content-article-title-description">{{ ez_field_description( content, "title" ) }}</p>

ez_field_name

Description

ez_field_name() is a Twig helper which returns the name from the FieldDefinition of a Content item's Field in the current language.

This can be useful when you don't want to use a sub-request and custom controller to be able to display this information.

If the Content item does not have a translation in the current language, the main language will be used. This behavior is identical when forcing a language using forcedLanguage.

Prototype and Arguments

ez_field_name ( Content|ContentInfo content, string fieldDefIdentifier [, string forcedLanguage ] ) : string|null

Argument name Type Description
content eZ\Publish\API\Repository\Values\Content\Content or eZ\Publish\API\Repository\Values\Content\ContentInfo Content / ContentInfo object the fieldDefIdentifier belongs to.
fieldDefIdentifier string Identifier of the Field you want to get the FieldDefinition name from.
forcedLanguage string Language you want to force (e.g. "jpn-JP"), otherwise takes prioritized languages from SiteAccess settings.

Usage

1
<label for="ez-content-article-title">{{ ez_field_name( content, "title" ) }}</label>

ez_field_value

Description

ez_field_value() is a Twig helper which returns a Content item's Field value in the current language.

This can be useful when you don't want to use ez_render_field and manage the rendering by yourself.

If the Content item does not have a translation in the current language, the main language will be used. This behavior is identical when forcing a language using forcedLanguage.

Tip

If languages were specified during retrieval of Content object, you can get field value directly using content->getFieldValue('title') and it will take the prioritised languages into account. If not, it falls back to the main language, just like ez_field_value() does.

Prototype and Arguments

ez_field_value ( eZ\Publish\API\Repository\Values\Content\Content content, string fieldDefIdentifier [, string forcedLanguage ] ): eZ\Publish\Core\FieldType\Value

Argument name Type Description
content eZ\Publish\API\Repository\Values\Content\Content Content object the field referred to with fieldDefIdentifier belongs to.
fieldDefIdentifier string Identifier of the field you want to get the value from.
forcedLanguage string Locale you want the Content name translation in (e.g. "fre-FR"). Null by default (takes current locale)

Usage

1
<h2>My title value: {{ ez_field_value( content, "title" ) }}</h2>

ez_field

Description

ez_field() is a Twig helper which returns a Field in the current language. The field gives you access to the field value, as well as the Field's Definition identifier and Type identifier.

Tip

Other Twig helpers are available to display specific information of the Field; they all start with ez_field_.

If the Content item does not have a translation in the current language, the main language will be used. This behavior is identical when forcing a language using forcedLanguage.

Tip

If languages were specified during retrieval of Content object, you can get field directly using content->getField('title') and it will take the prioritised languages into account. If not, it falls back to the main language, just like ez_field() does.

Prototype and Arguments

ez_field ( eZ\Publish\API\Repository\Values\Content\Content content, string fieldDefIdentifier [, string forcedLanguage ] ) : eZ\Publish\API\Repository\Values\Content\Field

Argument name Type Description
content eZ\Publish\API\Repository\Values\Content\Content Content object the field referred to with fieldDefIdentifier belongs to.
fieldDefIdentifier string Identifier of the field you want to get the value from.
forcedLanguage string Locale you want the Content name translation in (e.g. "fre-FR"). Null by default (takes current locale)

Usage

1
<h2>My title's id: {{ ez_field( content, "title" ).id }}</h2>

ez_file_size

Description

ez_file_size() is a Twig helper (Twig filter) which is mostly a byte calculator. It will convert a number from byte to the correct suffix (from B to EB). The output pattern will also vary with the current language of the SiteAccess (e.g. choosing between coma or point pattern).

It returns a string.

Note

The byte factor is 1000 instead of 1024 to be more familiar for users.

Prototype and Arguments

integer number_of_bytes|ez_file_size( integer number_of_decimal )

Argument name Type Description
number_of_bytes integer The number in byte you want to convert
number_of_decimal integer The number of decimal you want the output to have

Usage

1
2
3
{{ 42698273|ez_file_size( 3 ) }} //Output with French SiteAccess : 42,698 MB

{{ 42698273|ez_file_size( 4 ) }} //Output with English SiteAccess : 42.6983 MB

ez_first_filled_image_field_identifier

Description

ez_first_filled_image_field_identifier is a Twig helper which returns the identifier of the first image field that is not empty.

It can be used for example to identify the first image in an article to render it in an embed or line view.

Prototype and Arguments

ez_first_filled_image_field_identifier ( eZ\Publish\API\Repository\Values\Content\Content content ) : string

Argument name Type Description
content eZ\Publish\API\Repository\Values\Content\Content Content item the Fields belong to

ez_full_datetime, ez_full_date, ez_full_time

These Twig filters are used to format date and time. The formats are defined in user preferences.

Twig filter Description
ez_full_datetime outputs date and time in full format
ez_full_date outputs date in full format
ez_full_time outputs time in full format

The filters accept \DateTimeInterface as argument. If the argument is null, the filter returns the current date and time in the selected format.

For example {{ contentInfo.publishedDate|ez_full_datetime }} will return 03 May 2019 23:03.

The filters also accept an optional timezone parameter for displaying date and time in a chosen time zone.

ez_image_alias

Description

ez_image_alias() is a Twig helper that displays a selected variation (alias) of an image.

Prototype and Arguments

ez_image_alias ( eZ\Publish\API\Repository\Values\Content\Field field, eZ\Publish\API\Repository\Values\Content\VersionInfo versionInfo, string variantName ) : \eZ\Publish\SPI\Variation\Values\Variation|null

Argument name Type Description
field eZ\Publish\API\Repository\Values\Content\Field The image Field
versionInfo eZ\Publish\API\Repository\Values\Content\VersionInfo The VersionInfo that the Field belongs to
variantName string Name of the image variation to be used. To display original image alias, use original as an image variation.

See images for more information about image variations.

ez_is_field_empty

Description

ez_is_field_empty() is a Twig helper which checks if a Content item's Field value is considered empty in the current language.

It returns a Boolean value (true or false).

If the Content item does not have a translation in the current language, the main language will be used. This behavior is identical when forcing a language using forcedLanguage.

Prototype and Arguments

ez_is_field_empty ( eZ\Publish\API\Repository\Values\Content\Content content, eZ\Publish\API\Repository\Values\Content\Field|string fieldDefIdentifier [, string forcedLanguage ] ) : bool

Argument name Type Description
content eZ\Publish\API\Repository\Values\Content\Content Content item the displayed Field belongs to.
fieldDefIdentifier eZ\Publish\API\Repository\Values\Content\Field or string The Field you want to check or its identifier.
forcedLanguage string Locale you want the Content name translation in (e.g. "fre-FR"). Null by default (takes current locale)

Usage

Using the Field identifier as parameter
1
2
3
4
5
6
{# Display "description" field if not empty #}
{% if not ez_is_field_empty( content, "description" ) %}
    <div class="description">
        {{ ez_render_field( content, "description" ) }}
    </div>
{% endif %}
Using the Field as parameter
1
2
3
4
5
6
{# Display "description" field if not empty #}
{% if not ez_is_field_empty( content, field ) %}
    <div class="description">
        {{ ez_render_field( content, field.fieldDefIdentifier ) }}
    </div>
{% endif %}
Checking if Field exists before use
1
2
3
4
5
6
{# Display "description" field if it exists and is not empty #}
{% if content.fields.description is defined and not ez_is_field_empty( content, "description" ) %}
    <div class="description">
        {{ ez_render_field( content, "description" ) }}
    </div>
{% endif %}

ez_render_field

Description

ez_render_field() is a Twig helper that displays a Content item's Field value, taking advantage of the template block exposed by the Field Type used.

Template blocks for built-in Field Types reside in EzPublishCoreBundle.

See section of Using the Field Type's template block for more information.

Prototype and Arguments

ez_render_field ( eZ\Publish\API\Repository\Values\Content\Content content, string fieldDefinitionIdentifier [, hash params] ) : string

Argument name Type Description
content eZ\Publish\API\Repository\Values\Content\Content Content item the displayable field belongs to.
fieldDefinitionIdentifier string The identifier the Field is referenced by.
params hash Hash of parameters that will be passed to the template block.
By default you can pass 2 entries:
lang (to override the current language, must be a valid locale with xxx-YY format)
template (to override the template to use, see below)
attr (hash of HTML attributes you want to add to the inner markup)
parameters (arbitrary parameters to pass to the template block)

Some Field Types might expect specific entries under the parameters key, like the MapLocation Field Type.

Override a Field template block

If you do not want to use the built-in Field template block, you can override it by specifying your own template. You can do this inline when calling ez_render_field(), or globally by prepending a Field template to use by the helper.

Your template block must comply to a regular Field Type template block, as explained in the Field Type documentation.

Inline override

You can use the template you need by filling the template entry in the params argument.

1
2
3
4
5
{{ ez_render_field( 
       content, 
       'my_field_identifier',
       { 'template': 'AcmeExampleBundle:fields:my_field_template.html.twig' }
   ) }}

This code will load my_field_template.html.twig located in AcmeExampleBundle/Resources/views/fields/.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{# Assuming "my_field_identifier" from the template above example is an ezkeyword field. #}
{% block ezkeyword_field %}
    {% apply spaceless %}
        {% if field.value.values|length() > 0 %}
        <ul>
            {% for keyword in field.value.values %}
            <li>{{ keyword }}</li>
            {% endfor %}
        </ul>
        {% endif %}
    {% endapply %}
{% endblock %}

Overriding a block and calling the parent

When overriding a Field template block, it is possible to call its parent. For this, you need to import the original template horizontally (without inheritance), using the use Twig tag.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{# AcmeExampleBundle/Resources/views/fields/my_field_template.html.twig #}
{# Assuming "my_field_identifier" from above template example is an ezkeyword field. #}
 
{% use "EzPublishCoreBundle::content_fields.html.twig" with ezkeyword_field as base_ezkeyword_field %}
 
{# Surround base block with a simple div #}
{% block ezkeyword_field %}
    <div class="ezkeyword">
        {{ block("base_ezkeyword_field") }}
    </div>
{% endblock %}
Inline override using current template

If you want to override a specific Field template only once (e.g. because your override would be only valid in your current template), you can specify the current template to be the source of the Field block.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{% extends "AcmeExampleBundle::pagelayout.html.twig" %}

{% block content %}
    {# Note that "tags" is a field using ezkeyword fieldType #}
    <div class="tags">{{ ez_render_field( content, "tags" , { "template": _self } ) }}</div>
{% endblock %}

{# Here begins the inline block for my ezkeyword field #}
{% block ezkeyword_field %}
    {% apply spaceless %}
        {% if field.value.values|length() > 0 %}
        <ul>
            {% for keyword in field.value.values %}
            <li>{{ keyword }}</li>
            {% endfor %}
        </ul>
        {% endif %}
    {% endapply %}
{% endblock %}

Limitation

Using _self will only work if your current template is extending another one.

This is basically the same limitation as for Symfony form themes.

Global override

If you want to override a Field template every time it occurs, you can append it to the Field templates list.

1
2
3
4
5
6
7
8
ezpublish:
    system:
        my_siteaccess:
            field_templates:
                
                    template: AcmeExampleBundle:fields:my_field_template.html.twig
                    # Priority is optional (default is 0). The higher it is, the higher your template gets in the list.
                    priority: 10

It will then be used every time the Field is rendered with ez_render_field().

Tip

Because built-in Field templates have priority of 0, you need to set yours to a higher value to override them.

The content of the template must be placed in a Twig block corresponding to the Field Type's internal name (e.g. {% block ezstring_field %}) for ezstring.

The template must also extend EzPublishCoreBundle::content_fields.html.twig.

1
2
3
4
5
{% extends "EzPublishCoreBundle::content_fields.html.twig" %}

{% block ezstring_field %}
    {# template content here #}
{% endblock %}

ez_short_datetime, ez_short_date, ez_short_time

These Twig filters are used to format date and time. The formats are defined in user preferences.

Twig filter Description
ez_short_datetime outputs date and time in short format
ez_short_date outputs date in short format
ez_short_time outputs time in short format

The filters accept \DateTimeInterface as argument. If the argument is null, the filter returns the current date and time in the selected format.

For example {{ contentInfo.publishedDate|ez_full_datetime }} will return 03 May 2019 23:03.

The filters also accept an optional timezone parameter for displaying date and time in a chosen time zone.

ez_trans_prop

Description

ez_trans_prop() is a generic, low level Twig helper which gets the translated value of a multi valued(translations) property.

If the Content item does not have a translation in the current language, the main language (see further down for details) will be used if this is supported by the provided object. This behavior is identical when forcing a language using forcedLanguage.

If languages were specified during retrieval of a given value object, you can get translated values directly in several cases now, including examples below. For more details, see Languages.

Prototype and Arguments

ez_trans_prop ( ValueObject object, string property [, string forcedLanguage ] ) : string|null

Argument name Type Description
object eZ\Publish\API\Repository\Values\ValueObject ValueObject object property belongs to.
property string Property to get translated value from, logic is using one of the following (in this order):
object method get{property}
object property {property}s
forcedLanguage string Optional language we want to force (e.g. `"eng-US"``), otherwise takes prioritized languages from SiteAccess settings.
Main language use

Main language is be applied in the following way for Value objects that support this:

  • When attribute is retrieved via object property: Use mainLanguageCode property if it exists as fallback language, but only if either alwaysAvailable property does not exist, or is true.
  • When attribute is retrieved via object method: Provide $language = null as the only argument to the method, the logic of the ValueObject decides if this gives a fallback value or not.

Usage

Example below shows how this function can be used to get the Content name with exact same result as using ez_content_name(content):

1
{{ ez_trans_prop( versionInfo, "name" ) }}

Example for ContentType->names:

1
{{ ez_trans_prop( contentType, "name" ) }}

ez_urlalias

Description

ez_urlalias is a not a real Twig helper, but a special route name for generating URLs for a Location from the given parameters.

Prototype and Arguments

path( eZ\Publish\API\Repository\Values\Content\Location|string name [, array parameters ] [, bool absolute ] ) : string

Argument name Type Description
name string | \eZ\Publish\API\Repository\Values\Content\Location The name of the route or a Location instance
parameters array A hash of parameters:
locationId
contentId
absolute boolean Whether to generate an absolute URL

Working with Location

Linking to other Locations is fairly easy and is done with the native path() Twig helper (or url() if you want to generate absolute URLs). You just have to pass it the Location object and path() will generate the URLAlias for you.

1
2
{# Assuming "location" variable is a valid eZ\Publish\API\Repository\Values\Content\Location object #}
<a href="{{ path( location ) }}">Some link to a location</a>

I don't have the Location object

1
<a href="{{ path( "ez_urlalias", {"locationId": 123} ) }}">Some link to a location, with its Id only</a>
1
<a href="{{ path( "ez_urlalias", {"contentId": 456} ) }}">Some link from a contentId</a>

Note

Links generated from a Content ID will point to its main location.

Error management

For a Location alias set up a 301 redirect to the Location's current URL when:

  1. the alias is historical
  2. the alias is a custom one with forward flag true
  3. the requested URL does not match the one loaded (case-sensitively)

Under the hood

In the back end, path() uses the Router to generate links.

This makes it also easy to generate links from PHP, via the router service.

Read the Docs