Skip to content

Home

Jump to bottom Edit New page
Ingi á Steinamørk edited this page Jul 26, 2019 · 18 revisions

Ease Templates for Template Designers

This document describes the syntax and semantics of the Ease Template engine and will be most useful as reference to those creating Ease templates.

 

Synopsis

A template is simply a text file. It can generate any text-based format (HTML, XML, CSV, LaTeX, etc.). It has the extension, .ease.

A template contains variables or expressions, which get replaced with values when the template is evaluated, and tags, which control the logic of the template.

Below is a minimal template that illustrates a few basics. We will cover further details later on:

<!DOCTYPE html>
<html>
    <head>
        <title>My Webpage</title>
    </head>
    <body>
        <ul id="navigation">
        {% for item in navigation %}
            <li><a href="{{ item.href }}">{{ item.caption }}</a></li>
        {% endfor %}
        </ul>

        <h1>My Webpage</h1>
        {{ a_variable }}
    </body>
</html>

There are two kinds of delimiters: {% ... %} and {{ ... }}. The first one is used to execute statements such as for-loops, the latter prints the result of an expression to the template.

 

IDEs Integration

The Ease template engine is based on the syntax of the Twig template engine. Therefor many IDEs support syntax highlighting and auto-completion for Ease (as long as they support Twig):

 

Variables

Variables may have attributes or elements you can access, too. You can use a dot (.) or ([]) to access child attributes of a variable:

{{ foo.bar }}
{{ foo['bar'] }}

It's important to know that the curly braces are not part of the variable but the print statement. When accessing variables inside tags, don't put the braces around them.

 

Global Variables

The following variables are always available in templates:

Site:

  • site.name: The name of the site
  • site.description: The description of the site
  • site.keywords: The keywords for the site
  • site.author: The author of the site
  • site.analytics.id: The Google Analytics ID
  • site.facebook.app_id: The Facebook App ID
  • site.addthis.id: The AddThis ID
  • site.domain.url: The site domain name
  • site.captcha.key: The captha key
  • site.url: The current url
  • site.language: The currently chosen site language
  • site.languages: An array containing all the available languages and their urls: [language].code, [language].url
  • site.defaultCountryId: The default country id, used in web shops
  • site.isLive: True if site has been set to be live
  • site.debug: True if debug mode is on
  • site.showGrid: True if grid is shown
  • site.translation_replace: ?
  • site.info: The info from the config file, like: site, address, phone, email, site_url

Ease:

  • ease.language: The currently chosen Ease language
  • ease.pagemenus.disabled: True if page menus are disabled
  • ease.modules: A list of enabled modules
  • ease.settings.forms.*: All forms settings from config file
  • ease.settings.calendars.*: All calendars settings from config file
  • ease.settings.contentgroups.*: All contentgroups settings from config file
  • ease.settings.filescollections.*: All filescollections settings from config file
  • ease.settings.schedules.*: All schedules settings from config file
  • ease.settings.albumcollections.*: All albumcollections settings from config file
  • ease.settings.lists.*: All lists settings from config file
  • ease.settings.menus.*: All menus settings from config file
  • ease.settings.newsgroups.*: All newsgroups settings from config file
  • ease.settings.newsletters.*: All newsletters settings from config file
  • ease.settings.products.*: All products settings from config file
  • ease.settings.slideshows.*: All slideshows settings from config file
  • ease.settings.users.*: All users settings from config file
  • ease.settings.filescollections.allowed_filetypes: A numeric array containing all the allowed filetypes for filescollections
  • ease.settings.products.currency: Currently chosen currency
  • ease.settings.products.locales.fo: The string for faroese localization
  • ease.settings.products.locales.da: The string for danish localization
  • ease.settings.products.locales.en: The string for english localization
  • ease.settings.products.currency_patterns.fo: The currency patterns string for faroese localization
  • ease.settings.products.currency_patterns.da: The currency patterns string for danish localization
  • ease.settings.products.currency_patterns.en: The currency patterns string for english localization
  • ease.version: The current version of Ease

Logged in states:

  • administrator.loggedin: True if site administrator is logged in
  • user.loggedin: True if site user is logged in

Passed data:

  • GET: An array containing all the provided GET variables
  • POST: An array containing all the provided GET variables
  • COOKIE: An array containing all the provided COOKIES

Other:

  • isDeveloper: True if current IP address is found in the list of developer IP addresses
  • translate: All the translations

 

Setting Variables

You can assign values to variables inside code blocks. Assignments use the set tag:

{% set foo = 'foo' %}
{% set foo = [1, 2] %}
{% set foo = {'foo': 'bar'} %}

 

Filters

Variables can be modified by filters. Filters are separated from the variable by a pipe symbol (|) and may have optional arguments in parentheses. Multiple filters can be chained. The output of one filter is applied to the next.

The following example removes all HTML tags from the name and title-cases it:

{{ name|striptags|title }}

Filters that accept arguments have parentheses around the arguments. This example will join a list by commas:

{{ list|join(', ') }}

To apply a filter on a section of code, wrap it in the filter tag:

{% filter upper %}
    This text becomes uppercase
{% endfilter %}

Go to the filters page to learn more about built-in filters.

 

