Development Core MailTemplate

The MailTemplate component provides mailing capabilities to Cloudrexx.

All mail handling in Cloudrexx should be done using MailTemplate.

Features

• Sending e-mails
• Management and usage of e-mail templates having features as:
  • Localisation support
  • Support for static attachments and dynamically generated PDF documents (by using PDF component)
  • Block and placeholder support
  • Multipart support (plaintext/html)

Usage

Sending e-mails

The simplest way of sending an email is by just calling \Cx\Core\MailTemplate\Controller\MailTemplate::send() as follows:

$options = [
    'to'      => 'info@example.org',
    'subject' => 'Hello World',
    'message' => 'This is a plaintext message',
];
\Cx\Core\MailTemplate\Controller\MailTemplate::send($options);

The full list of $options that can be passed to send() is as follows:

Key	Description
key	The key of any mail template to be used
section	The module to initialize for (mandatory when key is set)
sender	The sender name
from	The sender e-mail address
to	The recipient e-mail address(es), comma separated
reply	The reply-to e-mail address
cc	The carbon copy e-mail address(es), comma separated
bcc	The blind carbon copy e-mail address(es), comma separated
subject	The message subject
message	The plain text message body
message_html	The HTML message body
html	If this evaluates to true, turns on HTML mode
attachments	An array of file paths to attach. The array keys may be used for the paths, and the values for the name. If the keys are numeric, the values are regarded as paths.
inline	An array of inline (image) file paths to attach. If this is used, HTML mode (html) is switched on automatically.
search	The array of patterns to be replaced by...
replace	The array of replacements for the patterns
substitution	A more complex structure for replacing placeholders and/or complete blocks, conditionally or repeatedly.

If key has been set, it tries to load the e-mail template identified by key (see e-mail templates), otherwise a blank email is initialised. The generated mail will be sent to the recipients defined by to, cc and bcc. If case of successful e-mail dispatching (to the configured SMTP server), the method send() returns true, otherwise false.

E-Mail templates

E-mail templates provide the ability for custom tailored e-mail notifications that can be managed by a user over a GUI.

Management

Note: The default SystemComponentBackendController automatically ads a section for e-mail template management in the backend in case there are any templates by the viewing component present. So manual integration is therefore rarely required.

The management of e-mail templates can easily be integrated into a backend section as follows:

$htmlCode = \Cx\Core\MailTemplate\Controller\MailTemplate::overview(
    $this->getComponent()->getName(),
    'config'
)->get();

To integrate the management GUI directly into the view of the Setting configuration dialogue, do see separate section.

Sending

Sending an e-mail template is as easy as sending a non-template e-mail, with the exception that a key must be specified that does identify the e-mail template to be sent:

$options = [
    'key'     => 'order_confirmation',
    'section' => 'Shop',
];
\Cx\Core\MailTemplate\Controller\MailTemplate::send($options);

Any previously defined option by the e-mail template will be overwritten if it gets passed to send() as $options.

Placeholder support

A MailTemplate e-mail (both a template and non-template e-mail) does support template blocks and placeholders in the following form:

Placeholders (case insensitive):
[place_holder], [PLACEHOLDER] or [PLACEHOLDER2]

Conditional or repeated blocks:
[[BLOCK] ... [PLACEHOLDER] ... [BLOCK]]

Note: The format for placeholders and blocks differs from the common format used by the rest of Cloudrexx.

When sending an e-mail, the option substitution can then be used to pass the data that shall be used to parse the placeholders and blocks within an email. It is important to note, that not only the body (message) of an email does support placeholders and blocks, but all $options. Meaning that substitution will be applied to all set $options of an e-mail template.

Placeholders and blocks that are empty or not defined by substitution will be removed from the e-mail before it will be sent. If the latter is not intended, then instead of substitution, you could use search together with replace which will do a static search & replace on all $options of an e-mail template.

Examples

The following examples will use the following template:

[[MY_BLOCK] ... [MY_PLACEHOLDER] ... [MY_BLOCK]]

$options['substitution']	Output	Notes
[ 'my_block' => [ 0 => [ 'MY_PLACEHOLDER' => 'Hello World' ], ], ]	... Hello World ...	If my_block or my_placeholder is missing in substitution, then the whole block will not be parsed, but removed from the e-mail.
[ 'my_block' => [ 0 => [ 'MY_PLACEHOLDER' => 'One', ], 1 => [ 'MY_PLACEHOLDER' => 'Two', ], ], ]	... One ... ... Two ...

Important: The additional array level between block and placeholders (or other blocks) is necessary - even for blocks without repetition. Therefore the following is wrong and will not work:

$options['substitution'] = [
    'my_block' => [
        'MY_PLACEHOLDER' => 'Hello World'
    ],
];

SMTP Relay

MailTemplate will use the default SMTP server (as set in Administration > Basic Configuration > E-mail Server) for relying mail.

Note: When using a cx env environment the SMTP server can be set through the environment variable CLX_SMTP_MTA_HOST.