Почтовые уведомления¶
Примечание
Редактор почтовых уведомлений появился с версии 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']
.
Схема отправки почтовых уведомлений¶
Формирование данных для уведомления.
Этот этап не претерпел никаких значительных изменений. Так же как и раньше необходимо собрать все данные, которые будут доступны при формировании тела сообщения.
Вызов подсистемы отправителя.
Статический класс
\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);
Определение типа почтового события.
Перед отправкой сообщения сервис
\Tygh\Mailer\Mailer
определяет, каким образом должно быть сформировано тело сообщения. На данный момент есть 3 способа это сделать:- Использовать шаблон из файла.
- Передать шаблон в параметрах.
- Использовать шаблон из БД.
Получение шаблона сообщения по идентификатору сообщения с помощью класса
\Tygh\Template\Mail\Repository
.Формирование контекста и переменных сообщения.
На основе данных, полученных в пункте 1, формируем контекст и доступные переменные почтового уведомления. В отличие от документов, контекст и переменные в почтовых уведомлениях не разделены. Это сделано для сохранения обратной совместимости.
Вызов шаблонизатора для формирования отображения тела сообщения.
Конвертация CSS стилей в inline.
Вызов низкоуровневого метода отправки сообщения.
На этом этапе сформированные данные передаются в библиотеку 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.