Functions

Functions can be called to generate content. Functions are called by their name followed by parentheses (()) and may have arguments.

For instance, the range function returns a list containing an arithmetic progression of integers:

{% for i in range(0, 3) %}
    {{ i }},
{% endfor %}

Go to the functions page to learn more about the built-in functions.

 

Control Structure

A control structure refers to all those things that control the flow of a program - conditionals (i.e. if/elseif/else), for-loops, as well as things like blocks. Control structures appear inside {% ... %} blocks.

For example, to display a list of users provided in a variable called users, use the for statement:

<h1>Members</h1>
<ul>
    {% for user in users %}
        <li>{{ user.username|e }}</li>
    {% endfor %}
</ul>

The if statement can be used to test an expression:

{% if users|length > 0 %}
    <ul>
        {% for user in users %}
            <li>{{ user.username|e }}</li>
        {% endfor %}
    </ul>
{% endif %}

Go to the statements page to learn more about built-in statements.

 

Comments

To comment-out part of a line in a template, use the comment syntax {# ... #}. This is useful for debugging or to add information for other template designers or yourself:

{# note: disabled template because we no longer use this
    {% for user in users %}
        ...
    {% endfor %}
#}

 

Including other Templates

The include tag is useful to include a template and return the rendered content of that template into the current one:

{% include 'sidebar.html' %}

Per default included templates are passed the current context.

The context that is passed to the included template includes variables defined in the template:

{% for box in boxes %}
    {% include "render_box.ease" %}
{% endfor %}

The included template render_box.html is able to access box.

You can access templates in subdirectories with a slash:

{% include "sections/articles/sidebar.ease" %}

This behavior depends on the application embedding Ease Template.

 

HTML Escaping

When generating HTML from templates, there's always a risk that a variable will include characters that affect the resulting HTML. Ease Template supports escaping of variables.

Working with Manual Escaping

It is your responsibility to escape variables if needed. What to escape? Any variable you don't trust.

Escaping works by piping the variable through the escape or e filter:

{{ user.username|e }}

By default, the escape filter uses the html strategy, but depending on the escaping context, you might want to explicitly use any other available strategies:

{{ user.username|e('html') }}
{{ user.username|e('url') }}

 

Escaping

It is sometimes desirable or even necessary to have Ease Template ignore parts it would otherwise handle as variables or blocks. For example if the default syntax is used and you want to use {{ as raw string in the template and not start a variable you have to use a trick.

The easiest way is to output the variable delimiter ({{) by using a variable expression:

{{ '{{' }}

 

Expressions

Ease Template allows expressions everywhere. These work very similar to regular PHP and even if you're not working with PHP you should feel comfortable with it.

{% set greeting = 'Hello ' %}
{% set name = 'Fabien' %}

{{ greeting ~ name|lower }}   {# Hello fabien #} // NOT SUPPORTED YET

{# use parenthesis to change precedence #}
{{ (greeting ~ name)|lower }} {# hello fabien #} // NOT SUPPORTED YET

The operator precedence is as follows, with the lowest-precedence operators listed first: b-and, b-xor, b-or, or, and, ==, > !=, <, >, >=, <=, in, matches, starts with, ends with, .., +, -, ~, *, /, //, %, is, **, |, [], and .:

 

Literals

The simplest form of expressions are literals. Literals are representations for PHP types such as strings, numbers, and arrays. The following literals exist:

  • "Hello World": Everything between two double or single quotes is a string. They are useful whenever you need a string in the template (for example as arguments to function calls, filters or just to extend or include a template). A string can contain a delimiter if it is preceded by a backslash () -- like in 'It's good'.

  • ["foo", "bar"]: Arrays are defined by a sequence of expressions separated by a comma (,) and wrapped with squared brackets ([]).

  • {"foo": "bar"}: Hashes are defined by a list of keys and values separated by a comma (,) and wrapped with curly braces ({}):

{# keys as string #}
{ 'foo': 'foo', 'bar': 'bar' }

{# keys as names (equivalent to the previous hash) #}
{ foo: 'foo', bar: 'bar' }

{# keys as integer #}
{ 2: 'foo', 4: 'bar' }

  • true / false: true represents the true value, false represents the false value.

  • null: null represents no specific value. This is the value returned when a variable does not exist.

Arrays and hashes can be nested:

{% set foo = [1, {"foo": "bar"}] %}

Using double-quoted or single-quoted strings has no impact on performance but string interpolation is only supported in double-quoted strings.

 

Other Operators

The following operators are very useful but don't fit into any of the other categories:

  • |: Applies a filter.

  • ~: NOT SUPPORTED YET Converts all operands into strings and concatenates them. {{ "Hello " ~ name ~ "!" }} would return (assuming name is 'John') Hello John!.

  • ? :: NOT SUPPORTED YET The ternary operator:

{{ foo ? 'yes' : 'no' }} // NOT SUPPORTED YET
{{ foo ?: 'no' }} is the same as {{ foo ? foo : 'no' }} // NOT SUPPORTED YET
{{ foo ? 'yes' }} is the same as {{ foo ? 'yes' : '' }} // NOT SUPPORTED YET
Add a custom footer
Add a custom sidebar
Clone this wiki locally