Skip to main content
Version: 2023.3

Twig Extensions

Introduction

Twig Extensions are functions, filters and more that offer special functionality to increase usability of view scripts.

Following an overview of some Twig Extensions:

  • render

  • render_esi

  • controller

  • asset

  • csrf_token

  • path

  • absolute_url

  • translator

  • trans

  • url

  • relative_path

In addition to the standard Twig extensions, Pimcore adds some additional powerful extensions.

Pimcore Twig Extensions

All Twig extension functions are described below in detail, the following tables give just a short overview of all available extensions.

ExtensionDescription
pimcore_cache()Simple in-template caching functionality
pimcore_device()Helps implementing adaptive designs
pimcore_glossaryTwig Filter: Apply filter on content to pass it to Glossary engine
pimcore_placeholder()Adding and embedding custom placeholders, e.g. for special header tags, etc.
pimcore_head_link()Embeding / managing referenced stylesheets (alternative to assets())
pimcore_head_meta()Managing your <meta> elements in your HTML document
pimcore_head_script()Managing your <scripts> elements
pimcore_head_style()Managing inline styles (pendant to headLink() for inline styles)
pimcore_head_title()Create and store the HTML document's <title> for later retrieval and output
pimcore_inc()Use this function to directly include a Pimcore document
pimcore_inline_scriptManaging inline scripts (pendant to headScript() for inline scripts)
pimcore_build_nav(), pimcore_render_nav(), pimcore_nav_renderer()Embed and build navigations based on the document structure
pimcore_url()An alternative to url() and path()
pimcore_website_config()Fetch website settings or specific setting (first param: key) for the current site
pimcore_image_thumbnail()Returns a path to a given thumbnail on image
pimcore_image_thumbnail_html()Returns html for displaying the thumbnail image
pimcore_supported_locales()Use this function to get a list of supported locales

Pimcore also adds some Twig tests for evaluating boolean conditions e.g.

