Почтовые уведомления

Примечание

Редактор почтовых уведомлений появился с версии 4.4.1.

В новой версии CS-Cart добавлена возможность редактирования шаблонов почтовых уведомлений в панели администратора. Для этого откройте страницу Дизайн → Шаблоны email-уведомлений и выберите шаблон того уведомления, которое нужно отредактировать.

Для удобства все почтовые уведомления разделены на две группы:

  • Уведомления для администратора;
  • Уведомления для покупателя.

В качестве шаблонизатора используется библиотека Twig. В шаблонах уведомлений можно использовать все возможности, предоставляемые этой библиотекой.

Примечание

Обратная совместимость сохранена: почтовые уведомления, основанные на файловых шаблонах, также будут работать.

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

Для хранения шаблонов почтовых уведомлений используется таблица cscart_template_emails. Таблица имеет следующую структуру:

Название Тип Описание
template_id int Автоинкрементный идентификатор шаблона
code varchar(128) Символьный идентификатор шаблона
area сhar(1) Рабочая зона шаблона
status char(1) Статус шаблона
subject text Шаблон темы сообщения
template text Шаблон тела сообщения
default_subject text Шаблон по умолчанию для темы сообщения
default_template text Шаблон по умолчанию для тела сообщения
params_schema text Схема дополнительных параметров шаблона
params text Данные дополнительных параметров шаблона
addon varchar(32) Идентификатор модуля-владельца шаблона
updated int UNIX timestamp обновления
created int UNIX timestamp создания

Программный интерфейс

Для управления и взаимодействия с шаблонами почтовых уведомлений реализованы следующие классы:

  • \Tygh\Template\Mail\Template — модель шаблона. Является программным представлением структуры шаблона в БД.
  • \Tygh\Template\Mail\Repository — репозиторий шаблонов, класс реализует низкоуровневые методы получения/добавления/обновления/удаления шаблонов в БД. Экземпляр класса доступен из контейнера Tygh::$app['template.mail.repository'].
  • \Tygh\Template\Mail\Service — класс-сервис, реализует более высокоуровневые методы управления шаблонами. Экземпляр класса доступен из контейнера Tygh::$app['template.mail.service'].
  • \Tygh\Template\Mail\Exim — класс реализует логику экспорта и импорта почтовых шаблонов. Экземпляр класса доступен из контейнера Tygh::$app['template.mail.exim'].

Схема отправки почтовых уведомлений

New banner
  1. Формирование данных для уведомления.

    Этот этап не претерпел никаких значительных изменений. Так же как и раньше необходимо собрать все данные, которые будут доступны при формировании тела сообщения.

  2. Вызов подсистемы отправителя.

    Статический класс \Tygh\Mailer заменен на класс-сервис \Tygh\Mailer\Mailer, который доступен из контейнера Tygh::$app['mailer'].

    При вызове метода для отправки сообщения необходимо в ключе template_code указать символьный идентификатор шаблона почтового уведомления. Пример:

    $mailer->send(array(
        'to' => 'company_orders_department',
        'from' => 'default_company_orders_department',
        'data' => array(...)
        /* указание идентификатора почтового шаблона. */
        'template_code' => 'call_requests_call_request',
        'tpl' => 'addons/call_requests/call_request.tpl',
        'company_id' => $company_id,
    ), 'A', $lang_code);
    
  3. Определение типа почтового события.

    Перед отправкой сообщения сервис \Tygh\Mailer\Mailer определяет, каким образом должно быть сформировано тело сообщения. На данный момент есть 3 способа это сделать:

    • Использовать шаблон из файла.
    • Передать шаблон в параметрах.
    • Использовать шаблон из БД.
  4. Получение шаблона сообщения по идентификатору сообщения с помощью класса \Tygh\Template\Mail\Repository.

  5. Формирование контекста и переменных сообщения.

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

  6. Вызов шаблонизатора для формирования отображения тела сообщения.

  7. Конвертация CSS стилей в inline.

  8. Вызов низкоуровневого метода отправки сообщения.

    На этом этапе сформированные данные передаются в библиотеку PHPMailer, которая и занимается непосредственно отправкой сообщения.

Добавление шаблона почтового уведомления

Для добавления шаблона почтового уведомления необходимо воспользоваться классом-сервисом \Tygh\Template\Mail\Service.

Пример:

