Инструкция по Jinja-подстановкам
Jinja - это язык для шаблонизации, с помощью которого можно создавать шаблоны и заполнять их изменяющимися данными.
У Jinja есть набор правил, образующий синтаксис, с помощью которого можно формировать конструкции «кода» и объяснять системе, что нужно сделать и какой контент вывести клиенту.
В VK CXhub Jinja используется для подстановки динамических значений в сообщения бота. Представьте, что у вас есть шаблон, в котором описаны условия, что и как должно выглядеть в сообщении. Когда VK CXhub обрабатывает запрос по конкретному клиенту в процессе работы сценария, Jinja заменяет эти конструкции на реальные данные из профиля клиента, списка событий клиента или из данных шагов согласно прописанным условиям и генерирует итоговое сообщение с нужными данными, которое отправляется пользователю.
Например, вы хотите добавить персонализацию в приветствие, но у вас в базе не у всех клиентов заполнено поле «Имя». Вы можете с помощью конструкции Jinja задать условие, что если в профиле клиента есть имя, то в приветствие добавляем обращение по имени, а если имени нет, то просто пишем «Здравствуйте» или вместо имени подставляем заданное значения по умолчанию, например «Дорогой клиент».
Таким образом, Jinja-подстановки полезны для:
- Создания персонализированного контента.
- Создания контента с данными из базы данных.
- Создания контента, которые изменяются в зависимости от действий пользователя.
Это позволяет создавать сообщения в сценариях более интересными и персонализированными, а также упрощает создание сценариев и сокращает количество веток внутри сценария для разных условий, так как в ряде случаев разные условия можно прописать в одной конструкции Jinja.
Для вашего удобства мы создали набор готовых шаблонов значений, которые вы можете использовать для своих задач. Каждый шаблон можно редактировать и дорабатывать в рамках шага, на котором он используется:
1. Зайдите в шаг, в котором хотите использовать шаблон Jinja, нажмите на поле, в котором вы хотите создать сообщение с подстановкой значения. Слева появится окно с названием «Подстановка переменных и смайлов». Под названием вы увидите панель с иконками - выберите вкладку, указанную на изображении ниже. При выборе этой вкладки вы увидите ее название «Шаблоны значений» и список шаблонов:
2. Выберите в списке шаблон, который хотите использовать, и нажмите на него. Значения из него автоматически подставятся в поле в виде фрагмента кода. Преднастроенные шаблоны не требуют внесения изменений, вы можете использовать их в текущем виде. Но при необходимости вы можете вносить изменения в конструкцию Jinja прямо в поле ввода.
Помимо шаблонов, вы можете выбирать нужные переменные из данных внутри шагов сценария. Вы сможете сделать это после прохождения сценария тестовым клиентом.
Подробнее о подстановке переменных клиентов вы можете прочесть в инструкции: https://help.apicxhub.ru/obnovlit-peremennie-klientov-cherez-stsenariy.
1. Чтобы добавить свою переменную и ее значение, добавьте переменную в проект VK CXhub, воспользовавшись инструкцией: https://help.apicxhub.ru/peremennie-klientov#sozdanie-peremennih.
2. После этого в настройках шага «Обновить переменные клиента» выберите новую переменную из списка и введите необходимые значения в шаге сценария вручную. Для этого нажмите на две фигурные скобки над полем ввода переменной. Аналогичным образом можно добавлять конструкции и в сообщения бота, СМС или Email-рассылки.
1. Переменные
Вы можете вставлять переменные в текст сообщения бота, чтобы отображать динамические данные. Например, вместо статического текста используйте {{ client['FirstName'] }}, и Jinja заменит его на значение переменной «Имя» client['FirstName'] из профиля клиента.
Для получения переменной или вызова функций, в Jinja используются двойные фигурные скобки {{ }}. Например, переменные клиентов в VK CXhub имеют вид:
- {{ client['FirstName'] }} –Имя клиента
- {{ client['Phone'] }} – Телефон клиента
В переменные можно добавлять фильтры. Например:
- Upper – фильтр для преобразования значения client.FirstName в верхний регистр, то есть {{ client.FirstName | upper }} вернет имя клиента, написанное заглавными буквами.
- Random – фильтр для выбора случайного числа в заданном диапазоне. Таким образом {{ range(1000, 9999) | random }} вернет случайное число в диапазоне от 1000 до 9999 включительно.
2. Условия
Jinja поддерживает условные конструкции, позволяя вам отображать разные части шаблона в зависимости от условий. Например, когда вы хотите показывать разные вещи в зависимости от ситуации: если пользователь в первый раз проходит сценарий, можно показать ему сообщение "Добро пожаловать!", а если прохождение повторное — "С возвращением!".
Для условных конструкций используются операторы «если — то» (if...else) — это управляющая конструкция, которая в зависимости от условия выбирает, какой блок кода выполнить.
Синтаксис условных операторов выглядит следующим образом:
{% if condition %}...{% elif condition %}...{% else %}...{% endif %}. Условные операторы могут включать if, elif и else.
3. Циклы
В Jinja можно использовать циклы для повторения элементов. Например, у вас есть товары с одинаковым набором параметров (название, стоимость, описание), и вы хотите отобразить их списком в email-письме, где будет повторяться один и тот же элемент (товар) с разными значениями.
Вам необходимо использовать конструкцию {% for item in sequence %}...{% endfor %}, которая позволяет повторять блок кода для каждого элемента в заданной последовательности.
4. Фильтры
Jinja позволяет использовать фильтры для изменения вывода данных. Например,
- Форматирование строк. Фильтр capitalize делает первую букву строки заглавной, а остальные — строчными.
- Форматирование чисел. Фильтр format позволяет форматировать числа. Например, можно отобразить число с двумя знаками после запятой.
- Работа с датами. Фильтр date позволяет форматировать даты. Например, можно отобразить дату в формате «день-месяц-год».
- Объединение строк. Фильтр join позволяет объединять элементы списка в строку с заданным разделителем.
- Удаление пробелов. Фильтр trim удаляет пробелы в начале и конце строки.
- Проверяйте шаблоны на различных данных, чтобы убедиться, что они работают корректно во всех сценариях.
- Перед использованием переменной в конструкции Jijja убедитесь, что она есть в списке переменных в VK CXhub.
- Следите за пробелами. Некоторые фильтры могут игнорировать пробелы в строках. Используйте фильтр trim, чтобы удалить лишние пробелы, если это необходимо. Например, {{ " Привет! "|trim }}
- Убедитесь, что вы используете правильный синтаксис для фильтров.
Например, фильтры применяются через вертикальную черту (|), и не забудьте про пробелы между переменной и фильтром. Оба варианта ниже являются правильными:
{{ variable | filter }}
{{ variable|filter }}
Более подробно о шаблонизаторе Jinja и синтаксисе вы можете почитать в официальной документации https://jinja.palletsprojects.com/en/stable/switching/.