Customisation - E-mail - Format

From Zen Cart(tm) Wiki
Revision as of 22:02, 17 November 2006 by Blindside (talk | contribs) (Reverted edits by Torke (Talk); changed back to last version by Allcanadiansearch.ca)
Jump to: navigation, search

Overview

There are several places in the Zen Cart™ code where e-mails to the customer are constructed. To create a consistent feel for all your communication with the customer, you will want to make sure you modify all these places whenever you modify one. Don't forget to use the template overrides system wherever possible when making your changes.


The e-mail's structure is determined in one of two ways: if you are sending plain text e-mails, it is determined by the way you put together the various items (customer greeting, order number, link to detailed invoice, etc) in a string variable that is then passed to the zen_mail() function. If you are sending HTML e-mails, the structure is determined by the template you use.


Plain text e-mails

You can rearrange, add, or delete items in a plain text e-mail. To do so, you will need to edit the Zen Cart™ files where the e-mail is created. For example, if you want to edit the order confirmation e-mail, you will need to edit the file includes/classes/order.php.

In our example, we open up includes/classes/order.php and scroll down to the bottom of the file, in the function send_order_email(). There you will see the lines that construct the plain text e-mail message:

(line 827)        $email_order = EMAIL_TEXT_HEADER . EMAIL_TEXT_FROM . STORE_NAME . "\n\n" .
                       $this->customer['firstname'] . ' ' . $this->customer['lastname'] . "\n\n" .
                       EMAIL_THANKS_FOR_SHOPPING . "\n" . EMAIL_DETAILS_FOLLOW . "\n" .
                       EMAIL_SEPARATOR . "\n" .
                       EMAIL_TEXT_ORDER_NUMBER . ' ' . $zf_insert_id . "\n" .
                       EMAIL_TEXT_DATE_ORDERED . ' ' . strftime(DATE_FORMAT_LONG) . "\n" .
                       EMAIL_TEXT_INVOICE_URL . ' ' . zen_href_link(FILENAME_ACCOUNT_HISTORY_INFO, 'order_id=' . $zf_insert_id, 'SSL', false) . "\n\n";
(line 848)          $email_order .= zen_db_output($this->info['comments']) . "\n\n";
(line 855)        $email_order .= EMAIL_TEXT_PRODUCTS . "\n" .
                        EMAIL_SEPARATOR . "\n" .
                        $this->products_ordered .
                        EMAIL_SEPARATOR . "\n";

and so on. In this file, the variable that holds the plain text e-mail message is called $email_order; it generally has a different name in each file, such as $email or $email_text. Whatever its name, this is the place where you will make your changes. You can add, delete, and rearrange the order of the items to suit your wishes.

If you don't understand what's going on in the lines above, you may want to Read more about PHP first.


HTML e-mails

The HTML e-mail templates are located in the folder email/ in your store's root directory. There are several different templates, each for a different purpose. You can rearrange the items, add new items, or delete items to achieve the structure you want for your e-mails.


You need not edit any other Zen Cart™ files if you just want to rearrange or delete the items listed in an HTML template. To add items, however, you will need to find all the Zen Cart™ files that use that particular HTML template, and add in a definition for your new item. You can use the Developer's Tool Kit in the Admin to find all the files that use a given template; search for the last part of the template name. For example, if you want to add an item into the HTML template email_template_order_status.html, search for 'order_status' using the Developer's Tool Kit (include the apostrophes to help narrow your search).


Once you have found the files that need to be edited, you will want to add a definition for your new HTML item to each one. For example, suppose you have added an item called $EMAIL_HOURS_OF_OPERATION to the email_template_order_status.html template. One of the files that you will need to edit is admin/orders.php. Find the part of that file where the e-mail message is being constructed; in this case, it begins around line 100.


You see that the HTML message is constructed with several statements like this:

      $html_msg['EMAIL_CUSTOMERS_NAME'] = $check_status->fields['customers_name'];
      $html_msg['EMAIL_TEXT_ORDER_NUMBER'] = EMAIL_TEXT_ORDER_NUMBER . ' ' . $oID;

All you need to do is add a new statement under all these to define your new item:

      $html_msg['EMAIL_HOURS_OF_OPERATION'] = 'We are open from 9 AM to 5 PM every day of the week.';


(Of course, it's a better idea to use a constant instead of hardcoding your text like this, but we'll do it like this in our example for clarity's sake. See the section on changing e-mail text values for more information.)


Idea.png Notice the $
Use a $ in front of the name of your new item in the HTML template, but do not use the $ where you define it.


Finding files where e-mails are created

Here is a list to help you find the files you will need to edit to modify the structure of your e-mails.

Type of e-mail HTML template in folder email/ Search for this in Developer's Tool Kit
Contact us email_template_contact_us.html 'contact_us'
Coupon email_template_coupon.html 'coupon'
Default email_template_default.html 'default'
Direct e-mail email_template_direct_email.html 'direct_email'
Gift certificates email_template_gv_mail.html
email_template_gv_send.html
email_template_gv_queue.html
'gv_mail'
'gv_send'
'gv_queue'
Low stock email_template_low_stock.html 'low_stock'
Newsletters email_template_newsletters.html 'newsletters'
Order confirmation email_template_checkout.html 'checkout'
Order status update email_template_order_status.html 'order_status'
Password forgotten email_template_password_forgotten.html 'password_forgotten'
Product notification email_template_product_notification.html 'product_notification'
Tell a friend email_template_tell_a_friend.html 'tell_a_friend'
Welcome email_template_welcome.html 'welcome'


Idea.png 3rd party contributions
Don't forget to modify files for any contributions (add-ons, modules) you've added to your store that send out e-mails.