/** @var \Tygh\Template\Mail\Service $service */
$service = Tygh::$app['template.mail.service'];

$service->createTemplate(array(
    'code' => 'new_notification',
    'area' => 'C',
    'status' => 'A',
    'default_subject' => '{{ __("new_notification_subject") }}',
    'default_template' => '{{ snippet("header") }} <br/> Dear {{ customer_name }}! <br/> ... <br/> {{ snippet("footer") }}',
    'addon' => 'my_changes',
));

Для упрощения добавления шаблонов почтовых уведомлений, реализована возможность декларативного описания шаблонов, которые можно описать в файле схемы модуля. В таком случае шаблоны сами будут добавлены при установке модуля. Пример:

<?xml version="1.0"?>
<addon scheme="3.0">
    <id>my_changes</id>
    <email_templates>
        <templates>
            <item>
                <code><![CDATA[my_changes_notification]]></code>
                <area><![CDATA[C]]></area>
                <status><![CDATA[A]]></status>
                <default_subject><![CDATA[{{ subject }}]]></default_subject>
                <default_template><![CDATA[{{ snippet("header") }}


            {{ snippet("my_changes.snippet”) }}


            {{ snippet("footer") }}]]></default_template>
                <addon><![CDATA[my_changes]]></addon>
            </item>
        </templates>
        <snippets>
            <item>
                <code><![CDATA[[my_changes.snippet]]></code>
                <default_template>Content</default_template>
                <status><![CDATA[A]]></status>
                <name>
                    <en><![CDATA[my_changes: snippet]]></en>
                </name>
                <addon><![CDATA[my_changes]]></addon>
            </item>
        </snippets>
    </email_templates>
</addon>

Расширение почтовых уведомлений

PHP-хуки

  • 'template_email_get_name' — вызывается после формирования названия шаблона почтового уведомления, с помощью хука можно изменить название:

    fn_set_hook('template_email_get_name', $this, $name)
    
  • 'mailer_send_pre' — вызывается перед отправкой сообщения; через этот хук есть возможность повлиять на содержимое сообщения:

    fn_set_hook('mailer_send_pre', $this, $transport, $message, $area, $lang_code)
    
  • 'mailer_send_post' — вызывается после отправки сообщения:

    fn_set_hook('mailer_send_post', $this, $transport, $message, $result, $area, $lang_code)
    

Дополнительные параметры шаблона

Любой шаблон почтового уведомления может содержать дополнительные параметры, которые впоследствии можно обработать в хуке mailer_send_pre. Схема дополнительных параметров хранится в поле params_schema и представляет из себя следующую структуру:

array(
     "var_name" => array(
         "type" => "checkbox",
         "title" => "param_title",
         "description" => "param_description"
     ),
     "var_name1" => array(
         "type" => "checkboxes",
         "title" => "param_title",
         "description" => "param_description",
         "variants" => array(
             "variant_key" => "variant_name"
        )
     ),
     "var_name2" => array(
         "type" => "checkboxes",
         "title" => "param_title",
         "description" => "param_description",
         "func" => "fn_get_params_variants"
     ),
)

Где:

  • "var_name" — имя переменной, по которому будет сохраняться значение;
  • "type" — тип переменной; доступные типы: checkbox, checkboxes, textarea, input, selectbox;
  • "title" — название языковой переменной, которая будет использована в качестве названия для поля.
  • "description" — название языковой переменной, которая будет использована в качестве подсказки для поля.
  • "variants" — массив вариантов для параметра типа checkboxes.
  • "func" — функция для формирования массива вариантов для параметра типа checkboxes.

Сохраненные значения будут доступны в свойстве модели шаблона почтового уведомления.

С помощью дополнительных параметров реализована возможность прикрепления “order”-документа к почтовым уведомлениям о смене статуса заказа. На странице редактирования шаблона выведен выпадающий список из доступных документов типа “order”, в пре-хуке mailer_send_pre обрабатывается значение этого поля.

В случае, если документ выбран, то к почтовому сообщению прикрепляется PDF-файл, сгенерированный на основе указанного документа. Схема переменных в этом случае выглядит следующим образом:

array(    "attach_order_document": array(
          "type": "selectbox",
          "title": "email_template.params.attach_order_document",
          "func": "fn_emails_get_order_document_variants"
     )
)

Функция fn_emails_get_order_document_variants описана в схеме emails/variants.functions.