Базовый синтаксис Jinja

Несмотря на то, что Jinja не является языком программирования, у него есть свои ключевые слова и правила, которые вместе образуют синтаксис. Этот синтаксис позволяет писать «код» и объяснять компьютеру, что нужно сделать, на понятном ему языке HTML. Jinja называют языком шаблонизации, потому что он используется для создания шаблонов, которые могут быть заполнены динамическими данными.

В основном вы будете создавать шаблоны Jinja прямо в панели администратора Carrot quest. Однако вы также можете записывать их в обычные текстовые файлы. Jinja не требует определенного расширения файла и может генерировать любой текстовый формат, например HTML, XML, CSV, LaTeX и т.д.

Разделители

Код Jinja часто вставляется в текст или в другие типы кода, например, в HTML для Email. Для этого используют специальные символы, которые помогают отличать код Jinja от обычного текста в шаблоне или другого кода. Они показывают, где начинается и заканчивается код Jinja.

В таблице ниже указаны необходимые разделители:

Переменные

Одна из основных функций Jinja — это переменные. Они позволяют сохранять значения во время рендеринга шаблона. Рендеринг шаблона — это процесс преобразования шаблона с динамическими данными в окончательный HTML или другой текстовый формат, который будет отображаться конечному пользователю. Проще говоря, это когда шаблон с переменными и логикой превращается в готовую веб-страницу или документ.

У переменной всегда есть имя, по которому к ней можно обратиться, а также тип. Тип определяет какие значения может хранить переменная и какие операции (выражения) с ними можно выполнять. Jinja автоматически определяет тип переменной при её создании на основе присвоенного значения, поэтому не стоит об этом беспокоиться.

Основные типы переменных в Jinja:

• Целые числа (int): Целые значения, например, 1, 42, -5.
• Числа с плавающей запятой (float): Дробные значения, например, 3.14, -0.001.
• Строки (str): Текстовые данные, например, "hello", "world".
• Булевы значения (bool): Логические значения, которые могут быть True или False.
• Списки (list): Набор элементов, например, [1, 2, 3], ["apple", "banana"].
• Словари (dict): Набор пар "ключ-значение", например, {"name": "Alice", "age": 30}.

Создание переменных

Чтобы использовать переменную, её сначала нужно создать и задать ей значение. Это делается с помощью команды set . Например, команда {% set favorite-color = "красный" %}  создаст переменную favorite-color  и сохранит в ней слово "красный". После этого вы сможете использовать эту переменную в любом месте кода, просто указав её имя.

{% set favourite-color = "красный" %}
{{ favourite-color }}
Output: красный

Создание с условиями

При создании переменной можно использовать условные операторы if , else и elif . Пример использования if/else  при создании переменной:

{% set name = user.name | title if user.name else "Дорогой клиент" 

Пример без использования if/else  при создании переменной:

{% set name = "Дорогой клиент" %}
 
{% if user.name %}
{% set name =  user.name | title %}
{% endif %}
 
{{ name }}

💡 Обязательно задавайте значение переменных перед их использованием, иначе парсер не сможет понять, что вы имеете в виду под именем переменной.

Cвойства переменных

Иногда вам нужно узнать значения определенных свойств (переменных) у объекта. Например, какое значение хранится в свойстве «name» у объекта «user».

Есть два способа получить свойства переменной:

• Квадратные скобки: Используйте variable['property'] , чтобы получить значение свойства. Это наиболее предпочтительный способ.

{{ user["name"] }}  <!-- Выведет значение свойства "name" у объекта user -→

• Точечная нотация: Вы также можете использовать variable.property  для доступа к значениям свойств.  

Обратите внимание: Чтобы избежать ошибок, следует придерживаться обозначения variable['property']  в квадратных скобках. Хотя в целом эти два обозначения должны быть эквивалентны, известны случаи, когда использование variable.property  приводит к критическим проблемам в нашем сервисе.

Например: 

{% set user = {'name': 'Alice', 'age': 30} %}
 {{ user['name'] }}  <!-- Выведет Alice -->
 {{ user['age'] }}   <!-- Выведет 30 -->

Значение None

Когда Jinja получает значение None , оно преобразует его в строку "None" . Это значит, что если вы используете значение из функции или переменной, которая возвращает None , то в шаблоне вы увидите строку "None" .

Пример:

{% set result = None %}
 Значение: {{ result }}  <!-- Выведет "None" -->

Выражения

Jinja поддерживает простые выражения, похожие на те, что используются в Python. Даже если вы не знакомы с Python, они легки в использовании. Подробнее прочитать про выражения вы можете в официальной документации Jinja, здесь мы рассмотрим основные выражения:

Математические выражения

В Jinja можно использовать арифметические операции над числами прямо в шаблоне. Это полезно для вычисления значений на основе данных. Выполняются они с помощью операторов:

+ — сложение;
- — вычитание;
* — умножение;
/ — деление;
// — выполняет целочисленное деление с округлением вниз. Например, 20 // 7 возвращает результат 2 (20 делится на 7 два раза с остатком);
%  — вычисляет остаток от деления. Например, 20 % 7 вернёт 6 (при делении 20 на 7 остаток равен 6).

Пример:

{% set a = 10 %}
{% set b = 3 %}
 
Сложение: {{ a + b }}  <!-- Выведет 13 -->
Вычитание: {{ a - b }}  <!-- Выведет 7 -->
Умножение: {{ a * b }}  <!-- Выведет 30 -->
Деление: {{ a / b }}  <!-- Выведет 3.3333... -->
Целочисленное деление: {{ a // b }}  <!-- Выведет 3 -->
Остаток от деления: {{ a % b }}  <!-- Выведет 1 -->

Сравнительные выражения

Используются для сравнения значений и принятия решений на основе этих сравнений. Они позволяют выполнять разные действия в зависимости от того, как значения соотносятся друг с другом.

== — cравнивает два объекта на предмет равенства;
!= — cравнивает два объекта на предмет неравенства;
> — возвращает true, если левая часть больше правой;
>= — возвращает true, если левая часть больше или равна правой части;
< — возвращает true, если левая часть меньше правой;
<= — возвращает true, если левая часть меньше или равна правой части.

Пример:

{% set age = 20 %}
 
{% if age == 18 %}
  Вам 18 лет.
{% elif age > 18 %}
  Вы старше 18 лет.
{% else %}
  Вы моложе 18 лет.
{% endif %}

Логические выражения

Используются для принятия решений в шаблонах. Они позволяют выполнять разные действия в зависимости от условий выражения с помощью логических операторов:

and — возвращает true, если оба условия истинны;
or — возвращает true, если хотя бы одно из условий истинно;
not — возвращает true, если условие ложно.

Пример:

{% set age = 20 %}
 {% set country = "Russia" %}
 {% set has_permission = False %}
 {% set is_member = True %}
 
{% if age > 18 and country == "Russia" %}
  Вы совершеннолетний в России.
 {% endif %}
 
{% if age > 18 or has_permission %}
  Вы можете войти.
 {% endif %}
 
{% if not is_member %}
  Пожалуйста, зарегистрируйтесь.
 {% else %}
  Добро пожаловать, член клуба!
 {% endif %}

Другие статьи про Jinja:

Структура данных в Jinja
Фильтры в Jinja
Персонализация с помощью Jinja
Полезные заготовки Jinja-кода