Skip to contents

Template Syntax

Source: vignettes/template-syntax.Rmd
template-syntax.Rmd

This vignette describes the template syntax supported by jinjar, following the structure of the Jinja Template Designer Documentation. It is designed to act as a reference when writing templates.

The jinjar R package is powered by the inja C++ library. The syntax is very similar to that of the Jinja Python package, but there are also many differences. Unfortunately, this means jinjar is not a drop-in replacement for Jinja – you might need to adapt existing Jinja templates for the jinjar engine.

The most fundamental difference between jinjar and Jinja is:

  • Jinja variables support direct interaction with the underlying Python objects.
  • jinjar variables are simple JSON data types. The underlying R objects are translated to JSON.

This is described in more detail in the Variables section below.

Before starting, let’s create a few R objects for rendering example templates.

library(jinjar)

# length-1 vector
title <- "My Webpage"

# vector
users <- c("User A", "User B", "User C")

# list
godzilla <- list(
  Name = "Godzilla",
  Born = 1952,
  Birthplace = "Japan"
)

# data frame
navigation <- data.frame(
  caption = c("Home", "Blog"),
  href = c("index.html", "blog.html")
)

# HTML special characters
name <- 'Dwayne "The Rock" Johnson'

Synopsis

A jinjar template is simply a text file, and when rendered the output is also a text file (e.g. HTML, SQL, LaTeX).

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

Below is a minimal template that illustrates a few basics using the default jinjar configuration. We will cover the details later in this document:

<!DOCTYPE html>
<html lang="en">
<head>
    <title>{{ title }}</title>
