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

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

Для створення шаблонів повідомлень, шаблонів документів для замовлень чи воронок використовується шаблонізатор 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 — отримує значення в тому вигляді, в якому вони є (без екранування).

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