Template syntax

  1. Introduction to template syntax

    What problem does HTML logic solve? In the IPS Community Suite, our templates are the 'view', i.e. how the data is rendered as HTML to the screen. However, basic HTML has no logic capabilities; what is in the HTML file is what is sent to the browser. In a complex application like ours, we need some way to make decisions about what is output. These decisions could potentially be made in the PHP backend, but that isn't appropriate in most cases; the backend should be focused on processing the data, while the view (our templates) control how the data is displayed. HTML logic allows us to make these decisions inside our templates. It mixes standard HTML with some special tags and flow-control statements, most of which are very similar to PHP.   What other features do templates have? The result is that in one template, we can have logic that says output some HTML if a certain condition is met, or different HTML otherwise. We can also do loops on data, reducing repetition. We also have some special tags that call output plugins to transform values in some way (for example, to render dates from a timestamp).    Basic syntax There's three basic types of syntax you'll see. We will explore these in more detail in later steps. Logic tags
    Double-curly parenthesis. Controls flow in a template. In these tags, the expressions can be any valid PHP expression. Some examples: /* Basic structure */ {{if $condition}} ... {{else}} ... {{endif}} /* Examples of other expressions */ {{if !$condition}} {{if ( $color == 'green' && $size == 'big' ) || $condition}} {{if count( $value ) > 2}}   Variables
    Single-curly parenthesis. Outputs values passed into the template (or values from elsewhere, e.g. a loop). {$value}   Output plugins
    Pass the provided value through the specified output plugin. {pluginName="value"}  
  2. Using expressions in logic

    As mentioned in the first step, any valid PHP expression can be used in HTML logic tags. You'll often just be checking if an expression is true or false: {{if $value}} ... {{endif}} ...but there are many other possibilities. You can also use normal PHP functions in your expressions. For example, you may need to determine if an array has any items, so PHP's count function is appropriate: {{if count( $items ) > 0}} ... {{endif}} Consult the full PHP documentation for the functions and language syntax.   Getting values from IPS4 You'll often need to compare values in the software in your expressions. For example, is a particular setting enabled, or does the current user have a member ID. While you can use the standard PHP approach to get these values, IPS4 contains a number of shortcut 'constants' you can use to simplify your logic. They are used like so: {{if settings.reputation_enabled}} ... {{endif}} Behind the scenes, this shortcut gets expanded to the PHP equivalent, meaning it gives you access to all of the available methods and properties of the object it translates to. The available shortcuts are:   request
    Translates to \IPS\Request::i().
    Access to the request variables. e.g. {{if request.some_param}}   member
    Translates to \IPS\Member::loggedIn(). 
    The member object for the current user. e.g. {{if member.language()->isrtl}}   settings
    Translates to \IPS\Settings::i().
    Obtains system setting values (by setting key). e.g. {{if settings.auto_polling_enabled}}   output
    Translates to \IPS\Output::i().
    The output object, containing the methods/properties the suite uses to output content. e.g. {{if count( output.contextualSearchOptions )}}   theme
    Translates to \IPS\Theme::i()->settings.
    Access to the theme settings available for the currently-used theme. e.g. {{if theme.sidebar_position == 'right'}}   cookie
    Translates to \IPS\\Request::i()->cookie.
    Access to the cookie object. e.g. {{if isset( cookie.hasJS )}}   Consult the PHP framework documentation for the full range of properties and methods available for each class. 
  3. if/elseif/else logic

    The most basic logic check is a simple if/else. This allows you to put HTML if a condition matches, or something else if it doesn't. The syntax is simply: {{if [expression]}} HTML to output if expression is true {{else}} HTML to output if expression was not true {{endif}}   There's also an elseif tag which allows you to specify other conditions to check if earlier conditions didn't match. {{if [expression]}} HTML to output if expression is true {{elseif [expression]}} HTML to output if expression is true {{else}} HTML to output if other expressions were not true {{endif}}  
  4. Loops

    Standard PHP loop types are supported as HTML logic tags.   Foreach {{foreach [expression]}} ... {{endforeach}} Expression is anything PHP would support in a loop. The variables the loop defines are available within the body of the loop: <ul> {{foreach $arrayOfItems as $id => $item}} <li>{$id}: {$item}</li> {{endforeach}} </ul>   For {{for [expression]}} ... {{endfor}} For example: <ul> {{for $i = 0; $i < count( $arrayOfItems ); $i++}} <li>{$i}</li> {{endfor}} </ul>   Breaking and continuing If you need to break or continue a loop, you can use the relevant PHP statement to do so. For example, using break: {{foreach $arrayOfItems as $id => $item}} {{if $id > 15}} {{break;}} {{endif}} {{endforeach}}  
  5. Variables

    Each template bit can have variables passed into it by the backed PHP code, and these variables can be used by the template bit to control the display. Consult either the template editor or designer's mode guides (depending on your preference) to find out how to determine which variables are available to a template. As well as these local variables, you can access the various objects created by the IPS4 PHP framework.   Variables are escaped It's important to note that by default, all variable values are HTML-escaped when you output them in templates. This is for security, and ensures you don't inadvertently output some malicious HTML that is then processed by the browser and displayed. If a variable $value contained: <strong>Example</strong> Then outputting it in a template like so: Here's the variable value: {$value} Would actually send: Here's the variable value: &lt;strong&gt;Example&lt;/strong&gt; This is safe for the browser to display. Bypassing this protection Of course, in some situations, you want the raw HTML to be output, and not escaped. To do so, you can use the raw modifier on the variable: Here's the variable value: {$value|raw} Warning Using this modifier on untrusted content is a security risk. You should not output raw user-supplied HTML unless it has been properly sanitized and you are certain it is safe. Content that comes from IPS4's rich text editor is safe to output with this modifier.  
  6. Template plugins

    It's often useful to transform raw values in some way, and this is achieved in IPS4 with template plugins. Template plugins take a value, and optionally some arguments, and output some transformed value. The syntax for template tags is: {pluginkey="<value>" argument="..."} The value can be a normal string, or it could be a variable coming from elsewhere. Template plugins can always be used in templates, but some can also be used in CSS files. Those that can are identified below.   Available plugins {advertisement="$location"}
    The HTML for the specified ad location Parameters
    $location - A valid advertisement location   {datetime="$timestamp" dateonly="[boolean]" norelative="[boolean]" lowercase="[boolean]" short="[boolean]"}
    Shows a time formatted according to the user's locale Parameters
    $timestamp - A timestamp to transform into a date
    dateonly - Show only the date (with no time)
    norelative - By default, relative times will be used (e.g. 8 hours ago). To always show an absolute date/time, set this to true.
    lowercase - By default, date strings will be capitalized where necessary (e.g. Yesterday, 8:32pm). Setting this to true ensures it is lowercase, for use in a sentence.
    short - Uses a very short date format (ideal for mobile devices)   {expression="$expression" raw="[boolean]"}
    Allows the result of arbitrary PHP expressions to be inserted into templates. The result of the expression is output. Can be used in CSS files. Parameters
    $expression - A valid PHP expression that produces output of some kind
    raw - By default, the result of the expression is HTML-escaped. Setting this parameter to true outputs the raw result. Be careful! This can be a security risk.   {file="$file" extension="[string]"}
    Outputs the URL to a file stored by IPS4's file handling classes. Can be used in CSS files. Parameters
    $file - Either an instance of the \IPS\File class, or a string representing the stored URL to the file
    extension - The file storage extension used to originally store the file, e.g. calendar_Events. If none is specified, core_Attachment is assumed.   {filesize="$sizeInBytes" decimal="[boolean]"}
    Formats the specified filesize and outputs an appropriate human-readable form. Parameters
    $sizeInBytes - An integer representing a file size, in bytes, to be formatted
    decimal - Whether the filesize should be treated as a KB (i.e. 1kb = 1024 bytes) or 1 = 1000. All values are always rounded to one decimal place.   {insert="$filename"}
    Includes a PHP script file Parameters
    $filename - The filename of the PHP file to include. The output of the file is buffered and output.   {lang="$languageKey" sprintf="[string]" htmlsprintf="[string]" pluralize="[string]" wordbreak="[boolean]" ucfirst="[boolean]"}
    Inserts a phrase from the language system in the user's chosen language. Paramaters
    $languageKey - The key of the language phrase to insert
    sprintf - Comma-separated list of values to replace in the language string. These values are HTML-escaped.
    htmlsprintf - Comma-separated list of values to replace in the language string. These values are not escaped. Be careful!
    pluralize - Comma-separated list of values to pass into any pluralize statements in the language string.
    wordbreak - If true, adds <wbr> tags to the returned string to help prevent strings that break the page width.
    ucfirst - Determines whether the first character of the string should be made uppercase.   {member="$propertyToDisplay" id="[integer]" group="[boolean]" raw="[boolean]"}
    Outputs the property or result of a method called on the member object. Parameters
    $propertyToDisplay - One of the properties or methods available on the member object. For example: link() or name.
    id - Member ID to load and display. If not specified, the current member is used.
    group - If true, this tag works on the member's group instead (and so the $propertyToDisplay should be one of the group properties or methods instead)
    raw - By default, the returned output is HTML escaped. Setting this to true means the output won't be escaped. Be careful!   {number="$number"}
    Formats a number according to the user's locale (e.g. with commas or periods) Parameters
    $number - Number to format   {prefix="$CSSPropertyName" value="[string]"}
    Shortcut tag which automatically prefixes the provided CSS property with vendor prefixes. Can be used in CSS files. Parameters
    $CSSPropertyName - The property name to prefix. The supported properties are: transition, transform, animation, animation-name, animation-duration, animation-fill-mode, animation-timing-function, user-select, box-sizing, background-size.
    value - the value of the CSS property.   {request="$requestParameter" raw="[boolean]"}
    Inserts the value of a request parameter. Paramaters
    $requestParameter - The parameter from the request object to be inserted.
    raw - By default, the returned value is HTML-escaped. If this parameter is true, the output won't be HTML-escaped. Be careful!   {resource="$path" app="[string]" location="[string]" noprotocol="[boolean]"}
    Returns the absolute URL to the specified resource. Can be used in CSS files. Parameters
    $path - Relative path to the required resource (path is relative to the current theme's /resource directory)
    app - The app to which the resource belongs.
    location - The location (front/admin/global)
    noprotocol - Whether to make the resulting URL protocol-less (i.e. do not include http:// or https:// at the beginning, which can be useful for resources which are not allowed to be loaded over http on an https connection)   {setting="$settingKey" escape="[boolean]"}
    Inserts the value of a system setting. Can be used in CSS files. Parameters
    $settingKey - Key of the system setting to insert.
    escape - By default, the raw value is output. If you need the value to be HTML-escaped, pass true for this parameter.    
  7. Using arbitrary PHP in templates

    It is possible to use arbitrary PHP in your templates. Generally this is discouraged, but in some situations a simple statement can be of benefit to initialize a variable or aid debugging (for example). Note: templates also support a special expression template tag; consider using this tag in favor of arbitrary PHP. We cover the tag in a later step of this guide. To use PHP, you can enclose your statement in double-curly parenthesis, like so: {{$myVar = 0;}} Be sure to include the semi-colon so that your statement is valid. This syntax allows for one-line statements. If you have a larger block, each line must contain its own double-curly parenthesis. Note: templates use output buffering; attempting to echo, print_r or similar in the middle of a template is likely to cause errors. If you need to do this, we recommend following the statement with an {{exit;}} so that script execution ends immediately.