all things Sitecore related

Building custom newsletter templates for Sitecore’s ECM 2.x

By on September 23, 2013 in ECM, Sitecore with 4 Comments

This blog post describes how to create a custom news template for ECM 2.x. This template is made available in the SPEAK interface so content editors and marketers can start using it. When a newsletter is created based of this template, it is possible to dynamically add controls to it and personalize it.

The given Example is created based on the analysis of the delivered example which is provided when the ECM 2.x package is installed.
To install ECM on your current Sitecore installation, you can follow the installation guide from SDN.

The final goal of this blog post is to create a small newsletter template and some presentation components. The screenshot below represents the newsletter that will be created in this post.
The blocks in the middle of this newsletter can be added dynamically to a placeholder.
The header and the footer are not created in this post but can be filled by configuring predefined content or it could be filled statically. (this is not covered in this blog post)

Create the newsletter

To build the example the following steps are taken to create a custom newsletter template in ECM.

  1. Create the newsletter branch template
  2. Create the content item templates
  3. Create the layout
  4. Create the sublayouts
  5. Create placeholder definitions
  6. Bind the presentation
  7. Make the template available in the SPEAK interface
    (this step is also available in chapter 5.4 Message Type Configuration of the Sitecore E-mail Campaign Manager Administrator’s and Developer’s Guide on SDN.)
  8. Create and test  the newsletter

Step 1: Create Branch Template
ECM Newsletters are created based on a branch templates (Chapter 6.2 of the Data Definition Reference describes what Branch Templates are and how you can use them in Sitecore). To store the Branch Template in Sitecore a Branch Folder can be created under Branches. For the example I used Custom Newsletter.

In this folder a new branch, based on the Branch template is created. All Monthly Newsletters in ECM are created based on this new template.
The default name of this new template is called Branch, as good practice you can rename the new template to “Monthly Newsletter” and change the icon.

Now that the template is created we need to make sure that the newsletter that is created by the branch template follows the right structure.

To enforce this the template type of the $name item must be changed. The $name item should be of the type AB Testable Message,
this is needed to be able to send A/B testable messages.

Furthermore a “Message Root” for the newsletter template should be created.
This item holds some basic fields and the presentation layout for a newsletter that is based on this template.
The presentation components will be later bound to this Message Root item.

To connect the message root to the newsletter the body field in the $name item must be specified.

After completing the steps above the newly created structure for the branch template should look like this:

Step 2: Create Content Items Templates

To be able to add dynamic content to a placeholder I created a Custom Newsletter Content Block. This template can be used to dynamically add content to the newsletter.

Notice the source of the Rich Text field (/sitecore/system/Settings/Html Editor Profiles/Message Content). This HTML Editor profile was especially designed to support newsletter content.

Step 3: Create Layout

The first thing I create is the layout, this layout is later on connected to the message root of my custom email newsletter as mentioned in step 1.

The following html is used in the Monthly newsletter layout:

<%@ Register TagPrefix="sc" Namespace="Sitecore.Web.UI.WebControls" Assembly="Sitecore.Kernel" %>
<%@ Register TagPrefix="sc" Namespace="Sitecore.Web.UI.WebControls" Assembly="Sitecore.Analytics" %>
<%@ OutputCache Location="None" VaryByParam="none" %>
<!-- Used for storing title of the email -->
<sc:Placeholder Key="mn-title" runat="server" />
<!-- The VisitorIdentification control ensures that people viewing this page
with a traditional web browser will be classified as humans not bots.
This control is not required if people only view messages using Email clients -->
<sc:VisitorIdentification runat="server" />
<body style="background-color:#1C1C1C">
<form method="post" runat="server" id="mainform">
<table width="100%">
<td width="100%" colspan="2" style="background-color:#1C1C1C;color:#FFFFFF">
<!-- Used for storing the title of the newsletter in h1 -->
<sc:Placeholder runat="server" Key="mn-header" />
<td width="100%" style="background-color:#E6E6E6;color:#00000">
<!-- Used for storing the content blocks of the newsletter in h2 and paragraphs -->
<sc:Placeholder runat="server" Key="mn-content" />
<td width="100%" colspan="2" style="background-color:#1C1C1C;color:#FFFFFF">
<!-- Used for storing the footer e.g. the unsubscribe link -->
<sc:Placeholder runat="server" Key="mn-footer" />

Step 4: Create SubLayouts
To display the dynamically added content blocks I created a Monthly Newsletter Block Sublayout. To let the user choose from a list of content blocks and to let the user create content in that specific location I filled the Datasource Location and Datasource Template in the Sublayout item in Sitecore.

I added controls to the ascx file to display the title and the body fields.

