Документация шаблонизатора

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

Наш шаблонизатор использует минимальный синтаксис для выполнения Вашей работы.
Шаблонизатор построен на движке Jinja2, который имеет огромные возможности кастомизации.
Давайте начнем с основ и перейдем к более сложным сценариям.

{
    "name": "Петр Иванович"
}
                               

Работа с переменными

Двойные фигурные скобки {{ }} позволяют получить результат выражения или переменной и вывести значение в шаблоне.

{
    "fruit": "Яблоко",
    "price": 50"
}
                               

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

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

Циклы и управляющие конструкции

Управляющие конструкции позволяют добавлять в шаблоны элементы управления потоком и циклы.
По умолчанию, управляющие конструкции используют разделитель {% %} вместо двойных фигурных скобок {{ }}.

Конструкция if, elif и else

Для понимания работы, давайте сразу рассмотрим несколько примеров.

{
    "name": "Петр Иванович",
    "age": 45
}
                               

В первой строке проверяется, если переменная "name" равна строке "Петр Иванович",
и переменная "age" равно числу 45, то выполнится блок:

Если первое условие не выполняется, то благодаря оператору "elif", проверяем следующее условие, аналогично первому.
В случае, если не выполняется, ни одно из условий, то будет выполнен блок в операторе "else".

Управляющие инструкции также могут быть вложенными.

Если условия становятся слишком сложными, можно обернуть выражения скобками ():

Цикл for

Цикл for позволяет перебирать последовательность.

{
    "name": "Петр Иванович",
    "fruits": {
        "loves": ["Яблоки", "Апельсины"],
        "not_loves": ["Груши", "Ананасы", "Киви"]
    }
}
                               

В шаблоне

В документе

Цикл можно проходить не только по массиву, но и по словарю.

{
  "name": "Петр Иванович",
  "age": 45,
  "about": "Хороший человек"
}
                               

В шаблоне

В документе

Вы не поверите, но той информации, что Вы уже узнали, хватит, что-бы создать динамически наполняемую таблицу.
Рассмотрим пример.

{
    "col_labels": ["Фрукты", "Овощи", "Камни", "Мебель"],
    "tbl_contents": [
        {"cols": ["банан", "перец", "пирит", "стул"]},
        {"cols": ["яблоко", "помидор", "алмаз", "стол"]},
        {"cols": ["апельсин", "картошка", "янтарь", "кровать"]}
    ]
}
                               

В шаблоне

В документе

Конструкция {% colspan <переменная> %} должна быть обязательно.
Для динамического распределения по множеству столбцов.
В документе она не учитывается, и нужна только в шаблоне.

В таблице упомянуты остальные широко используемые атрибуты переменной loop.

Давайте рассмотрим еще один пример. Сделаем форму заказа товаров.

{
    "customer_name": "Иван",
    "items": [
        {"desc": "Апельсины", "qty": 2, "price": "Бесплатно"},
        {"desc": "Мандарины", "qty": 5403, "price": "500,000"},
        {"desc": "Киви", "qty": 1, "price": "100,000,000.00"}
    ],
    "in_europe": true,
    "is_paid": false,
    "company_name": "PRINTDOC",
    "total_price": "100,000,000.00"
}
                               

В шаблоне

В документе

Фильтры

Можно использовать несколько фильтров, чтобы точнее настраивать вывод. Например:

Фильтр striptags удалит из переменной все HTML-теги.
В приведенном выше коде сначала будет применен фильтр striptags, а затем — title.

Фильтр round округляет число до конкретного количества символов.
В следующей таблице указаны широко используемые фильтры.

Теги

Для управления абзацами, строками таблицы, столбцами таблицы, оформлением строк должен использоваться специальный синтаксис.

ВАЖНО: Не используйте {%p, {%tr, {%tc или {%r два раза в том же параграфе, строке или столбце. Пример:

{%p if display_paragraph %} Это мой параграф {%p endif %}

ВАЖНО: Используйте неразрывный пробел ( CTRL + SHIFT + ПРОБЕЛ ), когда требуется пробел в начале или в конце строки.

ВАЖНО: Теги должны располагаться отдельно в строке: не добавляйте текст до или после в той же строке.

ВАЖНО: Всегда ставьте пробел после начального разделителя переменных / тегов

Цвет ячейки

Есть особый случай, когда вы хотите изменить цвет фона ячейки таблицы, вы должны поместить следующий тег в самое начало ячейки:

Колонки динамической таблицы

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

Отображение зарезервированных символов

Для того, чтобы отобразить {%, %}, {{ или }} , можно использовать:

Таблицы

Вы можете растянуть ячейки таблицы по горизонтали двумя способами, используя colspan (см. шаблон: dynamic_table_tpl.docx):

или внутри цикла for (см. шаблон: horizontal_merge_tpl):

Вы также можете объединять ячейки по вертикали в цикле for (см. шаблон: vertical_merge_tpl.docx):

Более подробное описание функционала шаблонизатора, Вы можете найти на официальном сайте Jinja2.

Лучший способ увидеть, как это работает - скачать, и посмотреть примеры.
*.docx файлы - код шаблона и готовый результат (как в документе).
*.json файлы - json код, для передачи в шаблон.