Rapido email templates

Rapido contains a simple and easy to use engine for implementing email templates – an engine which ensures that your emails look good in every client, and are identical across the solution.

The email templating engine uses Razor helpers to render markup. This has the great advantage that the code can be tidy and beautiful, and still be used to create dynamic content and pass variables through the helper methods. The downside, of course, is that using them across templates (via @Include or @MasterPageFile) results in a lot of red lines in Visual Studio, and that it can be difficult to trace errors.

We believe that this tradeoff is worth it – while it may be hard trace errors, using the engine also makes email templates much less error prone.

Currently Rapido contains the following email templates:

  • The EmailMaster.cshtml template must be set as the master template in all email templates. This template is located in the root of the Rapido folder.
  • The EmailTester.cshtml template contains an example implementation of an email created using the Rapido email engine. This template is located in the paragraphs folder of the Rapido design.

The EmailTester template can also be used as a boilerplate when implementing a new email design.

To set up at page for testing simple emails in the browser:

  • Create a page and go to Page properties > Layout and select clean.cshtml as the page template
  • Create a paragraph and select the email template as the paragraph template
  • Click Show page in the ribbon bar of the test page

Try it out – log in to the solution, and go to Content > Tools > Email tester and click Show page.

The current email engine may be viewed as work in progress – we are actively working on making it both more capable and easier to use for the implementer.

Start by creating the template in the appropriate Dynamicweb folder inside the Templates/Designs/Rapido folder, e.g. in /eCom7/CartV2/Mail for an order email. Give it the same name as the default name for the template.

Then add the following to the top of the template:

@inherits RazorTemplateBase<RazorTemplateModel<Template>> @using Dynamicweb.Rendering; @MasterPageFile("../../../EmailMaster.cshtml")

The first two lines are just to declare that we are using a Dynamicweb Razor template.

In the @MasterPageFile you should link back to the design root where the email master is found. Remember to adjust this for each new template.

To add a pre-header with a generic link to an online version of the email, which all clients can read, call the @CreatePreheader() helper.

All content in the email must be enclosed by this table:

<table bgcolor="#FFFFFF" border="0" cellpadding="0" cellspacing="0" width="500" id="emailBody"> //Content must be placed as email rows here </table>

To create a footer with an unsubscribe link – a requirement for e.g. newsletters – simply call the following helper method:

@CreateSubscriptionFooter()

One of the strong points of the email engine is that it uses simple rows with columns inside to structure the email content. This makes it possible to design emails which will work on all email clients – provided that you follow these simple rules:

  • You MUST use the @CreateRow helper method to design your email
  • You MUST NOT under any circumstances introduce new tables or divs in your emails. You WILL lose email client support if you do.

Besides ensuring email client support, the row + column concept is perfectly easy to implement.

The method has three overloads + a row configuration object. That is one overload for each column that you want in the row (One to three columns are supported).

A simple row with a background color is made like this:

Column header = new Column(); header.image = logoimage; header.align = "center"; @CreateRow(header, new RowSettings { backgroundColor = "#0B85C8" });

First you create the Column object, and define what settings it should have. Then you call the CreateRow helper, and if something should be custom on the row, we create the RowSettings object.

The following method with overloads are available:

@CreateRow(Column, RowSetting); @CreateRow(Column, Column, RowSetting); @CreateRow(Column, Column, Column, RowSetting);

One more, simple, helper method is available – it simply creates a divider between two rows. The divider includes a horizontal line:

@CreateRowDivider();

The following properties are available for the column:

Property

Data type

Description

backgroundColor

STRING

 

Padding

STRING

 

The following properties are available for the RowSetting:

Property

Data type

Description

Image

STRING

 

imageSize

 

Do not use this, the property is automatically set by the columns

preheader

STRING

 

introheader

STRING

 

header

STRING

 

subheader

STRING

 

textColor

STRING

 

align

STRING

(Left, Center, Right)

link

STRING

 

linkText

STRING

 

buttonColor

STRING

 

Furthermore, the Column has a method for adding lines of text. Call it like this:

Column.text.Add(“My text”);

Rapido comes with a small set of ready build email blocks the may be re-used all over. This secures continuity in the design, and makes it easier to do recurring design tasks.

To use them, include the helpers in the template where needed:

@Include("../../EmailHelpers.cshtml")

Then just call the helpers where they should render. Sadly you will not get any code hinting on this in Visual Studio, and the helpers will be marked red, as Visual studio does not know that they exist in the included file.

The email helpers available are:

  • RenderHeaderImage()
  • RenderFooterSection()
  • RenderButton(string link, string text)

They should be self-explanatory.

For Ecommerce order emails the following helpers are available:

  • RenderRecurringDetails()
  • RenderComments()
  • RenderAddresses(string billingTitle, string deliveryTitle, string prefix)
  • RenderPaymentAndShipping()
  • RenderOrderline(LoopItem orderline, bool showImage = true)
  • RenderProduct(LoopItem product)
  • RenderGiftcards()