Core Mail and Template Class
Manages e-mail templates in any language, accessible by module and key for easy access. Includes a nice wrapper for the phpmailer class that allows sending all kinds of mail in plain text or HTML, also with attachments.
version | 3.0.0 |
---|---|
since | 2.2.0 |
package | contrexx |
subpackage | core |
copyright | CONTREXX CMS - COMVATION AG |
author | Reto Kohli |
todo | Test! |
adminView($section, $group)
available(string $key, integer $lang_id) : boolean
Mind that {@see init()} should have been called before, setting up the data in all languages you're about to test. Returns false on failure.
string
The MailTemplate key
integer
The language ID
boolean
True if the key is available in that
language, false otherwiseclearEmptyPlaceholders(string $value)
string
The string, by reference
deleteTemplate($section, string $key) : boolean
Protected (system) templates can not be deleted. Deletes all languages available. if the $key argument is left out, looks for a key in the delete_mailtemplate_key index of the $_REQUEST array.
string
The optional template key
boolean
True on success, false otherwiseedit(mixed $section, string $key, $useDefaultActs) : \Cx\Core\Html\Sigma
Stores the MailTemplate if the 'bsubmit' parameter has been posted. If the $key argument is empty, tries to pick the value from $_REQUEST['key'].
mixed
The section of the mail template to be edited
string
The optional key of the mail template to be edited
\Cx\Core\Html\Sigma
The template objecterrorHandler() : boolean
boolean
False. Always.get(integer $section, string $key, integer $lang_id) : mixed
The $key parameter uniquely identifies the template for each module. The optional $lang_id may be provided to override the language ID present in the global FRONTEND_LANG_ID constant.
global | ADONewConnection |
---|---|
static | |
author | Reto Kohli |
integer
The optional module ID
string
The key identifying the template
integer
The optional language ID
mixed
The mail template array on success,
null otherwisegetArray(integer $section, integer $lang_id, string $order, integer $position, integer $limit, integer $count) : mixed
If the optional $lang_id argument is empty, the current language ID, or the global FRONTEND_LANG_ID constant is used instead, in this order.
integer
The section
integer
The optional language ID
string
The optional sorting order string, SQL syntax
integer
The optional position offset, defaults to zero
integer
The optional limit for returned templates. Defaults to -1 (no limit)
integer
The actual count of templates available in total, by reference
mixed
The template array on success,
null otherwisegetEmpty(string $key) : array
Note that this is NOT a constructor, but a static method that returns an empty template array with all fields empty, with the exception of the optional $key.
string
The optional key
array
The MailTemplate arrayinit(integer $section, integer $lang_id, string $order, integer $position, integer $limit, integer $count) : boolean
Uses the given language ID $lang_id if not empty, or all active frontend languages otherwise. The $limit value defaults to the value of the mailtemplate_per_page_backend setting from the core settings (@see SettingDb}.
integer
The section
integer
The optional language ID
string
The optional sorting order string, SQL syntax
integer
The optional position offset, defaults to zero
integer
The optional limit for returned templates
integer
The actual count of templates available in total, by reference
boolean
True on success, false otherwiseoverview(string $section, string $group, integer $limit, $useDefaultActs) : \Cx\Core\Html\Sigma
If empty, the $limit defaults to the "numof_mailtemplate_per_page_backend" setting for the given section and group.
string
The section
string
The group
integer
The optional limit for the number of templates to be shown
\Cx\Core\Html\Sigma
The template objectsend(array $arrField) : boolean
The array argument is searched for the following indices: 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. If the key index is present, the corresponding mail template is loaded first. Other indices present (sender, from, to, subject, message, etc.) will override the template fields. Missing mandatory fields are filled with the default values from the global $_CONFIG array (sender, from, to), or some core language variables (subject, message). A simple {@see str_replace()} is used for the search and replace operation, and the placeholder names are quoted in the substitution, so you cannot use regular expressions. More complex substitutions including repeated blocks may be specified in the substitution subarray of the $arrField parameter value. The e-mail addresses in the To: field will be used as follows: - Groups of addresses are separated by semicola (;) - Single addresses are separated by comma (,) All recipients of any single group are added to the To: field together, Groups are processed separately. So, if your To: looks like a@a.com,b@b.com;c@c.com,d@d.com a total of two e-mails will be sent; one to a and b, and a second one to c and d. Addresses for copies (Cc:) and blind copies (Bcc:) are added to all e-mails sent, so if your e-mail is in the Cc: or Bcc: field in the example above, you will receive two copies. Note: The attachment paths must comply with the requirements for file paths as defined in the {@see File} class version 2.2.0.
static | |
---|---|
author | Reto Kohli |
array
The array of template fields
boolean
True if the mail could be sent,
false otherwisestore(string $section, array $arrField) : boolean
Stores the template for the given section Uses the language ID from the lang_id index, if present, or the FRONTEND_LANG_ID constant otherwise. key The key of any mail template to be used lang_id The language ID 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. The key index is mandatory. If available, the corresponding mail template is loaded, and updated. Missing fields are filled with default values, which are generally empty. The protected flag can neither be set nor cleared by calling this method, but is always kept as-is. Note: The attachment paths must comply with the requirements for file paths as defined in the {@see File} class version 2.2.0.
string
The section
array
The field array
boolean
True on success, false otherwisestoreFromPost(string $section) : boolean
Sets appropriate messages.
string
The section
boolean
True on success, null if nothing
needs storing, false otherwisesubstitute(string $string, array $substitution)
Each array key in $substitution is regarded as a placeholder name. Each name is enclosed in square brackets ("[", "]") to form the full placeholder. If its value is an array, it represents a repeatable block with contents in an (indexed) array, otherwise it's a simple replacement.
Your template $string might look something like
A single [PLACEHOLDER] is substituted here once.
[[BLOCK]This line is repeated for each [ITEM] in the block.[BLOCK]] If there is no [ITEM] in the BLOCK subarray, the block is never parsed and thus removed.
The $substitution array looks like array( 'PLACEHOLDER' => 'Scalar replacement value', 'BLOCK' => array( index => array( 'ITEM' => 'Another scalar value', 'MORE_PLACEHOLDERS_OR_BLOCKS' => 'Nest as deep as memory allows', ... more ... ), ... more ... ), ... more ... )
Of course, all names used above are just examples, any block or placeholder name may be an arbitrary word consisting of letters and underscores.
Any block may occur more than once. Its contents are repeated. Each block name MUST occur an even number of times in the string.
Mind that the names in the substitution array SHOULD be unique, or the order of the elements becomes relevant and the results may not be what you expect! The array is processed depth-first, so every time a block array is encountered, it is completely substituted recursively before the next value is even looked at.
Final note: To replace any blocks or placeholders from the string that have not been substituted, call {@see clearEmptyPlaceholders()} after all values have been substituted. This will take care both of unused blocks and placeholders. See {@see send()} for an example.
string
The string to be searched and replaced, by reference
array
The array of placeholders and values, by reference
$arrTemplates : array
$empty : array
$section : integer
$text
TEXT_ATTACHMENTS
TEXT_BCC
TEXT_CC
TEXT_FROM
TEXT_INLINE
TEXT_MESSAGE
TEXT_MESSAGE_HTML
TEXT_NAME
TEXT_REPLY
TEXT_SENDER
TEXT_SUBJECT
TEXT_TO