EPiServer CMS Dynamic Content

Introduction

This technical note contains functional and technical information for the EPiServer CMS Dynamic Content functionality.

Table of Contents

• Overview
• Developing Dynamic Content
• Registering Dynamic Content with EPiServer CMS
• Adding Dynamic Content to a Page with the EPiServer CMS HTML Editor
• The Result

Overview

EPiServer CMS Dynamic Content allows developers to create blocks of functionality in code which can then be utilized later by an editor on a page in the HTML editor. This means editors are no longer restricted to working with static content and can make their pages more interactive. A dynamic content class can be thought of as a cut down version of an EPiServer template page, the implementation doesn't define a whole page, rather just a small section of it. A nice analogy would be a .NET UserControl, which in fact can be used to implement the user interface of a dynamic content object.

The logical workflow of dynamic content is as follows:

• The developer creates a .NET class that implements the EPiServer.DynamicContent.IDynamicContent interface (more about this later)
• The developer optionally creates a control to render the dynamic content user interface
• The dynamic content class is registered with EPiServer CMS in the web.config file
• The editor creates an instance of the dynamic content class, sets it's properties and places it as desired in the EPiServer HTML editor. 
• When the page is rendered in view mode, EPiServer CMS replaces the dynamic content design time markup with the actual XHTML output of the dynamic content class or its delegated control.

Developing Dynamic Content

The fundamental building block of a dynamic content class is the EPiServer.DynamicContent.IDynamicContent interface which can be found in EPiServer.dll. The interface's methods and properties are explained below.

string Render(PageBase hostPage)

The Render method should return the XHTML output to display on the page. This is what the visitor actually sees when they visit the page the object is being rendered on. The hostPage reference can be null as this method can be called by EPiServer without a page in context. This method should return null or an empty string if the class delegates rendering to a control.

Example:

public string Render(PageBase hostPage)
{
    if (hostPage != null)
    {
        return "<div>Hello from " + hostPage.CurrentPage.PageName + "!</div>";
    }
    else
    {
        return "<div>Hello there!</div>";
    }
}

System.Web.UI.Control GetControl(PageBase hostPage)

The GetControl method should return a reference to a control if the dynamic content class wishes to delegate its rendering responsibilities. The control returned can be anything that derives from control including web controls, user controls and custom controls.

Null should be returned if the class handles it's own rendering via the Render method.

Example:

public System.Web.UI.Control GetControl(PageBase hostPage)
{
    return hostPage.LoadControl("~/MyDynamicContentControl.ascx");
}

bool RendersWithControl { get; }

Return true if the class delegates rendering to a control, false otherwise.

string State { get;set; }

Get and set the state string for an instance. The class should use this value to serialize and deserialize its internal state. This can be null or an empty string.

Example:

public string State
{
    get
    {
        // Write out a simple comma seperated list of our internal values
        // Using Binary/XML serialization is probably more realistic for classes with more members
        return myString + "," + myInt.ToString();
    }
    set
    {
        // Parse the state string and initialize the member variables
        char[] seperators = { ',' };
        string[] values = value.Split(seperators);
 
        if (values.Length > 0)
        {
            myString = values[0];
        }

        if (values.Length > 1)
        {
            myInt = int.Parse(values[1]);
        }
    }
} 

Registering Dynamic Content with EPiServer CMS

To use a dynamic content class in EPiServer CMS, it must be registered in the site's web.config file. This is to ensure that only authorised content can be loaded and displayed. The XML segment below shows an example web.config extract with a dynamic content registration:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <episerver xmlns="http://EPiServer.Configuration.EPiServerSection">
    <dynamicContent>
      <controls>
        <add description="My example dynamic content class" 
          name="ExampleDynamicContent"
          type="MyNamespace.MyDynamicContent, MyDll" />
      </controls>
    </dynamicContent>
  </episerver>
</configuration>

Adding Dynamic Content to a Page with the EPiServer CMS HTML Editor

A dynamic content object is added to a page via the EPiServer CMS HTML Editor (in Edit mode). The editor sets the properties of the dynamic content object (if it has any). When an object has been added to a page it will be represented in the HTML editor as a non-editable text block. An example is shown below:

[DynamicContent:ExampleDynamicContent]

The "[DynamicContent:" part shows that it is a dynamic content placeholder and the text that follows before the final "]" charcter is the name given to the dynamic content class chosen in the web.config registration.

An example of the actual HTML markup for a dynamic content placeholder is shown below:

<SPAN contentEditable="false" 
      atomicSelection="true" 
      hash="eCNfsyKIZrKRLzXU0hMHwT4DZbwaozgMmfNI5Aky4zA=" 
      state="Hello,1" 
      classid="b30218a7-77fc-43dd-a844-81935aa9b35e">
  [DynamicContent:ExampleDynamicContent]
</SPAN>

The HTML must not be edited directly by the user, it is generated by EPiServer and is subject to change wíthout warning.

The Result

When the EPiServer CMS rendering code comes across a dynamic content tag in a XHTML string property, it will try and create an instance of the dynamic content class referred to, it will then call the object's State property to initialize it. After this it checks if the object delegates it's rendering to a control by calling the RendersWithControl property. If this property is true then the GetControl method will be called to obtain the rendering control, otherwise if false then the objects Render method is called to obtain the XHTML output. The placeholder span tag in the HTML output stream is then replaced by the output generated by the dynamic content object or delegate control so the person visiting your site can see the fruits of your labor.