Email Templates

Email Templates are used as the container for which email content is sent.  Every email is sent using a template even if the template is a basic template.  This article discuss how email templates are generated.  Of course we are always available to generate a template per your specification, please reach out to us so we can get a proposal together for you.

Background

Email templates are php files that ultimately generate html output.  This html output, and, a plain text equivelant become the substance of your email.  Our template processing engine allows you to specify variables that are substituted with actual content at the time the email is sent.  This content can come from data you provide, or, system generated data.  All variables start with a $, ex: $message.

Email templates are accessible only through the file manager and are stored in [root]\packages\ravid_crm\mail.  Note that:

• any php file in this directory can be used as a template
• files that we distribute will overwrite any file in this directory
• if you want to modify an existing template, copy it, give it a unique name, then it will not be overwritten.  Name it something that we wouldn't like use.

Template Format

Templates are PHP files.  The general template should look something like this:

• It's  a php file and you should follow all standard php conventions
• Use t("content") for strings that need to be translated and all standard conventions.  For example,

t("Dear %s<br>I hope you're having a great day today.<br><br>Sincerely,<br>%s",$userInfo['name_first'],$siteSenderSignature);

is valid and a great way to display content.

Variable Format

The general format is:  $[variable name]||"[null string]".   Let me explain the parts:

• [variable name] this is the name of the variable.  Sometimes you will have something here and nothing else.
•  
• || is super secret coding language meaning "or" or also is sometimes referred to as the pipe symbol.  The text string, between quotes, following the pipe symbol is the text that will be used is the variable name can not be found or is empty.

Here's a few examples:

• $userInfo:name_first - provides the first name from the userInfo system object
• $contact:birthday - provides the birth attribute from the contact system object
• $userInfo:name_first||"Friend" uses the first name of the userInfo object if it has a value, otherwise, it will use the word Friend. So let's say your templates starts with: Dear $userInfo:name_first||"Friend", - when the email is sent, assuming it's being sent to Steve, it will say Dear Steve,.  If however Steve has an email address but no first name in the system, the email will say Dear Friend,.  

For example, $userInfo:name_first||"" is a valid variable

System Variables

The following variables exist in the system and can be used in your templates:

• $userInfo['name_first']
• $userInfo['name_last']
• $userInfo['company']
• $userInfo['phone']
• $userInfo['address']
• $userInfo['[attribute handle'] where [attribute handle] is the handle of any attribute handle assigned to the user/members object
• $contact['[attribute handle]'] where [attribute handle] is the handle of any attribute you added to the contact express object
• $siteLogo
• $siteLogoLink
• $sender['[attribute handle'] where [attribute handle] is the handle of any attribute handle assigned to the user/members object.  This is the sender/author of the email.  
  • name_first, name_last, email_signature, phone are attributes which you may want to use in your templates.

Variables needing user input

Some variables can be used in templates which require the user to provide information.  this information is usually provided at the time the email or marketing campaign is initiated.  These variables follow a similar format to system variables but the template also must include a definition about how to collect the user info.  This is in comment blocks at the top of the email.  Consider this template:

There's a lot going on here.  Let's walk through it:

• /* [comment] */ these symbols denote the start and end of a comment block.  The comment block is everything in between the symbols.
• /* @title General Emails */ is the title of the template.  The title is everything after the @title and before the */
• @description is the description of the template, this should indicate how and where the template is used
• @var indicates that this comment block is going to tell you about a variable used in teh template for which we need user input.  The format of this comment is specific and is as follows:  @var [type] [variable name]
  • @var - is required and can't change
  • [type] - indicates the type of input.
  • [variable name] is the name of the variable including the dollars sign
• [type] can be any of the following
  • string - a single line text value
  • text - same as string
  • textarea - multi-line text
  • richtextarea - multi-line formatted text
  • filemanager or filemanager\file - requires selection of a file which will be attached to the email.
  • filemanager\[file type] requires selection of a file, which will be restricted to the suggested file type, and the url will be returned as opposed to the file being attached to the email.  Useful when, for example, you want to include an image or video in your email.  The following file type values are supported:
    • image
    • video
    • text
    • audio
    • document
    • application

Syntax Check your templates

It's always a good idea to syntax-check your templates before putting them into production.  You can do this from the command line using the following command:

php -l <template file name> 

For example, php -l general_email.php will test the file and display any syntax errors