Go to the website

Jinja basics

Key syntax concepts for working with the Jinja template engine

Despite not being a programming language, Jinja has its own conepts and rules that form its syntax. This syntax allows you to write a code and tell the system what to do using HTML. Jinja is called a template language because it's used to create templates that can be filled with dynamic data.

Jinja templates can be used directly in Dashly's admin panel for creating triggered or manual messages. Jinja does not require a specific file extension and can generate any text format, such as HTML, XML, CSV, LaTeX, etc.

Delimiters

Jinja code is often embedded in text or other types of code, such as HTML for Email. To do this, special characters (delimeters) are used to distinguish Jinja code from regular template text or other code. They indicate where the Jinja code begins and ends. The default Jinja delimiters are configured as follows:

  • {% ... %} for Statements. Used to output variable values or expression results.

  • {{ ... }}  for Expressions to print to the template output. Used for control structures and logical operations. For example, commands, loops, conditions, variable creation, and function calls.

  • {# ... #}  for Comments not included in the template output. Used for comments inside your code. Make your Jinja code more understandable to other people.

Variables

One of the core features of Jinja is variables. They allow you to store values during template rendering. Template rendering is the process of converting a template with dynamic data into the final HTML or other text format that will be displayed to the end user. In simple terms, this is when a template is turned into a finished web page or document.

A variable always has a name by which it can be accessed, as well as a type. The type determines what values the variable can store and what operations (expressions) can be performed on them. Jinja automatically determines the type of a variable when it is created based on the value assigned, so you don’t need to worry about this.

The main types of variables in Jinja are:

  • Integers (int): Whole values, such as 1, 42, -5.
  • Float: Fractional values, such as 3.14, -0.001.
  • Strings (str): Text data, such as "hello", "world".
  • Booleans (bool): Logical values that can be True or False.
  • Lists (list): A set of elements, such as [1, 2, 3], ["apple", "banana"].
  • Dictionaries (dict): A set of key-value pairs, such as {"name": "Alice", "age": 30}.

Creating Variables

To use a variable, you first need to create it and assign it a value. This is done with the set  command. For example, the command {% set favorite-color = "red" %}  will create a variable favorite-color  and store the word "red" in it. You can then use this variable anywhere in your code by simply specifying its name.

{% set favorite-color = "red" %}
{{ favorite-color }}
Output: red

Using conditions

When creating a variable, you can use the conditional statements if , else  and elif  . An example of using if/else  when creating a variable:

{% set name = user.name | title if user.name else "Dear customer" 

An example without using if/else  when creating a variable:

{% set name = "Dear customer" %}
 
{% if user.name %}
{% set name =  user.name | title %}
{% endif %}
 
{{ name }}

💡 Be sure to set the value of variables before using them, otherwise the parser won't be able to understand what you mean by the variable name.

Variable Properties

Sometimes you need to know the values of certain properties (variables) of an object. For example, what value is stored in the "name" property of the "user" object.

There are two ways to get the properties of a variable:

  • Square brackets: Use variable['property']  to get the value of a property. This is the preferred method.
{{ user["name"] }}  <!-- Will output the value of the name property of the user object -→
  • Dot notation: You can also use variable.property  to access property values.

Please note: To avoid errors, it's better to stick to the variable['property']  notation. While these two notations should generally be equivalent, there are known cases where using variable.property  causes critical issues.

For example:

{% set user = {'name': 'Alice', 'age': 30} %}
{{ user['name'] }}  <!-- output Alice -->
{{ user['age'] }}   <!-- output 30 -->


None Value

When Jinja receives a None value, it converts it to the "None" string. This means that if you use a value from a function or variable that returns None , you will see the string "None" in the template.

{% set result = None %}
Value: {{ result }} <!-- Outputs "None" -->

Expressions

Jinja supports simple expressions similar to those used in Python. Even if you are not familiar with Python, they are easy to use. You can read more about expressions in the official Jinja documentation, here we will cover the basic expressions:


Mathematical expressions

Jinja allows you to use arithmetic operations on numbers directly in the template. This is useful for calculating values based on data. They are performed using the following operators:

+ — addition;
- — subtraction;
* — multiplication;
/ — division;
// — performs integer division with rounding down. For example, 20 // 7 returns the result 2 (20 is divided by 7 twice with a remainder);
%  — calculates the remainder of the division. For example, 20 % 7 returns 6 (when dividing 20 by 7, the remainder is 6).

{% set a = 10 %}
{% set b = 3 %}
 
Addition: {{ a + b }}  <!-- output 13 -->
Subtraction: {{ a - b }}  <!-- output 7 -->
Multiplication: {{ a * b }}  <!-- output 30 -->
Division: {{ a / b }}  <!-- output 3.3333... -->
Integer division: {{ a // b }}  <!-- output 3 -->
Division remainder: {{ a % b }}  <!-- output 1 -->


Comparison Expressions

Used to compare values and make decisions based on those comparisons. They allow you to perform different actions depending on how the values relate to each other.

== — compares two objects for equality;
!= — compares two objects for inequality;
> — returns true if the left side is greater than the right;
>= — returns true if the left side is greater than or equal to the right;
< — returns true if the left side is less than the right;
<= — returns true if the left side is less than or equal to the right.

{% set age = 20 %}
 
{% if age == 18 %}
You are 18 years old.
{% elif age > 18 %}
You are over 18 years old.
{% else %}
You are under 18 years old.
{% endif %}


Logical expressions

These are used to make decisions in templates. They allow you to perform different actions depending on the conditions of the expression using logical operators:

and — returns true if both conditions are true;
or — returns true if at least one of the conditions is true;
not  — returns true if the condition is false.

{% set age = 20 %}
 {% set country = "Canada" %}
 {% set has_permission = False %}
 {% set is_member = True %}
 
{% if age > 18 and country == "Canada" %}
   You're an adult in Canada.
 {% endif %}
 
{% if age > 18 or has_permission %}
   You can log in.
 {% endif %}
 
{% if not is_member %}
  Please register.
 {% else %}
  Welcome, member!
 {% endif %}
Powered by