Navigation¶

Main Page

Create Account

Search the wiki
»

Discuss (0) History

Email Template Files

RSS

Modified on 2009/06/04 19:37 by aarondh Categorized as Uncategorized

(6) » Specifying an Email Addresses » Daisley-Harrison.Net.EmailArgumentList » Email Template Files

Table of Contents [Hide/Show]

Loading Email Templates
Email Body Tags
   choose element
         Example
   if element
         Example
   for-each element
         Example
   format element
         Example
   linked-image element
         Example
   replace element
         Example
Email Template File Schema
Sample Email Template

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/>


    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;"/>

<em:linked-image source="product:ProductImage"  alt="Logo" style="border: none;"/>

<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.
- radsoftware has tutorial on regular expression syntax in their blog article Learn Regular Expression (Regex) syntax width C# and .NET
- For more detailed, and once again obtuse, documentation see .NET Framework Regular Expressions on MSDN.
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 &lt;webteam@bobsbigburgers.com&gt;</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>

_{Please visit our blog at http://blog.daisley-harrison.com}

Daisley-Harrison Software

Navigation¶

Email Template Files

Loading Email Templates¶

Email Body Tags¶

choose element¶

Example¶

if element¶

Example¶

for-each element¶

Example¶

format element¶

Example¶

linked-image element¶

Example¶

replace element¶

Example¶

Email Template File Schema¶

Sample Email Template¶