Сниппеты

Примечание

Данный функционал появился с версии 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'].

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

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

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 (время в понятном человеку формате).

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

Подсказка

Более подробную информацию о шаблонизаторе вы можете узнать из официальной документации: http://twig.sensiolabs.org/