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" has been set, it tries to load the template 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           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!