Development Core MailTemplate

Description

The MailTemplate class contains (mostly static) methods and constants for the management of mail templates, the replacement of placeholders and the send process of mails. The intention is to everytime use this gateway in Contrexx to send Mails.

Documentation

Contrexx API \MailTemplate class

Methods

• static function init($section, $lang_id=null, $order=, $position=0, $limit=-1, &$count=0)
  • Used by almost all methods to reinitialize the class, especially the module
• static function overview($section, $group, $limit=0)
  • Overview of all (or a special amount $limit, under consideration of the paging offset) MailTemplates for the given module and the internal groups.
  • Returns a Sigma template
• static function edit($section, $key=)
  • MailTemplate for the given module and the key to edit
  • Returns a Sigma template
  • Integration example (in combination with SettingDb)

    [...]
    if (   isset($_REQUEST['act'])
        && $_REQUEST['act'] == 'mailtemplate_edit') {
        $result &= SettingDb::show_external(
            self::$objTemplate,
            $_CORELANG['TXT_CORE_MAILTEMPLATE_EDIT'],
            MailTemplate::edit()->get()
        );
    } else {
        SettingDb::init('backend');
        $result &= SettingDb::show_external(
            self::$objTemplate,
            $_CORELANG['TXT_CORE_MAILTEMPLATES'],
            MailTemplate::overview(
                SettingDb::getValue('mailtemplate_per_page_backend')
            )->get()
        );
    }
    [...]

• static function send($arrField)
  • If a key (see $arrField below) has been set, it tries to load the template identified by key, otherwise it uses an empty template
  • Afterwards the default values will be overwritten by the field inputs
  • #Replacements (search/replace) and substitutions will be done, if any. All replacements will be completely done on each field of the template (except the fields with the replacement parameters).
  • The parsed mail will be sent to the recipients in the fields To:, Cc: and Bcc:
  • Returns true if the mail has been successfully sent, otherwise false
  • $arrField can (almost) take arbitrary combination of the following keys:

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

Replacements (search/replace)

• All values in the array under index search will be replaced with str_replace() with the String from the array under index replace.

Substitution

• The structure of the array in substitution will have an effect on the blocks and placeholders in the content of the template.
• Syntax:
  • Placeholders (scalar):
    • [place_holder],
    • [PLACEHOLDER] or
    • [PLACEHOLDER2]
    • The replacement is case insensitive!
  • Conditional or repeated blocks:
    • [[BLOCK] ... [PLACEHOLDER] ... [BLOCK]]

Examples

Substitution of a block:

    [[BLOCK] ... [PLACEHOLDER] ... [BLOCK]]

conditional with:

    array(
      'block' => array( 
        0 => array(
          'PLACEHOLDER' => "Hello World"
        ),
      ),
    );

results in

    ... Hello World ...

Without block or placeholder in the substitution, the whole block won't be parsed.

repetitive with:

    array(
      'block' => array( 
        0 => array(
          'PLACEHOLDER' => "One"
        ),
        1 => array(
          'PLACEHOLDER' => "Two"
        ),
      ),
    );

results in

    ... One ...
    ... Two ...

WRONG:

    array(
      'block' => array( 
        'PLACEHOLDER' => "Hello World"
      ),
    );

The additional array level between block and placeholders (or other blocks) is necessary!