Hide menu Last updated: Oct 24 2016
Area: Episerver Commerce Applies to versions: 10 and higher
Other versions:

Notifications

This topic describes how the Episerver Commerce notification/template engine automatically sends out email notifications for new orders, customer registrations, email forms, and so on. The notification/template engine generates types of templated content and creates personalized emails for customers regarding orders.

How it works

The template engine is based on the ASP.NET 2.0 Provider Model. You can customize or replace the engine without needing to access any framework source code. The default implementation is an XSL-based template provider, allowing for the creation of templates using XML Stylesheet Language (XSL).

Classes in this topic are available in the following namespaces:

  • EPiServer.Business.Commerce. Contains CheckoutWizardModule.
  • Mediachase.Commerce.Engine.Template.Providers. Contains XslTemplateProvider.
  • Mediachase.Commerce.Engine.Template. Contains TemplateService and TemplateProvider.

Key classes and files

  • TemplateService.cs. Loads the appropriate template provider and returns formatted text for the email.
  • CheckoutWizardModule.ascx. Uses the TemplateService to generate the text for order-related emails. See the SendEmails methods.
  • XslTemplateProvider.cs. Custom template provider included.
  • TemplateProvider.cs. Base class from which all template providers must inherit.

Quick overview

The web.config file of your public/admin sites contains this section:

<system.net>
  <mailSettings>E:\Template\en-us\order-purchaseorder-confirm.xsl.
    <smtp>
      <network host="localhost"/>
    </smtp>
  </mailSettings>
</system.net>

You can add a user name and password in the file and authentication for the SMTP server, if required. See MSDN for more information on configuring email settings.

The templateSource attribute shows how to use the template name and CultureInfo parameters. Use CultureInfo for the folder name containing the templates for that language. The filename is specified as the template name with an .xsl extension.

An example of the resulting file path for a template

  • in English (CultureInfo name = "en-us")
  • for the order confirmation (template name = "order-purchaseorder-confirm")
  • where your templateSource setting is E:\Template{0}{1}.xsl

would be:

E:\Template\en-us\order-purchaseorder-confirm.xsl
Place the PublicLayer\Templates\en-us items in the directory in the template source. These are the template emails you need to customize.

Template service

An example of calling the TemplateService is in the CheckoutWizardModule control. Relevant data, including the PurchaseOrder object, are placed in a dictionary and passed to the TemplateService.Process() method with the name of the template, and a CultureInfo instance representing the desired/current culture. The Process() method returns the formatted custom text.

The following code is taken from CheckoutWizard.ascx.cs in the front end, but you can apply it to the back end also. The template service replaces the placeholders with the proper text. You can also add your own files to be used with the template service.

Template provider

The XSL/XMLTemplate Provider renders templates using a set of XSL files and expects that all parameters passed in the dictionary context can be serialized to XML. The provider then looks in the path specified in the configuration file (templateSource property) for the specific XSL. If it cannot find the file in the language-specific folder, it tries to fall back and look in the "default" folder.

It is then processed by the template similar to this example.

Template engine

Calling the template engine API is done as in the example below.

Example: calling the template engine

// Execute template processor
    string body = TemplateService.Process("order-confirm", Thread.CurrentThread.CurrentCulture, 
    new Dictionary<string, object>());

As you can see, three parameters are passed: template name, current culture, and a dictionary collection.

Related topic

Comments