</head>
<body>
    <ul id="navigation">
    {% for item in navigation -%}
        <li><a href="{{ item.href }}">{{ item.caption }}</a></li>
    {% endfor -%}
    </ul>
    {# a comment #}
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
    <title>My Webpage</title>
</head>
<body>
    <ul id="navigation">
    <li><a href="index.html">Home</a></li>
    <li><a href="blog.html">Blog</a></li>
    </ul>
    
</body>
</html>

The following example shows the default configuration settings, but you can adjust the syntax configuration as desired using jinjar_config().

There are a few kinds of delimiters. The default delimiters are configured as follows:

Line Statements are also possible, though they don’t have default prefix characters. To use them, set line_statement when creating the jinjar_config().

Variables

When writing a template, we refer to variables that act as data placeholders. We define their values when rendering the template.

Although we pass R objects to render(), it is helpful to understand that these are encoded as JSON objects before the template is rendered.

R object JSON object Template example
Length-1 vector Scalar {{ foo }}
Vector Array {{ foo.1 }}
List Object {{ foo.bar }}
Data frame Array of objects {{ foo.1.bar }}

You can use dot (.) notation to access data nested within a variable. An array element is accessed by its numeric zero-based index (e.g. foo.1) and an object value is accessed by its key (e.g. foo.bar).

Note: In R, the dot is a valid character in an object name (e.g. my.data). However, this causes ambiguity when accessing nested data values. For this reason, each dot is replaced with an underscore when the data is encoded as JSON (e.g. my.data becomes my_data).

Note: In R, a scalar is indistinguishable from a length-1 vector. This creates an ambiguity when passing R data to the template, because template variables support both scalars and arrays. You can explicitly pass a length-1 vector as an array using the I() operator (see help("render")).

The double-brace syntax is used to print the value of the variable (e.g. {{ foo }}). To use the variable in other contexts (e.g. control structures), then these braces are omitted (e.g. {% for bar in foo %}).

If a template variable has not been defined, then an error occurs. However, you can use the default(foo, bar) function to specify a fallback value.

Comments

To comment-out some lines, preventing them from appearing in the rendered document, use the comment syntax (default: {# ... #}). This is useful for debugging or documenting the template.

Hello{# TODO: update this #}!
Hello!

Whitespace Control

In the default configuration, whitespace (e.g. spaces, tabs, newlines) is left unchanged in the rendered output. For example, in the default configuration we get:

<div>
    {% if true %}
        yay
    {% endif %}
</div>
<div>
    
        yay
    
</div>

By setting trim_blocks = TRUE when creating the jinjar_config(), the first newline after a control block is automatically removed. Setting lstrip_blocks = TRUE removes any whitespace from the beginning of the line until the start of each block. With both options enabled, the above example becomes:

<div>
    {% if true %}
        yay
    {% endif %}
</div>
<div>
        yay
</div>

Instead of changing the global configuration, you can manually trim whitespace at a more finegrained level.

  • By putting a minus sign (-) after the opening delimiter, this removes any whitespace from the beginning of the line until the start of the block (i.e. the same as the lstrip_blocks feature).
  • By putting a minus sign (-) before the closing delimiter, this removes any whitespace (including newlines) until the next non-whitespace character (i.e. slightly different from the trim_blocks feature).

This can be activated for control blocks, comments, or variable expressions:

<div>
    {% if true -%}
        yay
    {%- endif -%}
</div>
<div>
    yay
</div>

Line Statements

If line statements are enabled (see jinjar_config()), it’s possible to mark a line as a statement. For example, if the line statement prefix is configured to #, you can do:

<ul id="navigation">
# for item in navigation
    <li><a href="{{ item.href }}">{{ item.caption }}</a></li>
# endfor
</ul>
<ul id="navigation">
    <li><a href="index.html">Home</a></li>
    <li><a href="blog.html">Blog</a></li>
</ul>

Control Structures

A control structure refers to all those things that control the flow of a program. With the default syntax, control structures appear inside {% ... %} blocks.

For

A for-loop allows you to iterate over each element in a vector:

{% for user in users -%}
{{ loop.index1 }}. {{ user }}
{%- endfor -%}
1. User A
2. User B
3. User C

or loop over key-value pairs in a named list:

<dl>
{% for key, value in godzilla %}
  <dt>{{ key }}</dt>
  <dd>{{ value }}</dd>
{% endfor -%}
</dl>
<dl>

  <dt>Birthplace</dt>
  <dd>Japan</dd>

  <dt>Born</dt>
  <dd>1952</dd>

  <dt>Name</dt>
  <dd>Godzilla</dd>
</dl>

As described in Variables, a data frame is translated to an array of JSON objects. Therefore a nested combination of the above two loops could theoretically be used. In practice, it is much more common to iterate over rows and access the individual elements by their attributes:

<ul id="navigation">
{% for item in navigation -%}
<li><a href="{{ item.href }}">{{ item.caption }}</a></li>
{% endfor -%}
</ul>
<ul id="navigation">
<li><a href="index.html">Home</a></li>
<li><a href="blog.html">Blog</a></li>
</ul>

While inside a for-loop block, you can access some special variables:

Variable Description
loop.index The current iteration (0-based).
loop.index1 The current iteration (1-based).
loop.is_first True if first iteration.
loop.is_last True if last iteration.
loop.parent In nested loops, the parent loop variable.

If

Conditional branches are written using if, else if and else statements, which evaluate Expressions.

{% if length(users) > 5 -%}
{% for user in users -%}
* {{ user }}
{% endfor %}
{% else if length(users) > 0 -%}
{{ join(users, ", ") }}.
{% else -%}
No users found.
{% endif %}
User A, User B, User C.

Assignments

Using the set statement, you can assign values to variables.

{% set name="world" -%}
Hello {{ name }}!
Hello world!

Extends

The extends tag can be used for template inheritance. See Template Inheritance in vignette("auxiliary-templates").

Include

The include tag inserts the rendered contents of an auxiliary template. See Template Inclusion in vignette("auxiliary-templates").

Expressions

Basic expressions are supported in templates.

Literals

The simplest form of expressions are literals, which represent fixed values.

As described in Variables, the template is rendered using data stored in JSON format. For this reason, literals must also be specified in JSON format. The following types of literals are supported:

  • String: characters between double quotation marks.
    • Double quotation marks in the string value must be escaped using a backslash.
  • Integer: whole numbers without decimal part.
  • Numeric: floating point numbers.
    • Specify in decimal or scientific format.
  • Boolean: either true or false.
    • Specify using lowercase characters.
  • List: array of values between square brackets.
  • Object: key-value data pairs between curly brackets
    • Keys must be string literals, but values can be any literal type.
  • NULL: missing data is represented by null.

Here is example usage for each type:

String: {{ "A string" }}
Integer: {{ 3 }}
Numeric: {{ 3.14 }} or {{ 1.6e-19 }}
Boolean: {{ true }} or {{ false }}
List: {{ [1, 2, 3] }}
Object: {{ {"a": 1, "b": 2} }}
Null: {{ null }}
String: A string
Integer: 3
Numeric: 3.14 or 1.6e-19
Boolean: true or false
List: [1,2,3]
Object: {"a":1,"b":2}
Null:

Math

You can perform simple arithmetic using standard operators:

1 + 1: {{ 1 + 1 }}
3 - 2: {{ 3 - 2 }}
2 * 2: {{ 2 * 2 }}
1 / 2: {{ 1 / 2 }}
2 ^ 3: {{ 2 ^ 3 }}
7 % 3: {{ 7 % 3 }}
1 + 1: 2
3 - 2: 1
2 * 2: 4
1 / 2: 0.5
2 ^ 3: 8
7 % 3: 1

Comparisons

You can perform comparisons:

1 == 1: {{ 1 == 1 }}
1 != 1: {{ 1 != 1 }}
2 >  1: {{ 2 > 1 }}
2 >= 1: {{ 2 >= 1 }}
2 <  1: {{ 2 < 1 }}
2 <= 1: {{ 2 <= 1 }}
1 == 1: true
1 != 1: false
2 >  1: true
2 >= 1: true
2 <  1: false
2 <= 1: false

Logic

Within expressions and control structures, you can use the Boolean operators: and, or, and not.

true and false: {{ true and false }}
true or false: {{ true or false }}
not false: {{ not false }}
true and false: false
true or false: true
not false: true

You can also check if a value is contained within a list using in:

{{ 1 in [1, 2, 3] }}
true

Functions

Data Checks

You can check if a value exists by passing the variable name as a string:

users does exist: {{ exists("users") }}
abc doesn't exist: {{ exists("abc") }}
users does exist: true
abc doesn't exist: false

Similarly, you can check if a value exists within a JSON object, by passing the key as a string:

Birthplace does exist: {{ existsIn(godzilla, "Birthplace") }}
Weight doesn't exist: {{ existsIn(godzilla, "Weight") }}
Birthplace does exist: true
Weight doesn't exist: false

Concisely handle missing values using the default() function:

{{ default(godzilla.Weight, 20000) }}
20000

You can also check the data type of a variable or literal:

{{ isString("a string") }}
{{ isInteger(3) }}
{{ isFloat(3.14) }}
{{ isNumber(3) }} and {{ isNumber(3.14) }}
{{ isBoolean(false) }}
{{ isArray([1, 2, 3]) }}
{{ isObject({"a": 1, "b": 2}) }}
true
true
true
true and true
true
true
true

Data Conversion

You can convert strings to numeric types, using the int() or float() functions:

{{ int("2") }}
{{ float("2.5") }}
2
2.5

HTML Escaping

When generating HTML from templates, there’s always a risk that a variable will include characters that affect the resulting HTML. The special characters are: <, >, & and ".

In jinjar, it’s your responsibility to manually escape variables, using the escape_html() function. You should escape variables that might contain any of the special characters. But if a variable is trusted to contain well-formed HTML, then it should not be escaped (otherwise you could accidentally double-escape the content).

<input type="text" value="{{ escape_html(name) }}">
<input type="text" value="Dwayne &quot;The Rock&quot; Johnson">

SQL Quoting

SQL databases expect string literals to be wrapped in single-quotes, while other types of literals (e.g., numbers) are not quoted. This is cumbersome to achieve when writing a template, so the quote_sql() function provides this functionality.

Important: quote_sql() does not provide any protection against SQL injection attacks.

WHERE title = {{ quote_sql(title) }} AND year = {{ quote_sql(godzilla.Born) }}
WHERE title = 'My Webpage' AND year = 1952

When passed an array, quote_sql() will quote each element and return a comma-separated list. This is particularly helpful when using the SQL IN operator.

WHERE user IN ({{ quote_sql(users) }})
WHERE user IN ('User A', 'User B', 'User C')

Numeric Data

You can check if an integer is even or odd, or divisible by some other integer. This could be used to make alternating row colors.

{{ even(42) }}
{{ odd(42) }}
{{ divisibleBy(42, 7) }}
true
false
true

You can round floating point numbers to a specific precision:

{{ round(3.1415, 0) }}
{{ round(3.1415, 3) }}
3
3.142

String Data

Translate a string to lower case or upper case:

{{ lower("Hello") }}
{{ upper("Hello") }}
hello
HELLO

Escape special characters for use in HTML content (see HTML Escaping):

<input type="text" value="{{ escape_html(name) }}">
<input type="text" value="Dwayne &quot;The Rock&quot; Johnson">

Quote string data for use as string literals in a SQL query (see SQL Quoting):

WHERE user IN ({{ quote_sql(users) }})
WHERE user IN ('User A', 'User B', 'User C')

JSON Lists

Get the number of list elements:

length(): {{ length([3,1,2]) }}
length(): 3

Get the first or last elements:

first(): {{ first([3,1,2]) }}
last():  {{ last([3,1,2]) }}
first(): 3
last():  2

Get the minimum or maximum elements:

min(): {{ min([3,1,2]) }}
max(): {{ max([3,1,2]) }}
min(): 1
max(): 3

Sort the list into ascending order:

sort(): {{ sort([3,1,2]) }}
sort(): [1,2,3]

Join a list with a separator:

{{ join([1,2,3], " + ") }}
{{ join(users, ", ") }}
1 + 2 + 3
User A, User B, User C

Generate a list as a range of integers:

{% for i in range(4) %}{{ loop.index1 }}{% endfor %}
1234

Access elements using a dynamic index with at(). Note that the index is zero-based.

{% set x = [1,2,3] -%}
{% set i = 2 -%}
{{ x.2 }}
{{ at(x, i) }}
3
3

JSON Objects

Access values using a dynamic key with at():

{% set x = {"a": 1, "b": 2} -%}
{% set key = "b" -%}
{{ x.b }}
{{ at(x, key) }}
2
2