Email template expression use a wiki style expression syntax. The generic expression syntax is as follows:
“
[”
namespace-uri “
:“
expression-text [ “
|”
parameter0 ] [ “
|”
parameter1 ] [ … “
|”
parameterN ]] “
]”
Where:
namespace-uri is any of the built in expression namespaces or any user defined namespace.
expression-text is the text of the expression, the meaning of which is defined by the expression namespace.
parameter0,
parameter1,…
parameterN are optional parameters used to aid the evaluation of the expression.
By default if a expression cannot be evaluated, either because of a syntax error in the expression, or the expression could not be resolve, the last parameter specified is returned as the default value. If no parameters are specified then the orginal text of the expression, including the enclosing square brackets are returned.
All namespace uris are processed by the
EmailArgumentList or
WebEmailArgumentList, depending on which version of the argument list is passed to the call CreateMessage() template. If no argument is passed to CreateMessage(), then engine automatically creates an instance of
EmailArgumentList.
Standard Namespaces using EmailArgumentList¶
Using
EmailArgumentList exposes the basic standard namespace URIs. To do this you must pass an instance of
EmailArgumentList to the CreateMessage method.
For example:
EmailTemplate emailTemplate = EmailTemplate.Load( Server.MapPath("./EmailTemplate1.xml"));
SmtpClient smtpClient = new SmtpClient();
smtpClient.SendMessage( emailTemplate.CreateMessage( new EmailArgumentList() ) );
NOTE: At this time template expressions are NOT nestable.
Namspace: settings
The settings namespace returns that value of application settings from the application configuration file.
•"[setttings:" key [ "|" default-value ] "]"
The settings namespace evaluates expressions against the <appSettings>..</appSettings> section of the application configuration file. If the expression matches a key in the application configuration file then configured value for that key will be returned. If the key is not found then the default-value, if specified will be returned. If a default-value is not specified then the entire expression, including surrounding square brackets will be returned.
For example:
using an application settings section of the application configuration file similar to:
<appSettings>
<add key="email.to" value="fred.flintstone@bedrock.gov"/>
<add key="email.cc" value="Pebble Flintstone <pebbles.flintstone@bedrock.gov>"/>
</appSettings>
[settings:email.to] would result in the value "fred.flintstone@bedrock.gov"
or
[settings:email.cc] would result in the value "Pebble Flintstone <pebbles.flintstone@bedrock.gov>"
or
[settings:fubar] would result in the value "[settings:fubar]"
or
[settings:fubar|does not compute] would result in the value "does not compute"
Note that if you are sending email from a .NET application then the application configuration file is your app.settings file. You may need to add one to your visual studio project.
If your are sending email from an ASP.NET or Sharepoint application then the appliction configuration file is your web.config file.
Namspace: time
The time namespace returns the current date/time in a number of different format.
- "[time:now" [ "|" format ] [ "]" --> The current date / time
- Example: [time:now] --> "5/6/2005 02:34:42 PM"
- Example: [time:now|d] --> "5/6/2005"
- Example: [time:now|M] --> "May 6"
- Example: [time:now|(M) MMM, MMMM"] --> "(6) Aug, August"
- [time:longdate] --> "Wednesday, May 6, 2005"
- [time:longtime] --> "02:34:42 PM"
- [time:shortdate] --> "5/6/2005"
- [time:shorttime] --> "02:34 PM"
For more information on possible format text please refer to the Microsoft MSDN documentation
Date Time Format Strings.
Namespace: linked-resource
- "[linked-resource:" resource-url "]"
Where:
- resource-url - is any valid relative or absolute url that results in a path to a physical file.
The resource-url will be resolved to a data stream that is embedded inside the final email message. The result of the expression is an embedded url reference to the linked resource inside the message.
For example:
[linked-resource:./logo.jpg] would result in the value "cid:__embedded_0" (The actual embedded url may vary).
If the same linked resource is used more than once in the message, it will result in only one actual resource being linked into the email message.
Note that you can also specify linked resources explicitly by using the
section tag see Linked Resources for more details.
Linked resouce URLs are resolved in using the following two methods:
When EmailAgumentList is passed to CreatedMessage
The url is resolved using the EmailTemplate.TemplateUrl as it's based URI. This means that linked resource paths are relative to the location of the email template file.
The url is first resolved using the Server.MapPath() method of the IIS HttpServer context object. This means that linked resource paths are relative to the current IIS appllication path. If the url is not resolved then it is attempted to be resolved in the manner specified by EmailAgumentList above.
Standard Namespaces using WebEmailArgumentList¶
When you pass an instance of a WebEmailArgumentList to CreateMessage() method all of the Internet Information Server context objects are exposed to the template processor, in addition to the standard namespaces exposed by the EmailArgumentList.
For example:
EmailTemplate emailTemplate = EmailTemplate.Load( Server.MapPath("./EmailTemplate1.xml"));
SmtpClient smtpClient = new SmtpClient();
smtpClient.SendMessage( emailTemplate.CreateMessage( new WebEmailArgumentList() ) );
Namespace: server
The server namespace returns that value of server variable from the ServerVariables collection of the HttpRequest object for the current HTTP request, or a named property of the HttpServerUtility object.
- "[server:" name [ "|" default-value ] "]"
Where:
- name is the name of an IIS server variable the ServerVariables collection or the name of a property of the HttpServerUtility object.
- default-value is an optional default value that will be returned if the server variable or property is not found.
For a list of valid server variable names please refer to W3School's ServerVariables page.
For a list of valid property name for the HttpServerUtility object please see HttpServerUtility properties
Example
The raw url used to reach this page is [server:URL]
or
The browser used to reach this page is [server:HTTP_USER_AGENT]
Namespace: application
The application namespace returns that value of application state variable from the HttpApplicationState object for the current HTTP request, or a named property of the HttpApplication object.
- "[application:" name [ "|" default-value ] "]"
Where:
- name is the name of the item in the application state item collection or the name of a property of the HttpApplicationState object.
- default-value is an optional default value that will be returned if the state variable or property is not found.
For a list of valid property name for the HttpApplicationState object please see HttpApplicationState properties
Example
The value of application state variable named "myAppStateVariableName" is [application:myAppStateVariableName| not available]
Namespace: session
The session namespace returns that value of session state variable from the HttpSessionState object for the current HTTP request, or a named property of the HttpSessionState object.
- "[session:" name [ "|" default-value ] "]"
Where:
- name is the name of the item in the session state item collection or the name of a property of the HttpSessionState object.
- default-value is an optional default value that will be returned if the state variable or property is not found.
For a list of valid property name for the HttpSessionState object please see HttpSessionState properties
Example
The value of session state variable named "mySessionStateVariableName" is [application:mySessionStateVariableName| not available]
Namespace: request
The request namespace returns that value of an item from the Cookies, Form, QueryString or ServerVariables collections of the HttpRequest object for the current HTTP request, or a named property of the HttpRequest object.
- "[request:" name [ "|" default-value ] "]"
Where:
- name is the name of the item from the Cookies, Form, QueryString or ServerVariables collections or the name of a property of the HttpRequest object.
- default-value is an optional default value that will be returned if the item or property is not found.
For a list of valid property name for the HttpRequest object please see HttpRequest properties
Example
The path for the current page is [request:Path]
or
The ip address that is reading the current page is [request:UserHostAddress]
Namespace: user
The user namespace returns that value of a named property of the User object from the current HttpContext object.
- "[user:" name [ "|" default-value ] "]"
Where:
- name is the name of the item from the Cookies, Form, QueryString or ServerVariables collections or the name of a property of the HttpRequest object.
- default-value is an optional default value that will be returned if the property is not found.
All possible value expressions for the user namespace are
- [user:Identity.IsAuthenticated] - returns true if the current user is an authenticated user
- [user:Identity.AuthenticationType] - returns the current authentication type used
- [user:Identity.Name] - returns the name of the current user
Example
The current user is [user:Identity.Name]
Custom Namespaces
User's can pass parameters and extension objects to the EmailTemplate.CreateMessage method. These custom parameters and namespace can be accessed in the email template by using a custom namespace in the template expression.
For example
Calling the EmailTemplate.CreateMessage method as follows:
EmailTemplate emailTemplate.Load( Server.MapPath( "./EmailTemplates/MyTestTemplate.xml" ) );
EmailArgumentList argumentList = new EmailArgumentList();
argumentList.AddParam("hitchhiker", "alpha", 42 );
argumentList.AddParam("hitchhiker", "beta", "The answer to the ultimate question of life, the universe, everything" );
Restaurant restaurant new Restaurant();
restaurant.Name = "Milliways";
argumentList.AddExtension( "center", restaurant );
MailMessage mailMessage = emailTemplate.CreateMessage( argumentList );
SmtpClient smtpClient = new SmtpClient();
smtpClient.SendMessage( mailMessage );
would allow you to use the following template expressions:
[hitchhiker:beta] is [hitchhiker:alpha].
The restaurant at the center of the universe is called "[center:Name]"
which would result in the following text:
The answer to the ultimate question of life, the universe, everything is 42.
The restaurant at the center of the universe is called "Milliways".