Skip to main content

Jinja's Basic Concepts

The Jinja language, like most template languages, allows, through specific tags in a text, a definition of expressions that are interpolated by the engine to render the final result.

Jinja markup in text can be:

  • {{ ... }}, for expressions that will be rendered;
  • {% ... %}, for control structures;
  • {# ... #}, for comments.

Check out a simple example of a Jinja template below:

<!DOCTYPE html>
<html lang="en">
<head>
    <title>My Webpage</title>
</head>
<body>
    {# print a Hello message for each name in names list #}
    {% for name in names %}
    <h1>Hello {{ name }}!</h1>
    {% endfor %}
</body>

When the variable name is given the values ['John', 'Mary'], the template rendering should return the following result below:

<!DOCTYPE html>
<html lang="en">
<head>
    <title>My Webpage</title>
</head>
<body>
    <h1>Hello João!</h1>
    <h1>Hello Maria!</h1>
</body>

In summary, when evaluated by the StackSpot template engine, Jinja expressions and control structures are processed to produce the final result.

Jinja expressions

Expressions must be enclosed within {{ ... }}, this indicates something that should be rendered by Jinja. Expressions can contain literal values, variables, calculations and complex expressions.

To learn more about all the Jinja expressions, check the Jinja documentation.

Filters

Variables can be transformed using filters. The syntax for applying a filter to a variable is:

{{ variable | filter }}

It is possible to apply more than one filter by chaining together several pipes (|), as in the example below:

{{ variable | filter1 | filter2 }}

In the above example the variable value is modified by filter1 and then modified by filter2.

Check the example of the default capitalize filter:
This filter converts the entered name to the format where, the first letter is uppercase and the others are lowercase.

{{ name | capitalize }}

For more information on Jinja's default filters, see the Jinja documentation.

You can provide an optional third argument count, only the first occurrences of count will be replaced:

# {{ "string value" |regex_replace("substring pattern", "replacement string") }}
{{ "Hello World"|regex_replace("Hello", "Goodbye") }}
    -> Goodbye World

# {{ "string value" |regex_replace("substring pattern", "replacement string", count) }}
{{ "aaathree"|replace("a", "two", 2) }}
    -> two, two, athree

You can use variables that contain the value to be replaced:

Consider that the variable hello_word has the value "dogs, cats, birds";

# {{ variable|regelex_replace('substring pattern', 'replacement string')}}
{{ hello_world|regex_replace('birds', 'humans') }}
    -> docs, cats, humans

The variable hello_word now has the value "dogs, cats, humans".

It is possible to use the regular expression groups in the replacement string in the replacement field:

Consider that the variable hello_word has the value 'burger';

# {{ string value or variable | regex_replace(define group pattern, replacement string group)}}
{{ hello_world|regex_replace('((\w+\s*)+)', 'cheese\1y') }}
    -> cheeseburger

The variable hello_word now has the value 'cheeseburger'.

  • from_json: Converts a string in JSON format into a python dict.

Consider the JSON string:

{
   "input1": "value1"
}

To use the Python dict in JINJA, you must access it as follows:

{% set my_dict = json_input | from_json %}
{{my_dict.input1}}

Control structures

The control structures present in Jinja are the if/elif/else/endif and for/else/endfor.

Use the if/elif/else/endif structure

Commands of the if/elif/else/endif structure allow you to define blocks that will be rendered according to a condition. The example below illustrates the use of an if block to control the printing of part of a template:

{% if age >= 18 %}
Would you like a drink?
{% elif >= 5 %}
Would you like a soft drink?
{% else %}
Would you like a juice?
{% endif %}

In the example above, logic is implemented to determine the message that will be printed according to the value of the variable age.

The comparison operators available in Jinja are:

  • ==: Compares the two operands, returning true if they are equal.
  • !=: Compares the two operands, returning true if they are different.
  • >: true if the operand on the left is larger than the operand on the right.
  • >=: true if the operand on the left is greater than or equal to the operand on the right.
  • <: true if the operand on the left is smaller than the operand on the right.
  • <=: true if the operand on the left is less than or equal to the operand on the right.

The following logical operators can be used in expressions:

  • and: Returns true if both left and right expressions are true.
  • or: Returns true if one of the expressions is true.
  • not: Denies the result of an expression.
  • (expr): Group logical expressions.

The elif and else blocks are optional, and you can use more than one elif block if you need to.

Use the for/else/endfor structure

The for/else/endfor commands allow you to define a repeating block for each element in a list as in the example below:

{% for name in names %}
Hello {{ name }}!
{% else %}
No names given!
{% endfor %}

In the example above, for each name in the names list a line with a salutation for the name entered will be rendered.

If the list of names is empty the contents of the block after the else will be rendered.

The else block is optional and can be omitted if not needed.

Next Steps