Email Notifications¶

Data Structure¶

The cscart_template_emails table is used to keep email notification templates. The table has the following structure:

Programming Interface¶

The following classes were implemented to manage email templates:

• \Tygh\Template\Mail\Template—the template model. It’s a programming representation of the template structure in the database.
• \Tygh\Template\Mail\Repository—the template repository. This class implements low-level methods of receiving/adding/updating/deleting templates from the database. An instance of the class is available from the Tygh::$app['template.mail.repository'] container.
• \Tygh\Template\Mail\Service—the service class that implements higher-level methods of template management. An instance of the class is available from the Tygh::$app['template.mail.service'] container.
• \Tygh\Template\Mail\Exim—the class that implements the logic of importing and exporting email templates. An instance of the class is available from the Tygh::$app['template.mail.exim'] container.

The Schema of Sending Email Notifications¶

1. Forming data for a notification.

   This step hasn’t changed much. The data must be gathered to form the body of the message.

2. Calling the sender subsystem.

   The \Tygh\Mailer static class was replaced by the \Tygh\Mailer\Mailer service class that is available from the Tygh::$app['mailer'] container.

   When calling a message sending method, specify the character identifier of the email template in the template_code key. For example:

   $mailer->send(array(
       'to' => 'company_orders_department',
       'from' => 'default_company_orders_department',
       'data' => array(...)
       /* indicating email template id. */
       'template_code' => 'call_requests_call_request',
       'tpl' => 'addons/call_requests/call_request.tpl',
       'company_id' => $company_id,
   ), 'A', $lang_code);
   

3. Defining the type of the email event.

   Before sending the message, the \Tygh\Mailer\Mailer service defines how the body of the message is formed. Currently there are 3 ways to do this:

   • By using the template from the file.
   • By passing the template in the parameters.
   • By using the template from the database.

4. Receiving the message template by the message ID with the \Tygh\Template\Mail\Repository class.

5. Forming the context and variables of the message.

   Based on the data received in step 1, we form the context and available variables of the email notification. Unlike the documents, the context and variables in the notifications are not separated. This preserves backward compatibility.

6. Calling the template engine to render the message body.

7. Converting CSS styles into inline.

8. Calling the low-level method of the message sending.

   On this step the formed data are sent to the PHPMailer library that handles sending messages.

Adding the Email Notification Template¶

To add the email notification template, use the \Tygh\Template\Mail\Service service class.

For example:

/** @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',
));

To make adding email notification templates easier, we implemented declarative description of templates in the add-on schema. In that case the templates will be added automatically when the add-on is installed. For example:

<?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>

Extending Email Notifications¶

Additional Template Parameters¶

Any email notification template may contain additional parameters that can be processed later in the mailer_send_pre hook. The schema of additional parameters is stored in the params_schema field and has the following structure:

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"
     ),
)

Where:

• "var_name"—the name of the variable that is used to save the value.
• "type"—the type of the variable; the available types are: checkbox, checkboxes, textarea, input, selectbox.
• "title"—the name of the language variable that will be used as the name of the field.
• "description"—the name of the language variable that will be used as a hint for the field.
• "variants"—array of variants for a parameter with the checkboxes type.
• "func"—the function that forms the array of variants for a parameter with the checkboxes type.

The saved values will be available in the property of the model of the notification template.

Additional parameters allow you to attach the order document to email notifications about order status changes. The dropdown list that determines, which document must be attached, appears on the template editing page. The value of this list is handled in the mailer_send_pre pre-hook.

The selected document will generate a PDF file that will be attached to the message. In this case the schema of variables looks this way:

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

Function fn_emails_get_order_document_variants is described in the emails/variants.functions schema.