Update: If you're using CMS 6 R2 you'll want to check out this post on how to create new dynamic content in EPiServer CMS 6 R2.
What is dynamic content in EPiServer?
Dynamic content is essentially custom pieces of content that an EPiServer editor can insert through the TinyMCE editor. Together with the option of specifying dynamic content settings (ie properties for the dynamic content being inserted) we can create an easy way for editors to include virtually any type of content.
This dynamic content sample
Peter Sunna created one popular sample for inserting YouTube videos, but the applications for dynamic content are (nearly) endless. The following sample goes through how to create new dynamic content which uses a user control for rendering the content on a page template. We also look at how to specify dynamic content properties which are used by the editor when inserting dynamic content in page content.
Add a new dynamic content class
First we create the dynamic content type, called InsidersList, which is responsible for defining any dynamic content settings and also for rendering the dynamic content in page templates:
Add a user control for rendering the dynamic content
In this case we'll use a user control for rendering the actual dynamic content in page templates, so we'll create a new user control inheriting UserControlBase, much like we would for any page template user control in an EPiServer project:
Inherit the IDynamicContent interface
The InsiderList class we added needs to inherit IDynamicContent:
public class InsiderList : IDynamicContent
{
}
We right-click IDynamicContent and select Implement interface:
Next we implement the interface. The following implementation is for a dynamic content module which simply renders a user control without any settings:
public class InsidersList : IDynamicContent
{
#region IDynamicContent Members
public Control GetControl(EPiServer.PageBase hostPage)
{
// Return the user control to render
return hostPage.LoadControl("/Templates/DynamicContent/InsidersList/InsidersListControl.ascx");
}
public PropertyDataCollection Properties
{
// For now we won't use any settings for this dynamic content
get { return new PropertyDataCollection(0); }
}
public string Render(EPiServer.PageBase hostPage)
{
// This dynamic content is rendered by a control, so we don't implement this method
throw new NotSupportedException();
}
public bool RendersWithControl
{
// Yes, this dynamic content should be rendered by the control returned by the GetControl method
get { return true; }
}
public string State
{
// No need for saving state (ie dynamic content settings) right now
get;
set;
}
#endregion
}
Add dynamic content settings
Simply inserting a user control is usually not enough. For customizing dynamic content the editor usually needs to be able to specify some dynamic content settings. These are used by the editor when inserting dynamic content, for example to control appearance or data settings. A dynamic content setting is really an EPiServer property.
Add properties to the dynamic content type
For our InsidersList dynamic content we need to offer the editor the option of changing the default URL from which the insiders list is retrieved, and also the option of setting a different default sort key string.
We add these properties, and set their default values, in the constructor of the dynamic content class:
public InsidersList()
{
// Add dynamic content properties
Properties=new PropertyDataCollection(2);
Properties.Add("Url", new PropertyUrl());
Properties.Add("Default sort key", new PropertyString());
// Set default settings values
Properties["Default sort key"].Value = "listdatum";
Properties["Url"].Value = "http://se.yhp.waymaker.net/kungsleden/new/insider/insiderinc.asp";
}
Having added these two properties, when the editor clicks the Dynamic Content button in TinyMCE…
…and chooses Insiders list…
…the properties will be displayed automatically and allow the editor to set their values before inserting the dynamic content:
Persisting dynamic content settings
Dynamic content settings are stored through the State property of the dynamic content class. How dynamic content settings are saved/retrieved through the State property is up to you as a developer, but in our case we’ll stick with a pipe-separated string:
public string State
{
get
{
// Return dynamic content settings as a pipe-separated string
return string.Format("{0}|{1}",
Properties["Url"].Value,
Properties["Default sort key"].Value);
}
set
{
// We saved dynamic content settings as a pipe-separated string
var values = value.Split('|');
if (values.Length==2)
{
Properties["Url"].Value = values[0];
Properties["Default sort key"].Value = values[1];
}
}
}
How EPiServer uses the State property
When dynamic content is inserted by an editor, EPiServer invokes the getter of the State property to get the value it should save to the database. When the user control is loaded for display in page template, EPiServer invokes the setter of the State property to set the value of the State property to whichever value was saved in the database.
(This can probably be a bit confusing as first, but if you give it a minute you’ll see the logic. It’s the same principle as EPiServer uses for custom properties.)
Applying dynamic content settings to the user control
The user control we use to render the actual dynamic content on a page template doesn’t know in which context it is being loaded (ie which dynamic content instance loaded it), so we need some properties on our user control type to allow us to pass the dynamic content settings:
public partial class InsidersListControl : UserControlBase
{
public string Url { get; set; }
public string DefaultSortKey { get; set; }
}
We set these properties when we load the user control from the dynamic content class:
public System.Web.UI.Control GetControl(EPiServer.PageBase hostPage)
{
// Load user control
var control = (InsidersListControl)hostPage.LoadControl("/Templates/DynamicContent/InsidersList/InsidersListControl.ascx");
// Set user control properties based on dynamic content settings
control.Url = Properties["Url"].Value as string;
control.DefaultSortKey = Properties["Default sort key"].Value as string;
return control;
}
After that we can use these property values to control the user control appearance.
Register dynamic content in configuration
In order for editors to be able to insert the dynamic content we need to register it in episerver.config (or the <episerver> element in web.config).
In addition to a name and description (displayed in the Dynamic content dialog) we specify the fully qualified type name and assembly of the dynamic content type:
<dynamicContent>
<controls>
<add description="Insiders list provided by Cision"
name="Insiders list"
type="Website.Templates.DynamicContent.InsidersList.InsidersList, Website" />
</controls>
</dynamicContent>