Сниппеты¶
Примечание
Данный функционал появился с версии 4.4.1.
Сниппет — выделенная часть шаблона, пригодная для повторного использования. Классические примеры сниппетов — это “шапка” и “подвал”, которые подключаются во всех шаблонах почтовых уведомлений. Сниппеты не имеют своего контекста и переменных, контекст и переменные наследуются от шаблона, вызывающего сниппет.
Функциональность сниппетов доступна как для шаблонов почтовых уведомлений, так и для шаблонов документов.
Пример подключения сниппета в шаблон:
{{ snippet("header") }}
Пример подключения сниппета в шаблон c дополнительными переменными:
{{ snippet("header", {"title": product.name}) }}
Типы сниппетов¶
Все сниппеты в системе разделены на типы. Это разделение позволяет разграничить доступ к сниппетам из разных типов документов. Например, сниппеты типа mail
доступны для всех почтовых уведомлений и недоступны для документов.
Структура данных¶
Для хранения основной информации о сниппетах используется таблица cscart_template_snippets
, содержащая следующие столбцы:
Название | Тип | Описание |
---|---|---|
snippet_id | id | Автоинкрементный идентификатор |
code | varchar(128) | Символьный код |
type | varchar(32) | Тип |
template | text | Шаблон |
default_template | text | Шаблон по умолчанию |
status | char(1) | Статус |
handler | text | Название функции-обработчика сниппета |
params | text | Дополнительные параметры |
addon | varchar(32) | Идентификатор модуля-владельца сниппета. |
updated | int | UNIX timestamp обновления |
created | int | UNIX timestamp создания |
Название сниппета является языкозависимым и хранится в отдельной таблице cscart_template_snippet_descriptions
.
Программный интерфейс¶
Для управления и взаимодействия со сниппетами реализованы следующие классы:
\Tygh\Template\Snippet\Snippet
— модель сниппета. Является программным представлением структуры сниппета.\Tygh\Template\Snippet\Repository
— репозиторий сниппетов. Класс реализует низкоуровневые методы получения/добавления/обновления/удаления сниппетов в БД. Экземпляр класса доступен из контейнераTygh::$app['template.snippet.repository']
.\Tygh\Template\Snippet\Service
— сервис. Класс реализует более высокоуровневые методы управления сниппетами. Экземпляр класса доступен из контейнераTygh::$app['template.snippet.service']
.\Tygh\Template\Snippet\Exim
— класс реализует логику экспорта и импорта сниппетов. Экземпляр класса доступен из контейнераTygh::$app['template.snippet.exim']
.
Схема формирования отображения сниппета¶
- Определение типа сниппета из контекста. Каждый контекст, в котором вызывается сниппет, знает какие сниппеты для него доступны. Контекст на программном уровне представляет собой класс, реализующий интерфейс
ITemplate
. - Получение шаблона сниппета по типу и символьному идентификатору. Для этого используется класс
\Tygh\Template\Snippet\Repository
. - Вызов пре-хука
'template_snippet_render_pre'
. - Вызов шаблонизатора для формирования отображения сниппета.
- Вызов пост-хука
'template_snippet_render_post'
. - Возврат результата.
Добавление сниппетов¶
Модули могут добавлять свои сниппеты любого типа. Предполагается, что добавление сниппетов будет происходить в момент установки модуля, а удаление — в момент удаления модуля. Для добавления можно воспользоваться методами класса \Tygh\Template\Snippet\Service
, либо воспользоваться возможностью описать сниппеты в схеме модуля. Пример:
<?xml version="1.0"?>
<addon scheme="3.0">
<id>my_changes</id>
<snippet_templates>
<item>
<type>order_invoice</type>
<code><![CDATA[some_snippet]]></code>
<default_template><![CDATA[Content]]></default_template>
<status><![CDATA[A]]></status>
<name>
<en><![CDATA[Order invoice snippet]]></en>
</name>
<addon><![CDATA[my_changes]]></addon>
</item>
</snippet_templates>
</addon>
Расширение сниппетов¶
Бывают ситуации, когда для формирования шаблона недостаточно визуального редактора, или он не эффективен, или же необходимы дополнительные структурированные данные.
Например, для вывода списка товаров в документе “order.invoice” необходимо выводить таблицу, которую можно легко расширять. Очевидно, что делать это в визуальном редакторе документов не очень удобно. Для решения таких проблем были добавлены соответствующие хуки, которые позволяют влиять на формирование отображения сниппетов и расширять интерфейс на страницах редактирования сниппетов и документов.
PHP-хуки¶
'template_snippet_render_pre'
— выполняется перед формированием отображения сниппета. Этим хуком можно добавить необходимые переменные, которые впоследствии можно будет использовать в шаблоне сниппета:fn_set_hook('template_snippet_render_pre', $snippet, $context, $variable_collection)
'template_snippet_render_post'
— выполняется после формирование отображения сниппета:fn_set_hook('template_snippet_render_post', $snippet, $context, $variable_collection, $result)
'template_snippet_remove_post'
— выполняется после удаления сниппета:fn_set_hook('template_snippet_remove_post', $this, $snippet)
'template_snippet_save_post'
— выполняется после сохранения сниппета в БД:fn_set_hook('template_snippet_save_post', $this, $snippet, $lang_code)
Template-хуки¶
{hook name="snippets:tabs_extra"}{/hook}
(design/backend/templates/views/snippets/update.tpl) — позволяет добавлять новые вкладки во всплывающее окно редактирования сниппета.
Шаблонизатор¶
В качестве шаблонизатора используется библиотека Twig (версия 1.24). Подключены стандартные расширения:
- Twig_Extensions_Extension_Text
- Twig_Extensions_Extension_Array
- Twig_Extension_Debug — только в режиме разработки.
Добавлены дополнительные фильтры и функции:
Фильтр date — предназначен для форматирования значения в виде даты.
Если вы используете этот фильтр, не забудьте указать формат даты. Например:
{{ o.raw.timestamp }}
будет выглядеть как 1127988066 (неформатированное UNIX-время).{{ o.raw.timestamp|date("%d/%m/%Y") }}
будет выглядеть как 29/09/2005 (время в понятном человеку формате).
Вот форматы времени, которые можно выбрать в CS-Cart:
Формат даты Отображаемая дата Описание "%d/%m/%Y"
29/09/2005 день/месяц/год "%d-%m-%Y"
29-09-2005 день-месяц-год "%d.%m.%Y"
29.09.2005 день.месяц.год "%m/%d/%Y"
09/29/2005 месяц/день/год "%m-%d-%Y"
09-29-2005 месяц-день-год "%m.%d.%Y"
09.29.2005 месяц.день.год "%Y/%m/%d"
2005/09/29 год/месяц/день "%Y-%m-%d"
2005-09-29 год-месяц-день "%Y.%m.%d"
2005.09.29 год.месяц.день "%b %e, %Y"
Сен 29, 2005 месяц день, год "%d %b %Y"
29 Сент 2005 день месяц год "%A, %B %e, %Y"
Четверг, Сентябрь 29, 2005 день недели, месяц день, год "%A, %e %B %Y"
Четверг, 29 сентября 2005 день недели, день месяц год Фильтр price — предназначен для форматирования значения в виде денежного типа. Например,
{{ o.raw.total }}
будет выглядеть как 2334.55, а{{ o.raw.total|price }}
— как 2 334.55 Р.Фильтр filesize — предназначен для форматирования значения в виде размера файла в килобайтах. Например, он используется в шаблоне электронного письма о доступе к скачиваемым товарам:
{{ file.file_size|filesize }}
.Фильтр puny_decode — предназначен для декодирования URL-адресов из PunyCode в интернациональное представление. Этот фильтр можно найти в шаблонах email-уведомлений, которые содержат URL, например, в письмах о смене пароля:
{{ url|puny_decode }}
.Функция __ — предназначена для вывода переводов. Например, вместо кода
{{__("change_order_status_c_text")}}
в русской версии документа появится соответствующее значение языковой переменной: Ваш заказ был выполнен. Спасибо, что выбрали нас.Функция snippet — предназначена для подключения сниппетов. Например, код
{{ snippet("ship_to") }}
в документе Счет добавляет в документ соответствующий сниппет со вкладки Сниппеты.Функция include_doc — предназначена для подключения документов в тело почтового уведомления. Например, в email-уведомлениях о статусах заказов есть следующая строка:
{{ include_doc("order.summary", order_info.order_id) }}
.Это строка добавляет документ
order.summary
(детали заказа) в тело этих почтовых уведомлений.
Подсказка
Более подробную информацию о шаблонизаторе вы можете узнать из официальной документации: http://twig.sensiolabs.org/