Сниппеты¶

Типы сниппетов¶

Все сниппеты в системе разделены на типы. Это разделение позволяет разграничить доступ к сниппетам из разных типов документов. Например, сниппеты типа mail доступны для всех почтовых уведомлений и недоступны для документов.

Структура данных¶

Для хранения основной информации о сниппетах используется таблица cscart_template_snippets, содержащая следующие столбцы:

Название сниппета является языкозависимым и хранится в отдельной таблице 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'].

Схема формирования отображения сниппета¶

1. Определение типа сниппета из контекста. Каждый контекст, в котором вызывается сниппет, знает какие сниппеты для него доступны. Контекст на программном уровне представляет собой класс, реализующий интерфейс ITemplate.
2. Получение шаблона сниппета по типу и символьному идентификатору. Для этого используется класс \Tygh\Template\Snippet\Repository.
3. Вызов пре-хука 'template_snippet_render_pre'.
4. Вызов шаблонизатора для формирования отображения сниппета.
5. Вызов пост-хука 'template_snippet_render_post'.
6. Возврат результата.

Добавление сниппетов¶

Модули могут добавлять свои сниппеты любого типа. Предполагается, что добавление сниппетов будет происходить в момент установки модуля, а удаление — в момент удаления модуля. Для добавления можно воспользоваться методами класса \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” необходимо выводить таблицу, которую можно легко расширять. Очевидно, что делать это в визуальном редакторе документов не очень удобно. Для решения таких проблем были добавлены соответствующие хуки, которые позволяют влиять на формирование отображения сниппетов и расширять интерфейс на страницах редактирования сниппетов и документов.

Шаблонизатор¶

В качестве шаблонизатора используется библиотека 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 (время в понятном человеку формате).

  Начиная c CS-Cart 4.6.3, не обязательно указывать формат для даты. Если вы используете фильтр без формата, например, {{ o.raw.timestamp|date }}, то будет использован формат, выбранный на странице Настройки → Внешний вид.

  Вот форматы времени, которые можно выбрать в 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 Р.

  Начиная с CS-Cart 4.6.3, вы можете использовать этот фильтр, чтобы выбрать, в какой валюте отображать цену. Например, {{ o.raw.total|price("EUR") }} отобразит итог заказа в евро в соответствии с курсом, заданным в вашем магазине. Если для фильтра не указана валюта, то будет использоваться валюта, которая является CART_PRIMARY_CURRENCY.

• Фильтр 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 (детали заказа) в тело этих почтовых уведомлений.