Smarty templates: operator reference #

This page is for template developers who write .stpl templates and need the exact form of one operator. It lists every template operator a standard installation registers, grouped by area, with its .stpl form, whether it needs the prefix exp_, how it takes its input, and an example. The rules behind the columns are explained in Smarty templates: operators and fetch functions; read that first if the words "input" and "param" below are new to you.

The list was taken from the code: the operator registrations of lib/eztemplate/classes/eztemplateautoload.php, kernel/common/eztemplateautoload.php, kernel/private/eztemplate/eztemplateautoload.php, lib/ezpdf/classes/eztemplateautoload.php, [PHP] PHPOperatorList[] of settings/template.ini, and the autoloads/eztemplateautoload.php of the extensions shipped with the installation. The input mode of each operator is what expSmartyRenderer::operatorInputMode() decides from the operator's template hints, and for the operators without hints from expSmartyRenderer::PARAMETER_OPERATORS and [SmartySettings] ParameterOperatorList[] of smarty.ini.

How to read the tables #

Name in .stpl. The name to write after the pipe or before the parentheses. exp_<name> where Smarty 5 has a modifier of the same name (Smarty's own modifiers always win; exp_ steps past them). An operator whose own name starts with exp_ (exp_path, exp_environment) is called by that name.

Mode.

• input: the operator works on its input. $x|op:a:b passes $x as the input and a, b as parameters; op($x, a, b) is the same call. Called without an input (a .tpl op(a, b) with no pipe), write op(null, a, b). Every operator without template hints is of this kind, which includes nearly every operator of the extensions, except the kernel's operators that read their parameters only (below) and those an extension lists in [SmartySettings] ParameterOperatorList[] of smarty.ini.
• param: the operator reads its parameters only. The piped value becomes the first parameter, so $a|op:b and op($a, b) are the same call, in any order you like to write it. The function form of the .tpl is the .stpl form: {ezhttp('SearchText', 'get')}, {if has_role('Editor')}. For the kernel's operators without template hints that are of this kind (ezhttp, has_role, topmenu ...), a null in front, as in ezhttp(null, 'SearchText', 'get'), the form converted templates had before, is left out, so both forms work.

Example. A .stpl line. Where the template engine's own tests (eZTemplateOperatorMatrixTest, checked against .stpl by tests/tests/lib/smarty/expSmartyOperatorParityTest.php) have the case, the output is given after →.

Literals first, since several operators of the .tpl are literals in Smarty:

Arrays and lists (eZTemplateArrayOperator) #

Logic and comparison (eZTemplateLogicOperator, eZTemplateControlOperator) #

cond and first_set read their parameters only. Piped, the piped value becomes the first parameter: $a|first_set:'d' is "the first of $a, 'd' that is set", and $a|cond:'x':'y' uses $a as the condition. A .tpl $a|first_set('d') ignores $a and is always 'd'; the converter writes it as first_set('d') to keep that. Smarty's own ==, !=, &&, ||, ! and ?: work too, but eq compares as the .tpl does ({if eq(1, '1')} is true; several parameters must all be equal).

Types (eZTemplateTypeOperator) #

All of them read their parameters: is_set($x) and $x|is_set are the same.

Arithmetic (eZTemplateArithmeticOperator) #

Smarty's +, -, *, / and % are fine for numbers too.

Strings (eZTemplateStringOperator, eZTemplateTextOperator, eZTemplateNl2BrOperator) #

indent and nl2br hint that their input is a parameter, but read it as their input when they run; the bridge lists them in expSmartyRenderer::INPUT_AT_RUN_TIME.

PHP string functions (eZTemplateStringsOperator) #

Sixty-one PHP string functions are operators (PHP string functions as template operators). All are input operators: the piped value is the PHP function's subject.

{$text|exp_substr:0:5}
{if $text|str_contains:'Expo'}...{/if}
{'%s has %d items'|sprintf:$name:$count}
{1234567.891|exp_number_format:2:'.':','}
{$node.data_map.success_text.data_text|exp_strip_tags}
{(first_set($form.parent.parent.vars, $form.parent.vars))|expattr:'name'|ristring:'_':'-'}

Smarty's own substr, strlen, strip_tags and number_format are PHP's functions with the same order of parameters, so the unprefixed names usually print the same; the prefixed names are what the converter writes and what is guaranteed to behave as in the .tpl.

Digests and units (eZTemplateDigestOperator, eZTemplateUnitOperator) #

Dates and locale (eZTemplateLocaleOperator) #

Fetching and attributes (eZTemplateExecuteOperator, eZTemplateAttributeOperator) #

More on fetch(): Fetch functions.

Images (eZTemplateImageOperator) #

An extension that registers an operator of the same name replaces the kernel's: in a siteaccess with sevenx_themes_media, image is the theme's operator (an input operator, written image(null, ...)).

Roles and policies (eZTemplateRoleOperator) #

They read their parameters only (the current user is the default): write them as in the .tpl. A value piped into them becomes the first parameter, so $current_user|has_role:'Editor' asks for a role named after the user; write has_role('Editor'). Details: Role and policy checks in templates.

Extensions, installation and environment (lib and kernel) #

URLs, settings and the request (eZURLOperator, eZi18nOperator) #

ezhttp and ezhttp_hasvariable take the name and the type (post, get, session, cookie) as their parameters. They have no template hints; the bridge knows them as operators that read their parameters only (expSmartyRenderer::PARAMETER_OPERATORS), so the function form of the .tpl works: {ezhttp('SearchText', 'get')}. 'SearchText'|ezhttp:'get' is the same call, and ezhttp(null, 'SearchText', 'get'), which converted templates wrote before, still works. Wash what it returns: {ezhttp('SearchText', 'get')|wash}.

ezurl, ezroot, ezdesign and ezimage print the address in double quotes by default (href={...|ezurl}); :'no' leaves the quotes out, :'single' uses single quotes. With ezurlmultisite active, its own operators take over these ten names with the same forms.

Content, menus and text (kernel/common) #

None of these has template hints. The input ones work on the value piped into them; as a function without an input, write null first, with the parameters of the .tpl. The param ones read their parameters only (expSmartyRenderer::PARAMETER_OPERATORS): write them as in the .tpl.

siteaccess_url, siteaccess_menu and siteaccess_menu_key say they take no input ('input' => false), so they are param operators: siteaccess_url(a, b) and a|siteaccess_url:b are the same.

PHP functions of template.ini #

[PHP] PHPOperatorList[] of settings/template.ini makes PHP functions operators: urlencode, urldecode, rawurlencode and rawurldecode in a standard installation. They are param operators with one parameter:

<a href="/search?q={$text|rawurlencode}">...</a>

Operators of the shipped extensions #

Operators registered by an extension's autoloads/eztemplateautoload.php exist only in a siteaccess where the extension is active. Of the extensions shipped with the installation, only ezurlmultisite gives its operators template hints (the same as the kernel's URL operators); every other extension operator is an input operator: $x|op:a passes $x as its input, and a .tpl call without a pipe is written op(null, ...) in a .stpl. An extension makes an operator without hints that reads its parameters only a param operator with [SmartySettings] ParameterOperatorList[] in its smarty.ini.append.php (see Writing operators and functions).