{# using 'instaceof' checks if object is instanceof provided classname #}
{% if (product is instanceof('App\\Model\\Product\\Car')) %}
...
{% endif %}

{# using 'pimcore_data_object' checks if object is instanceof \Pimcore\Model\DataObject\Concrete #}
{% if (product is pimcore_data_object) %}
...
{% endif %}

The following table gives an overview of all available tests:

TestDescription
instanceof(classname)Checks if an object is an instance of a given class
pimcore_assetChecks if object is instanceof Asset
pimcore_asset_archiveChecks if object is instanceof Asset\Archive
pimcore_asset_audioChecks if object is instanceof Asset\Audio
pimcore_asset_documentChecks if object is instanceof Asset\Document
pimcore_asset_folderChecks if object is instanceof Asset\Folder
pimcore_asset_imageChecks if object is instanceof Asset\Image
pimcore_asset_textChecks if object is instanceof Asset\Text
pimcore_asset_unknownChecks if object is instanceof Asset\Unknown
pimcore_asset_videoChecks if object is instanceof Asset\Video
pimcore_data_objectChecks if object is instanceof DataObject\Concrete
pimcore_data_object_folderChecks if object is instanceof DataObject\Folder
pimcore_data_object_class(classname)Checks if object is instanceof Pimcore\Model\DataObject{Classname}
pimcore_data_object_galleryChecks if object is instanceof DataObject\Data\ImageGallery
pimcore_data_object_hotspot_imageChecks if object is instanceof DataObject\Data\Hotspotimage
pimcore_documentChecks if object is instanceof Document
pimcore_document_emailChecks if object is instanceof Document\Email
pimcore_document_folderChecks if object is instanceof Document\Folder
pimcore_document_hardlinkChecks if object is instanceof Document\Hardlink
pimcore_document_pageChecks if object is instanceof Document\Page
pimcore_document_linkChecks if object is instanceof Document\Link
pimcore_document_page_snippetChecks if object is instanceof Document\PageSnippet
pimcore_document_snippetChecks if object is instanceof Document\Snippet

The following tests are only available if the PimcoreWebToPrintBundle is enabled and installed:

TestDescription
pimcore_document_printChecks if object is instanceof PrintAbstract
pimcore_document_print_containerChecks if object is instanceof Printcontainer
pimcore_document_print_pageChecks if object is instanceof Printpage

The following tests are only available if the PimcoreNewsletterBundle is enabled and installed:

TestDescription
pimcore_document_newsletterChecks if object is instanceof Newsletter

You can also create your own custom Twig Extension to make certain functionalities available to your views.
Here you can find an example how to create your own Twig Extension.

pimcore_cache

This is an implementation of an in-template cache. You can use this to cache some parts directly in the template, independent of the other global definable caching functionality. This can be useful for templates which need a lot of calculation or require a huge amount of objects (like navigations, ...).

pimcore_cache( name, lifetime, force)

NameTypeDescription
namestringName of cache item
lifetimeintLifetime in seconds. If you define no lifetime the behavior is like the output cache, so if you make any change in Pimcore, the cache will be flushed. When specifying a lifetime this is independent from changes in the CMS.
forceboolForce caching, even when request is done within Pimcore admin interface
Example
{% set cache = pimcore_cache("test_cache_key", 60) %}
{% if not cache.start() %}
<h1>This is some cached microtime</h1>
{{ 'now'|date('U') }}
{% do cache.end() %}
{% endif %}

pimcore_device

This extension makes it easy to implement "Adaptive Design" in Pimcore.

Arguments
NameTypeDescription
defaultstringoptional Default if no device can be detected
Example
{% set device = pimcore_device('desktop') %}
{% if device.isPhone() %}
This is my phone content
{% elseif device.isTablet() %}
This text is shown on a tablet
{% elseif device.isDesktop() %}
This is for default desktop Browser
{% endif %}

For details also see Adaptive Design.

pimcore_glossary

The pimcore_glossary filter replaces glossary terms. See Glossary for details.

{% apply pimcore_glossary %}
My content
{% endapply %}

pimcore_placeholder

See Placeholder Template Extension

See HeadLink Template Extension

pimcore_head_meta

See HeadMeta Template Extension

pimcore_head_script

See HeadScript Template Extension

pimcore_head_style

See HeadStyle Template Extension

pimcore_head_title

See HeadTitle Template Extension

pimcore_inc

Use pimcore_inc() to include documents (eg. snippets) within views. This is especially useful for footers, headers, navigations, sidebars, teasers, ...

pimcore_inc(document, params, cacheEnabled)

NameTypeDescription
documentPageSnippet | int | stringDocument to include, can be either an ID, a path or even the Document object itself
paramsarrayIs optional and should be an array with key value pairs.
enabledCacheboolIs true by default, set it to false to disable the cache. Hashing is done across source and parameters to ensure a consistent result.
Example
{#include path#}
{{ pimcore_inc("/shared/boxes/buttons") }}

{#include ID#}
{{ pimcore_inc(256) }}

{#include object#}
{% set doc = pimcore_doc(477) %}
{{ pimcore_inc(doc, {param: 'value'}) }}

{#disable caching#}
{{ pimcore_inc(123, null, false) }}

When passing parameters to something included with pimcore_inc(), these parameters are not automatically passed to Twig. The parameters are passed as attributes to the included document, and should be passed to Twig via the document's controller action.

Example:

index.html.twig

{{ pimcore_inc('/some/other/document', { 'parameterToPass': parameterToPass }) }}

IndexController.php (whatever controller / method is designated for /some/other/document in the document tree)

public function otherDocumentAction(Request $request): array
{
return ['parameterToPass' => $request->get('parameterToPass')];
}

more Convenient way

public function otherDocumentAction(Request $request): Response
{
return $this->render(":Default:someOtherDocument.html.twig", ['parameterToPass' => $request->get('parameterToPass')]);
}

someOtherDocument.html.twig (whatever Twig template is actually for /some/other/document in the document tree)

...
{{ parameterToPass }}
...

pimcore_inline_script

See InlineScript Template Extension

  • pimcore_build_nav
  • pimcore_render_nav
  • pimcore_nav_renderer

Used to interact with navigations. See Navigation for details. Simplified example:

{% set navigation = pimcore_build_nav({
active: document,
root: navRootDocument
}) %}
{{ pimcore_render_nav(navigation) }}

{# you can also fetch the renderer instance and call custom render methods #}
{% set renderer = pimcore_nav_renderer('menu') %}
{{ renderer.render(navigation) }}

pimcore_url

An alternative to url() and path() which used Url.

{{ pimcore_url(params, name, reset, encode, relative) }}

All parameters are optional here:

NameTypeDescription
paramsarrayRoute params. If object is passed in the params then link generator will be used to generate Url
namestringRoute name
resetboolIs false by default, set it to false to avoid merging parameters from request
encodeboolIs true by default, set it to false to disable encoding
relativeboolIs false by default, set it to true to generate a relative path based on the current request path
Example
{% set object = pimcore_object(769) %}
{{ pimcore_url({'object': object}) }}