Loading Email Templates
Email templates can be loaded into memory using the Load method of the static DaisleyHarrison.Net.Email.EmailTemplate object
For example:
using DaisleyHarrison.Net.Email;
...
EmailTemplate emailTemplate = EmailTemplate.Load( "templateFileName.xml" );
When loading email templates inside an ASP.NET application it is often more convenent to use the Server.MapPath method to resolve a relative path to your template file that is relative to the application path. For example:
using DaisleyHarrison.Net.Email;
...
EmailTemplate emailTemplate = EmailTemplate.Load( Server.MapPath("./templates/templateFileName.xml") );
Email Body Tags¶
Inside an
<em:body>...</em:body> element you can place any combination of text and any other valid xml. The current XML schema specifies, text, or xhtml, or any of the processing elements below. You can however use
any valid xml. The template processor is designed to preserve any non-recongized xml tag and pass it throught to the email message unchanged.
There are a few text processing XML elements that are recognized by the template processing engine to aid in the create of more complex emails. These processing elements are explained in the following sections.
Note: Processing tags can be nested to any depth.
choose element
The choose element is used to select between a number of optional content paths based on evaluating a set of conditional expressions.
- <em:choose> [ <em:when select="select-expression" [ cond="cond-expression" ] [ test="test-expression" ] > when-content </em:when> ] ... [ <em:otherwise> otherwise-content </em:otherwise> ] </em:choose>
Where:
- em:when - is zero or more "when" expression, processes in the same manner as the if element (See the If element for more details).
- select-expression - is any valid Template Expression (See the If element for more details).
- condition - is a condition operation to apply to the results of the evaluating the select-expression (See the If element for more details).
- test-value - a value used for conditions involving a binary comparison operation like "=" or "<=" (See the If element for more details).
- when-content - any text and/or xml content that will be processed only if the when expression evaluates as true
- em:otherwise - The otherwise element is optional, but at most one otherwise element can be used inside a choose element
- otherwise-content - any text and/or xml content that will be processed only if all when expressions evaluate as false
Example
<em:choose>
<em:when select='person:LastName' cond='!whitespace'>
[person:FirstName| ] [person:LastName]
</em:when>
<em:when select='person:FirstName' cond='!whitespace'>
[person:FirstName| ]
</em:when>
<em:otherwise>
An anonymous person
</em:otherwise>
</em:choose>
if element
Conditionally processes content based on the evaluate of a conditional expression.
- <if select="select-expression" [cond="condition"] [test="test-value"] >
Where:
- select-expression - is any valid Template Expression
- condition - is a condition operation to apply to the results of the evaluating the select-expression. (See below)
- test-value - a value used for conditions involving a binary comparison operation like "=" or "<=".
Supported cond operations are:
- cond="=" - if the expression result is equal to the test value (the default)
- cond="<" - if the expression result is < the test value
- cond=">" - if the expression result is > the test value
- cond="<=" - if the expression result is <= to the test value
- cond=">=" - if the expression result is >= to the test value
- cond="!=" - if the expression result is not equal to the test value
- cond="<>" - if the expression result is not equal to the test value
- cond="exists" - if the expression result does not exist
- cond="!exists" - if the expression result does not exist
- cond="whitespace" - if the expression result is all whitespace
- cond="!whitespace" - if the expression result is not all whitespace
- cond="regex" - if the expression result does matches the regular exrpession in the test value
- cond="!regex" - if the expression result does not match the regular exrpession in the test value
- cond="odd" - if the numeric result of the expression is odd
- cond="even" - if the numeric result of the expression is even
- cond="contains" - if the test value is contained in the expression result
- cond="!contains" -if the test value is not contained in the expression result
- cond="even"
Example
<em:if select="server:URL" cond="contains" test="fubar">
DON'T USE "fubar" IN THE URL!!!!
</if>
for-each element
The for-each element loops though a collection of items, applying the inner template content once for each item in the collection.
- <emfor-each select="select-expression" [ as="alias" ] > for-each-content </em:for-each>
Where:
- select-expression - is any valid Template Expression which results in a collection of items to iterate through.
- If the select-expression results in a null, the for-each-content with not be processed
- If the select-expressoin results in a single item that is not enumerable (ie. not a collection) then the for-each-content will be processed only once.
- alias - is the parameter name that will contain the item when the for-each-content is processed.
- If an alias is not specified then the parameter name "item" with the same namespace as the template library will be used to contain the current collection item.
- for-each-content - is the any text and/or xml markup or template expression that will be processed once for each item in the collection.
Example
Your favorite colors are:
<em:for-each select="person:FavoriteColors">
[em:item]
<em:for-each/>
or
Your favorite colors are:
<ul>
<em:for-each select="person:FavoriteColors" as="color" >
<li> [color] </li>
<em:for-each/>
<ul>
format element
The format element applies a string format expression to the results of a template expression.
- <em:format select="select-expression" pattern="string-format-expression"/>
Where:
- select-expression - is any valid Template Expression
- string-format-expression - is any valid string format expression.
- SteveX has a good compilation of string format expression in his blog article String Formatting in Csharp
- For the more detailed, but very obtuse, documentation see Microsoft's Formatting Overview on MSDN for more information on string format expressions.
Example
<em:format select="shopping-cart:TotalCost" pattern="{0:C}"/>
linked-image element
The linked-image element is the simplest way to embed an image in an html email. When an image url is specified using the linked-image element it automatically adds the image to the linked-resources collection for the email, assigns the linked resource an id, and create an html img tag.
- <em:linked-image source="image-expression" [ alt="alt-text" ] [ class="css-class" ] [ style="css-style" ] />
Where:
- image-expression - is any valid Template Expression that results in a valid URL to an image.
- alt-text - is the alt text for the image.
- although alt-text is optional it is recommend (and required for XHTML) that all img tags have an alt text attribute defined.
- css-class - is a cascading style sheet class name for the image (optional).
- css-style - is any valid css style sheet directives (optional).
- see the W3 School tutorial on cascading style sheets at CSS Tutorial
Example
<em:linked-image source="./images/logo.png" alt="Logo" style="border: none;"/>
or
<em:linked-image source="product:ProductImage" alt="Logo" style="border: none;"/>
or
<em:linked-image source="./images/logo.png" alt="Logo" class="cool"/>
replace element
The replaceelement applies a Regex style regular expression replace operation on the results of a template expression.
- <em:replace select="select-expression" pattern="regular-expression" replace="replace-expression"/>
Where:
- select-expression - is any valid Template Expression
- regular-expression - is any valid Regex style regular expression.
- replace-expression - is any valid Regex style replace regular expression.
- Also refer to the links indicated above for more details.
Example
<em:replace select="person:notes" pattern="blue" replace="green"/>
Email Template File Schema
The XML schema for the EmailTemplate XML document can be found at
http://daisley-harrison.com/namespaces/EmailTemplate/EmailTemplate.xsd
Sample Email Template
Here is a one of the sample email template files that can be found in the Email Library download:
<?xml version='1.0' encoding='utf-8'?>
<em:email-template xmlns:em='http://daisley-harrison.com/namespaces/EmailTemplate'>
<em:from>Bob's Big Burgers <webteam@bobsbigburgers.com></em:from>
<em:to>[settings:email-template3-to]</em:to>
<em:cc>bambam@bobsbigburgers.com, pebbles@bobsbigburgers</em:cc>
<em:bcc>bob@bobsbigburgers.com</em:bcc>
<em:subject>Way to go team!</em:subject>
<em:body>
[person:FirstName| ] [person:LastName| An anonymous user ] just purchased a bunch of stuff!
</em:body>
<em:alternate-views>
<em:alternate-view>
<em:linked-resources>
<em:linked-resource id='logo' url='./Images/Logo.jpg'/>
</em:linked-resources>
<em:body>
<html xmlns='http://www.w3.org/1999/xhtml'>
<body>
<div>
<a href='http://www.bobsbigburgers.com'>
<img src='cid:logo' alt='logo'/>
</a>
</div>
<h1>Bob's Big Burgers Did It Again</h1>
<p>
<strong>
<em:choose>
<em:when select='person:LastName' cond='!whitespace'>
[person:FirstName| ] [person:LastName]
</em:when>
<em:when select='person:FirstName' cond='!whitespace'>
[person:FirstName| ]
</em:when>
<em:otherwise>
An anonymous person
</em:otherwise>
</em:choose>
</strong> just purchased a bunch of stuff!
<em:if select='person:Email' cond='!whitespace'>
<p>
If you would like to give it that personal touch you can reach out to [person:FirstName|that unkown purchaser] at <a href='[person:FirstName]'>[person:Email]</a>
</p>
</em:if>
</p>
</body>
</html>
</em:body>
</em:alternate-view>
</em:alternate-views>
</em:email-template>