Real lines from the media port, all input operators called without an input:

<h3 class="title"><a href="{exp_path(null, $location)}">{ng_render_field(null, $content.fields.title)}</a></h3>
<article {item_params(null, $toolbar_macros, $content, $location)} class="view-type view-type-{$view_type}">
{$__loop1 = fieldRelations(null, $content, 'authors')}

An operator name that starts with exp_ and is registered (exp_path, exp_url, exp_config, exp_can_login_to_siteaccess, exp_environment ...) is that operator. Only a name that is not registered has its prefix removed: exp_count is count, exp_implode is implode. So exp_path can never stand for an operator named path; write path for that one.

Bridge helpers (not operators) #

expattr, expvar, expvoid, expslice, expsectionloop, exprange, expsequence, expcolumn are modifiers of the bridge itself; see The helpers of the bridge.

Finding the operators of your installation #

The tables cover what ships with the installation. Your own extensions add operators the same way: look for operator_names in extension/*/autoloads/eztemplateautoload.php of the extensions active in the siteaccess. To find out the mode of an operator, look for operatorTemplateHints() in its class: none, or 'input-as-parameter' => 'always', means input; 'input-as-parameter' => true or 'input' => false means param. Writing an operator that works in both engines: Writing operators and functions for .stpl.

Related pages #

• Smarty templates: operators and fetch functions: the rules behind this page
• Template functions and blocks
• Troubleshooting and FAQ