iono Documentation - E-Mail Templates
iono uses text file based templates to send out all e-mails. Replacement variables are used to add in information appropriate to each customer or e-mail. The iono_mailer class located in includes/libraries/iono/iono_mailer.php is used to handle all the e-mail needs for iono. It extends PHPMailer, a well known, open source mail sending class.
The class is made available by default during iono initialisation and can be accessed from the object $iono_mailer. It will not be in scope in any functions by default so you will need to use the global keyword to make it available.
Messages
Predefined messages are found in the templates/iono/mailer/ directory and look something like this, from user_invoice_due.tpl.php:
Hi $customer[first_name], Invoice #$invoice[invoice_id] created on your account on $invoice[time_added] is now due. Please login at $global[system_url] to complete payment. -- Regards, $global[site_name] $global[site_url]
Each replacement variable is formatted like a normal PHP variable and is an array. This variable is replaced before the message is sent with the appropriate value.
Predefined Messages
The default predefined messages are as follows. They are located in the templates/iono/mailer/ directory.
- admin_invoice_approve.tpl.php - Sent to the administrator to inform them that there is a new invoice pending approval.
- user_activate.tpl.php - Requests the user activate their account
- user_extra_expired.tpl.php - A user's extra has expired
- user_extra_expiring.tpl.php - A user's extra will expire soon
- user_invoice_approved.tpl.php - Informs the user that their invoice/order has been approved. Approval is made either manually or after payment is processed successfully.
- user_invoice_created.tpl.php - Informs the user that a new invoice has been created on their account
- user_invoice_due.tpl.php - Informs the user that an invoice on their account is now due
- user_license_expired.tpl.php - A user's license has expired
- user_license_expiring.tpl.php - A user's license will expire soon
- user_reset.tpl.php - The user's account details after a reset
HTML is not supported in any e-mail template because it is often filtered, not displayed correctly or annoys the receipient.
Adding a new message
You can add your own predefined messages by calling the iono_mailer::add_message function from your code. This expects three parameters:
- name (string) - The name of the template. The file in the templates/iono/mailer/ directory must have the same name, minus the file extension of .tpl.php. E.g. user_activate.tpl.php would be user_activate.
- subject (string) - The subject of the e-mail once it is sent
- data (array) - An array of which data the template needs access to. Full set is array('customer', 'license', 'extra', 'invoice').
Sending
Sending a predefined message in an e-mail requires you to call the iono_mailer::send function. This function expects three parameters:
- to (mixed) - The e-mail address to send to as a string. To send to multiple, specify as an array e.g. array('example1@example.com', 'example2@example.com')
- message (string) - The name of the message template to send.
- data (array) Array containing the IDs for the customer, license, extra or invoice to get data for. These will be available depending upon the message text chosen
For example:
$iono_mailer->send('me@example.com', 'test', array('customer' => 1, 'license' => 1,
'extra' => 1, 'invoice' => 1));
Raw messages
To send a raw message that does not have a predefined template you will need to use the iono_mailer::send_raw function. This function expects three parameters:
- to (string) - The e-mail address to send to as a string.
- subject (string) - The subject of the e-mail once it is sent
- message (string) - The actual message body
Replacement Variables
When defining a new message, you define which data is available in the form of an array containing either customer, license</code, <code>extra or invoice. When the message is parsed, this will make available an array of data which can then be replaced in the template with real values. This data is retrieved based on the ID you provide when calling the iono_mailer::send function. For example, to get details for customer #1 and license #2 you would call it like so:
$iono_mailer->send('me@example.com', 'test', array('customer' => 1, 'license' => 2));
The available data for each of these is as follows:
Customer
Accessed in the form $customer[varname].
- user_id
- username
- first_name
- last_name
- company
- address1
- address2
- city
- county
- postalcode
- country
- phone
When the user_reset message is used, the variable password becomes available with the new password generated by the system.
Extra
Accessed in the form $extra[varname].
- extra_id
- product_id
- product_extra_id
- user_id
- status
- expires
- timestamp
- product_name
- product_extra_name
License
Accessed in the form $license[varname].
- license_id
- product_id
- product_license_id
- user_id
- status
- timestamp
- expires
- ip
- hostname
- product_name
- product_license_name
Invoice
Accessed in the form $invoice[varname].
- invoice_id
- time_added
- time_due
- status
- initial_discount
- initial_sub_total
- initial_tax
- initial_total
- recurring_discount
- recurring_sub_total
- recurring_tax
- recurring_total
- recurring_period
- subscription_active
Global
In addition, the following variables are available globally in every template and are accessed in the form $global[varname].
- site_name
- contact_email
- site_url
- system_url