Сниппеты

Примечание

Данный функционал появился с версии 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 — предназначен для форматирования значения в виде даты.
  • Фильтр price — предназначен для форматирования значения в виде денежного типа.
  • Фильтр filesize — предназначен для форматирования значения в виде размера файла в килобайтах.
  • Фильтр puny_decode — предназначен для декодирования URL-адресов из PunyCode в интернациональное представление.
  • Функция __ — предназначена для вывода переводов.
  • Функция snippet — предназначена для подключения сниппетов.
  • Функция include_doc — предназначена для подключения документов в тело почтового уведомления.

Подсказка

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