Scriban — это быстрый, безопасный и мощный язык для создания текстовых шаблонов.
Здесь будут рассмотрены некоторые из его возможностей.
Базовые конструкции
Важно запомнить, что все конструкции языка заключаются в двойные фигурные скобки,
которые заменяются на соответствующие им результирующие строки в процессе обработки шаблона.
Возьмем пример:
{{ x = "5" }}
Пример выше показывает объявление переменной. Переменные могут быть объявлены в любом месте
шаблона,
и при выводе данная строка будет заменена на пустую.
Значение, присвоенное переменной, выводится следующим образом:
{{ x = "5"
x }}
В результате выполнения команды в шаблоне выведется «5».
В Scriban переменные бывают двух типов — числовые и строковые.
Для каждого типа есть набор поддерживаемых операций:
— для числовых:
- + {{ y = x + 1 }} — сложение;
- – {{ y = x – 1 }} — вычитание;
- * {{ y = x * 2}} — умножение;
- / {{ y = x / 2}} — деление;
- // {{ y = x // 2}} — деление с округлением до целого;
- % {{ y = x % 2}} — остаток от деления (на 2 в данном случае);
— для строковых:
- + {{ name = ('foo' + 'bar') }} — сложение строк.
С переменными можно производить операции сравнения с помощью специальных операторов:
Оператор |
Описание |
== |
левый операнд равен правому |
!= |
левый операнд не равен правому |
> |
левый операнд больше правого |
>= |
левый операнд больше или равен правому |
< | левый операнд меньше правого
|
<= | левый операнд меньше или равен правому
|
!x |
логическое отрицание от «x» |
&& |
логическое И |
|| |
логическое ИЛИ |
В Scriban есть зарезервированные имена, использовать которые для объявления переменных
не рекомендуется.
Одним из таких имен является empty (empty представляет собой пустой объект и является
аналогом null
в других языках программирования).
Условные операторы и циклы
В Scriban есть поддержка циклов и условных операторов.
Условные операторы позволяют осуществлять вывод данных в зависимости от какого-либо условия.
{{ if !page }}Page is not null{{ else }}Page is null!{{ end }}
В результате выполнения этого условия выведется «Page is null», если в переменной
ничего нет,
и «Page is not null», если переменная содержит какую-либо информацию.
Циклы в Scriban строятся на основе условных операторов и, помимо прочего, позволяют
работать с коллекциями
(наборами однотипных данных). Различают несколько видов циклов:
- {{for ‹variable› in ‹expression›}} , где ‹variable› — это переменная, а ‹expression› —
массив данных.
Пример:
{{ for page in pages }}This is the page {{ page.title }}{{ end }}
В данном случае выполняется проход по коллекции с выводом названия страниц.
Для этого при объявлении цикла была объявлена переменная page,
которая представляет собой один из элементов коллекции (массива) pages.
В эту переменную будет осуществляться запись текущего элемента на каждом шаге цикла.
-
{{ for x in 1..n }}This is the loop step [{{x}}]{{ end }}
В данном примере коллекция создается прямо при объявлении цикла («1..n»).
На каждом шаге «x» будет заменен на соответствующее ему число.
Например, на шаге 2 выведется:
This is the loop step [2]
-
{{while ‹expression›}} ... {{end}}, где ‹expression› — логическое условие, как в условном
операторе.
Данный цикл похож на условный оператор и будет выполняться, пока выражение внутри истинно.
Например:
{{ flag = 0
while flag == 0
if while.index == 3
flag = while.index
end }}
[{{while.index}}] step
{{end}}
Здесь показано использование цикла while. В результате выполнения будет выведено следующее:
[1] step
[2] step
[3] step
Также в данном примере используется специальная переменная while.index, равная
порядковому номеру текущей итерации (шаг цикла). Цикл будет прерван после третьего шага,
когда условие станет ложным.
Все циклы поддерживают операторы break (прерывание цикла) и continue (переход
с следующему шагу). Пример:
{{ for i in 1..5
if i == 2
break
end
}}
[{{i}}]] step
{{ end }}
|
{{ for i in 1..5
if i > 1 && i < 3
continue
end
}}
[{{i}}]] step
{{ end }}
|
В результате выполнения примеров будет выведено соответственно:
[1] step
|
[1] step
[3] step
[4] step
[5] step
|
В цикле for также есть переменная, в которой находится порядковый номер текущей итерации (for.index).
Она используется аналогично while.index в примере выше.
Отдельно стоит обратить внимание на использование логического И в примере с continue:
условие (i > 1 && i < 3) будет аналогично i == 2.
Встроенные функции
В Scriban есть встроенные библиотечные функции, которые могут быть полезны при создании шаблонов.
Например, встроенный объект date.now, который содержит в себе информацию о текущей дате.
Его можно использовать следующим образом:
{{ date.now.‹field› }},
где вместо ‹field› можно подставить любое значение из таблицы, приведенной ниже.
Имя |
Описание |
year |
текущий год |
month |
текущий месяц |
day |
день месяца |
day_of_year |
порядковый номер текущего дня в году |
hour |
текущий час |
minute |
текущая минута |
second |
текущая секунда |
millisecond |
текущая миллисекунда |
Таким образом {{ date.now.year }} заменится в шаблоне на «2019».
Ознакомиться с полной оригинальной документацией можно по ссылке.
Scriban в Pixlpark
В Pixlpark можно использовать Scriban для формирования коммерческих предложений и квитанций заказа.
Для этого необходимо выбрать «Создать новый HTML Scriban шаблон» при создании нового шаблона.
Для созданного таким образом шаблона будут доступны новый набор подсказок и новый синтаксис для построения шаблонов.
Для коммерческого предложения в Pixlpark используется специальный объект «КП»,
доступные свойства которого можно увидеть в «Подсказке по параметрам».
Ниже для примера представлена его структура в нотации JSON.
{
"sales_tax_formatted": " 53,85 руб.",
"cart_price_formatted": " 353,00 руб.",
"total_price_formatted": " 406,85 руб.",
"photolab": {
"id": 2512,
"title": "Pixlpark Бизнес-сувениры",
"address": "",
"email": "info@pixlpark.ru",
"phone": "+7 (495) 545-46-91"
},
"user": {
"id": 0,
"display_name": "Иван Иванов",
"first_name": "Иван",
"last_name": "Иванов",
"email": "ivan@pixlpark.com",
"phone": ""
},
"items": [
{
"id": 3662352,
"size": "5-6 лет",
"weight": 0.0,
"brand": "Fruit of the Loom",
"material": "хлопок 100%, плотность 135 г/м2",
"vendor_code": "610190.30/116",
"description": "Футболка детская Kids Original T",
"quantity": 1.0,
"title": "Футболка детская \"Kids Original T\", белый",
"price": 190.0,
"price_string": " 190,00 руб.",
"cover": "https://example.com/cover1",
"sku_values": "",
"pos_id": "",
"custom_field": "Без нанесения",
"item_parts_quantity": 0,
"position": 1
},
{
"id": 3662353,
"size": "S–XXL",
"weight": 0.0,
"brand": "",
"material": "хлопок 100%, плотность 120 г/м²; джерси",
"vendor_code": "7192.60",
"description": "Качественная футболка для массовых промоакций",
"quantity": 1.0,
"title": "Футболка «Промохит», белая",
"price": 163.0,
"price_string": " 163,00 руб.",
"cover": "https://example.com/cover2",
"sku_values": "",
"pos_id": "",
"custom_field": "Без нанесения",
"item_parts_quantity": 0,
"position": 2
}
],
"general_title": "Коммерческое предложение"
}
Пример использования Scriban в разметке коммерческого предложения:
{{ for item in items }}
‹div class="prod-container"›
‹p class="h1">{{item.title}}‹/p›
‹div class="left-box"›
‹img src="{{item.cover}}"›
‹/div›
‹p›
{{item.description}}
‹/p›
‹ul›
‹li›Размер — {{item.size}}‹/li›
‹li›Материал — {{item.material}}‹/li›
‹li›Вес — {{item.weight}}‹/li›
‹li›Артикул — {{item.vendor_code}}‹/li›
‹/ul›
‹p›
Стоимость тиража {{item.quantity}} (с НДС) = {{item.price}} руб.
‹/p›
‹/div›
{{ end }}
Как и в примерах выше, все свойства вызываются через «.» (например, {{item.price}} ),
а для вывода элементов коллекции необходимо использовать цикл ({{ for item in items }} ... {{ end }}).
Отдельно стоит сказать про поле position: оно показывает порядковый номер элемента в переданной коллекции.
При использовании циклов не рекомендуется использовать position для вывода порядкового номера элемента.
Лучше заменить его специальными переменными цикла: while.index, for.index и прочими,
описанными в официальной документации. При использовании более сложных алгоритмов вывода элементов
(как в примере с continue и break) рекомендуется создать отдельную переменную для сохранения номера позиции внутри нее.