Довідник доступних тегів, функцій та фільтрів Twig

Розповідаємо які теги, функції та фільтри Twig можна використовувати в шаблонах документів та повідомлень
Написано Юлія Бакум
Оновлено 10 місяців тому

Для створення шаблонів повідомлень, шаблонів документів для замовлень чи воронок використовується шаблонізатор Twig.

Доступна більшість стандартних тегів, функцій та фільтрів: 

Теги

  • if аналогічний оператору if у PHP. Можна використовувати для перевірки того, чи є вираз істинним. В умовах доступний також оператор {% else %}.

Наприклад, якщо в замовленні є номер з джерела, то ми виводимо його; якщо ж його немає, то вказуємо номер замовлення з CRM:

{% if model.source_uuid %}{{ model.source_uuid }}{% else %}{{ model.id }}{% endif %} 

  • for — цикл, який перебирає кожен елемент сутності. Використовується для отримання значень з масиву товарів чи оплат.

Наприклад, щоб додати посилання на фіскальний чек, яке міститься в оплатах в середині замовлення, огортаємо змінну в цикл. Цикл перевірить кожну оплату в замовленні та отримає з них посилання на фіскальний чек:

{% for payment in model.payments %}
    {{ payment.fiscal_url }} 
{% endfor %}

  • set — встановлює значення змінної. Можна додавати свої змінні в середині коду для реалізації кастомних розрахунків тощо. 

Наприклад, щоб порахувати залишок до оплати в замовленні, потрібно отримати суму яка вже оплачена з врахуванням, що може бути декілька платежів.

Тому оголошуємо змінну paid_amount з початковим значенням 0. Далі з допомогою циклу додаємо до неї вже сплачені суми:

{% set paid_amount = 0 %}
{% for payment in model.payments %}
  {% if payment.status == "paid" %}
    {% set paid_amount = paid_amount + payment.amount %}
  {% endif %}
{% endfor %}
Залишок до оплати = {{ (model.total_price - model.discount_amount + model.shipping_price - paid_amount)|format_currency('UAH', locale='uk') }}

  •  apply — дозволяє застосовувати фільтри до блоку даних в шаблоні.

Наприклад, можна зробити текст у верхньому регістрі:

{% apply upper %}
    Цей текст буде весь великими літерами
{% endapply %}

Функції

  • date() — перетворює аргумент на дату, щоб забезпечити порівняння дат. Якщо аргумент не передано, функція повертає поточну дату.

Наприклад, умова якщо дата доставки / відправки в замовленні менша ніж дата, яка була 2 дні тому:

{% if date( model.shipping_date_actual) < date('-2days') %}
   дата доставки/відправки була більше 2-х днів тому
{% endif %}

  • max() — знаходить найбільше значення у наборі чи масиві чисел.

Наприклад, якщо потрібно отримати ціну продажу найдорожчого товару в замовленні, щоб застосувати до неї якусь спеціальну пропозицію:

{% set prices = [] %}
{% for product in model.products %}
    {% set prices = prices | merge([product.price_sold]) %}
{% endfor %}
Найдорожча ціна продажу: {{ max(prices) }} грн

  • min() — знаходить найменше значення у наборі чи масиві чисел. 

Наприклад, якщо потрібно знайти товар в замовленні з найнижчою ціною закупівлі:

{% set min_product = null %}
{% set min_price = null %}

{% for product in model.products %}
    {% if min_price is null or product.purchased_price < min_price %}
        {% set min_price = product.purchased_price %}
        {% set min_product = product.product_name %}
    {% endif %}
{% endfor %}

Товар {{ min_product }}, ціна закупу {{ min_price }} грн

Фільтри

Фільтри застосовуються до змінних через вертикальну риску |.

Робота з регістром і форматуванням тексту:

  • capitalize — робить першу букву в рядку великою, а інші маленькі.

Наприклад, місто в адресі доставки покупець може вказати з маленької букви, тоді цей фільтр виправить цей момент:

{{ model.shipping_address_city|capitalize }}

  • lower — форматує усі символи в рядку в нижній регістр.

  • upper — форматує усі символи в рядку в верхній регістр.

  • trim — видаляє пробіли або інші символи з початку та кінця рядка.

Наприклад, обрізаємо символ + в номері телефона покупця:

{{ model.client_phone|trim('+') }}

  • replace — динамічно змінюю текст або форматує його на основі змінних.

Наприклад, якщо в назві товару є слово "free", то замінювати його на "Подарунок":

{% for product in model.products %}
    {{ product.product_name|replace({'free': 'Подарунок'}) }}
{% endfor %}

  • escape — екранує символи у вказаному форматі. 

  • spaceless — видаляє пробіли між тегами HTML або пробіли у простому тексті.

  • nl2br — замінює перенесення рядка на html-тег <br>.

