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

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

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

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

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

• \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'].

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

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>

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

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

Любой шаблон почтового уведомления может содержать дополнительные параметры, которые впоследствии можно обработать в хуке 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.