Edit on GitHub

Templating Helpers

Introduction

Template Helpers are methods that offer special functionality to increase usability of view scripts. This is a concept of the Symfony Templating Component and you can of course use all of the built-in functionalities of this component.

Following an overview of some helpers provided by the Symfony Templating Component:

  • escape()
  • extend()
  • actions()
  • assets()
  • code()
  • form()
  • request()
  • router()
  • session()
  • stopwatch()
  • translator()
  • url()
  • path()

For more information please have a look into the docs of the Symfony PHP Templating Compontent.

In addition to the Symfony standard templating helpers, Pimcore adds some additional powerful helpers.

Pimcore Templating Helpers

All helpers are described below in detail, the following tables give just a short overview of all available helpers.

Method Description
action() Call an arbitrary action, this is a shorthand for Symfony's actions() helper
cache() Simple in-template caching functionality
device() Helps implementing adaptive designs.
getAllParams() Returns all parameters on the request object
getParam() Returns a specific parameter from the request
glossary() Helper to control the glossary engine
placeholder() Adding and embedding custom placeholders, e.g. for special header tags, etc.
headLink() Embeding / managing referenced stylesheets (alternative to assets())
headMeta() Managing your elements in your HTML document
headScript() Managing your elements
headStyle() Managing inline styles (pendant to headLink() for inline styles)
headTitle() Create and store the HTML document's <title> for later retrieval and output
inc() Use this function to directly include a Pimcore document.
inlineScript() Managing inline scripts (pendant to headScript() for inline scripts)
navigation() Embed and build navigations based on the document structure
pimcoreUrl() An alternative to url() and path() with the building behavior of Pimcore 4
template() Directly include a template
translate() I18n / Shared Translations

You can also create your own custom templating helpers to make certain functionalities available to your views.
Here you can find an example how to create and register your own templating helper.

$this->action()

This helper is a shorthand of Symfony's actions helper.

<?= $this->action($action, $controller, $bundle, $params = []) ?>
{{ pimcore_action(action, controller, bundle, {}) }}
Name Description
$action Name of the action (eg. foo)
$controller Name of the controller (eg. Bar)
$bundle Optional name of the bundle where the controller/action lives
$params Optional params added to the request object for the action
Example
<section id="foo-bar">
    <?= $this->action("foo", "Bar", null, ["awesome" => "value"]) ?>
</section>
<section id="foo-bar">
    {{ pimcore_action('foo', 'Bar', ~, { awesome: 'value' }) }}
</section>

$this->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, ...).

$this->cache(string $name, [int $lifetime = null], [bool $force = false])

Name Description
$name Name of cache item
$lifetime Lifetime 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.
$force Force caching, even when request is done within Pimcore admin interface
Example
<?php $cache = $this->cache("test_cache_key", 60); ?>
<?php if (!$cache->start()): ?>
    <h1>This is some cached microtime</h1>
    <?= microtime() ?>
    <?php $cache->end(); ?>
<?php endif ?>
{% 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 %}

$this->device()

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

<?= $this->device('a default value'); ?>
{{ pimcore_device('a default value') }}
Name Description
$default Default if no device can be detected
Example
<?php
    $device = $this->device("phone"); // first argument is the default setting
?>
 
<?php if($device->isPhone()) { ?>
    This is my phone content
<?php } else if($device->isTablet()) { ?>
    This text is shown on a tablet
<?php } else if($device->isDesktop()) { ?>
    This is for default desktop Browser
<?php } ?>
 
<?php if($this->device()->isDesktop()) { ?>
    Here is some desktop specific content
<?php } ?>

For details also see Adaptive Design.

$this->getAllParams()

Returns all parameters as an array on the request object.
See also $this->getParam().

$this->getParam()

Returns a parameter from the request object (get, post, .... ), it's an equivalent to $request->get() in the controller action.

$this->getParam(string $key, [mixed $default = null])

Name Description
$key Key of param
$default Default value if key not set
Example
<?= $this->getParam("myParam"); ?>

$this->glossary()

For details please see Glossary Documentation.

Example
<section class="area-wysiwyg">

    <?php // start capturing content with Glossary feature ?>
    <?php $this->glossary()->start(); ?>
        <?= $this->wysiwyg("content"); ?>
    <?php // call the processor with optional parameters ?>
    <?php $this->glossary()->stop(['limit' => 1]); ?>

</section>

$this->placeholder()

See Placeholder Template Helper

$this->headLink()

See HeadLink Template Helper

$this->headMeta()

See HeadMeta Template Helper

$this->headScript()

See HeadScript Template Helper

$this->headStyle()

See HeadStyle Template Helper

$this->headTitle()

See HeadTitle Template Helper

$this->inc()

Use $this->inc() to include documents (eg. snippets) within views. This is especially useful for footers, headers, navigations, sidebars, teasers, ...

$this->inc(mixed $document, [array $params], [$cacheEnabled = true])

Name Description
$document Document to include, can be either an ID, a path or even the Document object itself
$params Is optional and should be an array with key value pairs like in $this->action() from ZF.
$enabledCache Is true by default, set it to false to disable the cache. Hashing is done across source and parameters to ensure a consistent result.
Example
use Pimcore\Model\Document;
  
<!-- include path -->
<?= $this->inc("/shared/boxes/buttons") ?>
 
<!-- include ID -->
<?= $this->inc(256) ?>
 
<!-- include object -->
<?php
 
$doc = Document::getById(477);
echo $this->inc($doc, [
    "param1" => "value1"
]);
?> 
  
<!-- disable caching -->
<?= $this->inc(123, null, false) ?>

$this->inlineScript()

See InlineScript Template Helper

$this->navigation()

See Navigation

$this->pimcoreUrl()

An alternative to url() and path() with the building behavior of Pimcore 4.

$this->template()

This method is designed to include a different template directly, without calling an action.

$this->template($name, array $parameters = [])

Name Description
$path Path of template to include in Symfony template notation
$params Params to include.
Example
<?php echo $this->template("Includes/footer.html.php") ?>
 
<!-- with parameters -->
<?php echo $this->template("Includes/somthingelse.html.php", [
    "param1" => "value1"
]) ?>

Parameters in the included template are then accessible through $this->paramName or directly as $paramName, i.e. from the example above.

Example
<?= $this->param1 ?>
<?= $param1 ?>

Following parameter names cannot be used with $this->parameterName notation:

  • current
  • container
  • loader
  • helpers
  • parents
  • stach
  • charset
  • cache
  • escapers
  • globals
  • parser
  • evalTemplate
  • evalParameter

$this->translate()

View helper for getting translation from shared translations. For details also see Shared Translations.

$this->t(string $key = "") $this->translate(string $key = "")

Name Description
$key Key of translation
Example
<a href="/"><?= $this->translate("Home"); ?></a>

$this->webLink()

Exposes methods provided by Symfony's WebLink Component. See WebLink for details.

<link rel="stylesheet" href="<?= $this->webLink()->preload('/static/css/global.css', ['as' => 'style']) ?>">