Форматування чисел і валюти:

  • format_number — форматує число по заданому формату.

Наприклад, виводимо загальну вартість замовлення прописом:

{{ model.grand_total|format_number(style="spellout", locale="uk") }}

Наприклад, якщо потрібно вивести ціну продажу товару з двома знаками після коми:

{{ product.price_sold|number_format(2, ',', '') }}

  • format_currency — виводить число у форматі заданої валюти.

Наприклад, форматуємо ціну продажу товару у валюту UAH:

{{ product.product_price|format_currency('UAH', locale='uk') }}

  • round — округлює число до заданої точності.

Приклади округлення загальної вартості замовлення:

Якщо потрібно математичне округлення до меншого чи більшого: 
{{ model.grand_total|round|format_currency(currency, locale='de') }} 

Якщо потрібно округлення завжди до більшого:
{{ model.grand_total|round(0, 'floor')|format_currency(currency, locale='de') }}

Якщо потрібно округлення завжди до меншого: 
{{ model.grand_total|round(0, 'ceil')|format_currency(currency, locale='de') }}

Робота з датами:

  •    date — перетворює дату в рядок у вказаному форматі. 

Приклади форматування сьогоднішньої дати (можна підставляти будь-які змінні які містять дату):

{{ "now"|date("d.m.Y") }} // 05.09.2024 

{{ "now"|date("d-m-y H:i") }} // 05-09-24 11:22

{{ "now"|date("d/m/Y H:i", "Europe/Paris") }} // 05/09/2024 13:24 - дата та час зараз у перекладі на часовий пояс Парижа 

  • date_modify — змінює дату з допомогою заданої умови (модіфікатора).

Наприклад, додаємо до дати створення замовлення 5 днів:

{{ model.created_at|date_modify("+5 day")|date("m.d.Y")}}

  • format_datetime — форматує дату та час по заданому формату.

Операції з масивами:

  • first — отримує перший елемент в масиві.

Наприклад, якщо потрібно вивести тільки посилання на перший файл доданий до замовлення:

{% set filesArray = model.files|split('\n') %}
{{ filesArray|first }}

  • last — отримує останній елемент в масиві.

Наприклад, якщо ви зберігаєте ПІБ покупців у форматі «Петренко Іван» і потрібно вивести тільки ім'я:

{% set foo = model.client_name|split(' ')%}
Вітаю, {{ foo|last }}!

  • slice — обрізає масив у зазначених рамках.

Наприклад, якщо потрібно обрізати назву першої властивості товару: 

{{ product.product_properties|slice(10, 155)}} - виводить текст починаючи з 10 символа до 155

  • sort — сортує масив значень.

Наприклад, сортуємо список назв товарів по алфавіту:

{% for key, product in model.products|sort((a, b) => a.product_name <=> b.product_name)  %}
{{ product.product_name }}
{% endfor %}

  • merge — об'єднує масиви в один.

  • reduce — дозволяє послідовно обробляти кожен елемент масиву та об'єднувати їх в одне значення.

Наприклад, якщо потрібно порахувати загальну кількість штук товару в замовленні:

{{ model.products|reduce((carry, item) => carry + item.product_quantity, 0) }}

  • join — формує рядок з масиву шляхом з'єднання елементів масиву та додаючи роздільник між ними.

  • split — розділяє рядок по заданому роздільнику та повертає список рядків.

Наприклад, якщо потрібно обрізати інші властивості товару і залишати тільки ту, назву якої ви вказали:

{% for product in model.products %}
{% if product.product_properties %}
{% set properties = product.product_properties|split("\n") %}
{% for property in properties %}
{% set parts = property|split(':') %}
{% if parts|length == 2 and parts[0]|trim == 'Розмір' %}
{% set rozmir = parts[1]|trim %}
Розмір: {{ rozmir }}
{% endif %}
{% endfor %}
{% endif %}
{% endfor %}

Загальні та допоміжні:

  • default — повертає передане значення за замовчуванням, якщо значення не визначене або порожнє, інакше значення змінної. 

Наприклад, якщо в замовленні немає телефону покупця, то виведеться текст 'не вказано': 

Телефон: {{ model.client_phone |default('не вказано') }}

    • length — повертає кількість елементів або довжину рядка.

    Наприклад, якщо потрібно порахувати кількість позицій в замовленні:

    Всього найменувань {{ model.products|length }}

      • raw — отримує значення в тому вигляді, в якому вони є (без екранування).

                Теги: твіг, цикли, код шаблонів, формат, оператори
                Чи була наша стаття корисною?