Cartella has a very flexible email system. Customizing the built in emails and adding your own is very simple. There are two classes used for sending emails. These are the EmailDispatcher and the EmailContentController.

Sending an Email

The EmailDispatcher has an overloaded function called SendMail()()()() for sending emails. Its parameters are pretty straight forward. It takes the values passed in and creates a mail message that then gets added to the email queue. If you would like to send an HTML email, using this method, you must format the HTML yourself. A better option for sending HTML emails is to use the EmailContentController.

Modifying existing emails and Sending HTML emails using the EmailContentController

The EmailContentController is used to send HTML emails. To accomplish this, it uses XSLT. When an email is about to be sent, Cartella will load Default.xslt which has a reference to CustomTemplates.xslt in the "Content/EmailContent" folder of your Cartella application.

Note
If a localized version of Default.xslt is available, the localized verion will be loaded. (See: )

The EmailContentController has an overloaded function for sending emails called SendMail()()()(). Like in [t:Cartella.Classes.EmailDispatcher], the parameters are pretty straight forward with the exception of emailContentKey and variableToValue. These two parameters are used to create an XML document that is sent to "Default.xslt" to create the body of the email. Here is an example of the XML that will be created.

CopyXML

<CartellaEmail xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"><URL>http://www.mydomain.com</URL><Content EmailType="emailContentKey"><Key1><![CDATA[Value1]]></Key1><Key2><![CDATA[Value2]]></Key2><!-- If your value is is an XmlSerializableDictionary
        Your xml will look like this --><Key3><Key1><![CDATA[Value1]]></Key1><Key2><![CDATA[Value2]]></Key2></Key3></Content></CartellaEmail>

The emailContentKey is a string used to create the value of the EmailType attribute on the content element. The variableToValue Dictionary is used to generate the inner value of the Content element. Each key in the dictionary will become an element, and each value will become the value of that element. ToString is called on both the key and the value. Values will be wrapped in a CDATA tag. If you are using a custom type, make sure that you override the ToString method, otherwise your value will just be the fully qualified name of the class. Also, make sure that your keys will be translated into valid XML tags. Remember that XML tags may not begin with a number, so do not use int as the type for the key of your dictionary. All XML tags must begin with a letter and may not have special characters. They may have periods (.) so class names are ok. For sending more complex data structures, use the XmlSerializableDictionary. It has had its ToString method overridden to provide valid XML.

Now that you have your XML, you can useXSLT to create the body of your email. The default format of emails created with "Default.xslt" will have a header and footer. Then a template match in the Content node will be called. Here is an example of an XSL template.

CopyXML

<xsl:template match="Content[@EmailType='emailContentKey']">
    Here is the value of Key1: <xsl:value-of select="Key1"/><br />
    Here is the value of Key2: <xsl:value-of select="Key2"/><br />
    Here is the value of Key3: <br />
    <xsl:for-each select="Key3/*">
        <xsl:value-of select="name()"/>:<xsl:value-of select="."/>
        <br />
    </xsl:for-each>
</xsl:template>

This could create the following HTML output:

CopyXML

<head>
    <style type="text/css">
        /*CSS Rules Go here*/
    </style>
</head>
<body>
    HTML from the root template match created the head and this content
    Now calling the template for the Content node...

    Here is the value of Key1: Value1<br />
    Here is the value of Key2: Value2<br />
    Here is the value of Key3: <br />
    Key1:Value1
    <br/>
    Key2:Value2
    <br />

    HTML from the root template match goes here to create the footer...
</body>

Remember that most email clients will block all links to external references in emails to avoid their users getting too much SPAM. For this reason it is better to put the CSS inline in the head tag. Also, generally speaking, the fewer the images, the better. However, if you would like images in your emails, you must use the fully qualified URL of the image. To help you in this we have added a node at the top of the XML with the base URL of your site. Here is a line of code you would use to insert an image

CopyXML

<img src="{$URL}/Images/MyImage.jpg"/>

$URL is an xsl variable we have provided in "Default.xslt" for inserting images and links. By modifying the templates in "Default.xsl", you can customize all emails sent by Cartella. We recommend that if you are going to create new types of emails, that you put your new template matches in "CustomTemplates.xslt".