Выделенные фргаменты кода (Сниппеты)¶

Типы выделенных фрагментов кода (сниппетов)¶

Все выделенные фрагменты кода (сниппеты) в системе разделены на типы. Это разделение позволяет разграничить доступ к выделенным фрагментам кода (сниппетам) из разных типов документов. Например, выделенные фрагменты кода (сниппеты) типа 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 в интернациональное представление. Этот фильтр можно найти в шаблонах уведомлений по электронной почте, которые содержат URL, например, в письмах о смене пароля: {{ url|puny_decode }}.

• Функция __ — предназначена для вывода переводов. Например, вместо кода {{__("change_order_status_c_text")}} в русской версии документа появится соответствующее значение языковой переменной: Ваш заказ был выполнен. Спасибо, что выбрали нас.

• Функция snippet — предназначена для подключения выделенных фрагментов кода (сниппетов). Например, код {{ snippet("ship_to") }} в документе Счет добавляет в документ соответствующий выделенный фрагмент кода (сниппет) со вкладки выделенных фрагментов кода Сниппеты.

• Функция include_doc — предназначена для подключения документов в тело почтового уведомления. Например, в уведомлениях по электронной почте о статусах заказов есть следующая строка: {{ include_doc("order.summary", order_info.order_id) }}.

  Это строка добавляет документ order.summary (детали заказа) в тело этих почтовых уведомлений.