<h1><sc:Text runat=”server” ID=”txtTitle” Field=”Title” /></h1>
<sc:Text runat=”server” ID=”txtBody” Field=”body” />

Note: I tried to use sc:fieldrender for the title field and add an enclosing tag. Unfortunately this control didn’t have any output in the newsletter. I changed it to sc:text and this worked. For now I would say sc:fieldrender is not supported in ECM templates.

Step 5: Create Placeholder Definitions
To be able to control which sublayouts can be placed on the different placeholders the matching definitions are created in Sitecore. On this placeholder definition the Newsletter Monthly Block is added to the allowed controls. This allows the end user to add this control to the mn-content placeholder in the newsletter.

Step 6: Bind the Presentation

Now that all the components are created it is possible to bind all these together. Open the message root from the custom newsletter and open the presentation details. For the default device choose the created layout. A minimum of two controls are needed to let the newsletter work fully.

The existence of these two controls and how they should be used are also mentioned in the Sitecore ECM 1.3.3 to ECM 2.0 Upgrade Instructions. At this moment I am not sure where the controls must be placed, but I always place the target item in my first placeholder and the process personalization tokens in the last placeholder.

UPDATE 14-10-2014:  Add the “Set Page Title” rendering to the presentation details if you would like to save the modifications of the message subject using the ECM UI.
The path for this rendering is: “/sitecore/layout/Renderings/Email Campaign/Set Page Title”.
Update was provided by: Maria Sherbakova

Step 7: Make the newsletter template available in SPEAK

This the actual last configuration step in this process. To make the template available for the end users in the SPEAK interface of ECM the template must be assigned as Insert Option for a specific Message type.



Step 8: Create and test the message

Now that all configuration steps are made it is now possible to create and test the message. You can do this by opening the E-Mail Campaign Manager from the start menu in the Sitecore desktop. In my example I added the monthly newsletter to the One Time Message type. So first we create a One Time message and select the monthly newsletter. A more detailed description on how to create message in the SPEAK interface can be found in chapter 3.2 of the ECM Marketers Guide on SDN.


Now a new newsletter is created based on the newsletter branch template, which was created previously. In this blog post the basics of working with ECM in the SPEAK interface are not covered, so we move directly to editing the message itself. A more detailed description on how to edit a message in the SPEAK interface can be found in chapter 3.4 of the ECM Marketers Guide on SDN.

Double clicking on the message body opens a popup where the body of the message can be edited through the Page Editor of Sitecore.
Now content items can be added to a placeholder like you would normally do with the Page Editor in Sitecore.

Choose “Add to here” to add a content item to the mn-content placeholder.

Because the allowed controls was set in the placeholder definition we can only choose the Monthly Newsletter Block. The popup for adding a datasource to this control is opened. It is now possible to Select Existing Content or Create New Content. The reason for this is because we have set the Datasource Location and the Datasource template in the control properties. In the example I select the predefined block “block 1”.

Selecting the content will result in the Monthly Newsletter Block to be added to the page layout. Because dynamic binding is used it is also possible to use the personalization and the multivariate testing feature from Sitecore.
You can now save your message. When the message is completely configured you can send the message How to this works is described in chapter 6 of the ECM Marketers Guide on SDN.

About the Author

About the Author: .


If you enjoyed this article, subscribe now to receive more just like it.

There Are 4 Brilliant Comments

Trackback URL | Comments RSS Feed

  1. Lorent Dione says:

    Thanks for a great post!
    I am running into one issue and wondering if anyone has experienced it. Basically the sc:text in the sublayout does not display it’s content. I have tested the sublayout outside of ECM and it work fine. However when I add it in my Newsletter the sc:text tag don’t display their content. I have searched for sc:text and ECM related issue but no luck… Any idea what might cause this issue?

    • Anis Chohan says:

      @Lorent Dione I had issues with sublayouts, reverted to xslt’s and the sc:text and all other sitecore controls worked like a charm.

  2. Michael says:

    There is an error in step 4. It’s important that the datasource location of the sublayout is relative to the message root. Not to a fixed folder outside the message root. Otherwise the insert options won’t work in the rich text editor . To reference the message root use “./” in the field Datasource Location .

  3. Raul says:

    In order to use a datasource with Sublayout you need to retrieve the datasource in code and then set it as the .Datasource or .Item property of each of the field controls. You can have a base class do this for you (i.e. with a bit of magic with a ContextItemSwitcher)

    This would work fine in an XSLT as the sc_item is automatically populated with the datasource (if set) otherwise it defaults to the context item (whereas sc_currentitem is always the context item, even when the datasource is set)

Post a Comment

Your email address will not be published. Required fields are marked *