Getting started with EPiServer plugin development

Recently I had the opportunity to attend the EPiServer Developer Training, which is an excellent start to using EPiServer as a developer.  I left the training confident that I could develop a website which is exactly what I was hoping for.  At the end of the training however was a certification exam, and taking that is another story altogether.  Anyway, what I really wanted to do after the training was to work on a couple of plugins or simple sites to cut my teeth on.  This was the first one I worked on, start to finish approximately 2 hours.

The purpose of this plugin is not to cover new ground as far as the EPiServer community, but for me to put my training to use.  The goal was to create a practical plugin that leveraged EPiServer’s configuration free automatic plugin registration – my experience with other content management systems tells me that this is a very nice feature and promotes code reuse.  After a few minutes of thinking of my recent clients’ needs I settled on a Vimeo Video Embed Dynamic Content plugin.  This would make it easy for content author’s to insert Vimeo videos into their content.

The Basics

From EPiServer’s documentation you will see that this is really simple.  Use the DynamicContentPlugin attribute to give some meta information about your plugin and some configuration.

26
27
28
29
30
31

[DynamicContentPlugIn(
	DisplayName = "Vimeo Video",
	Description = "Displays a vimeo video",
	Area = PlugInArea.DynamicContent)]
public class VimeoEmbed : IDynamicContent
{

Just like that you’ve got a DynamicContent plugin that’s gets automatically registered on EPiServer startup.  Of course, it doesn’t do anything yet, but we’ll get there.

The Properties Collection – How Users Configure the Dynamic Content

The Properties collection is where you configure the form that users see when selecting your plugin.  There is also a way to use a user control as an edit form, but for now let’s keep it simple.

Below in the constructor you can see that we’re adding properties to the Properties collection of the appropriate type.  PropertyString becomes a textbox, PropertyBoolean becomes a checkbox, etc.  You can also give the properties a default value, configure it as a required field, etc.

85
86
87
88
89
90
91
92
93
94
95

public VimeoEmbed()
{
	Properties.Add("Video ID", new PropertyString());
	Properties["Video ID"].IsRequired = true;
 
	Properties.Add("Show Title", new PropertyBoolean());
	Properties["Show Title"].Value = true;
 
	Properties.Add("Show ByLine", new PropertyBoolean());
	Properties["Show ByLine"].Value = true;
	...

So are we finished?

At this point I would like to say that we are finished, but we’re not!  It seems that the plugin author must manage the State manually… what’s that?!  Of the examples I could find, this seems a bit messy.  The configuration options users enter on this screen get saved in the HTML of the richtext field the user put the dynamic content in by way of the content author’s (de)serialization methods.  Take for example the following:

126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159

public string State
{
	get
	{
		return string.Format("{0}|{1}|{2}|{3}|{4}|{5}|{6}|{7}|{8}",
			 Properties[keyID].Value,
			 Properties[keyTitle].Value,
			 Properties[keyShowByLine].Value,
			 Properties[keyShowPortrait].Value,
			 Properties[keyColor].Value,
			 Properties[keyAutoplay].Value,
			 Properties[keyLoop].Value,
			 Properties[keyWidth].Value,
			 Properties[keyHeight].Value
		);
	}
	set
	{
		var values = value.Split('|');
 
		if (values.Length == 9)
		{
			Properties[keyID].Value = values[0];
			Properties[keyTitle].Value = values[1];
			Properties[keyShowByLine].Value = values[2];
			Properties[keyShowPortrait].Value = values[3];
			Properties[keyColor].Value = values[4];
			Properties[keyAutoplay].Value = values[5];
			Properties[keyLoop].Value = values[6];
			Properties[keyWidth].Value = values[7];
			Properties[keyHeight].Value = values[8];
		}
	}
}

That messy solution seems to contradict how easy it is to register the plugin in the first place, no?

Final Thoughts

Post training, this is literally my first couple of hours hands-on with EPiServer. The path I took on this plugin might not have uncovered the best solutions. One thing I didn’t like was how the key on the Properties collection is also the field label on the auto-generated form. The second thing is how State must be manually managed – there must be a simple method that can be used across the board for simple types. I could create a custom form control for the labels, but really we want to cut down on development time and maximize on code reuse.

Downloading

This project could be useful to anyone who wants to make their own DynamicContent plugin. It is licensed under Apache License 2.0, so you’re free to use the source or do whatever you want to do with it.

DOWNLOAD HERE

Resources:

• DynamicContent Plugin Documentation - http://world.episerver.com/Documentation/Items/Tech-Notes/EPiServer-CMS-6/EPiServer-CMS-6-R2/Dynamic-Content/
• Vimeo Video DynamicContent Plugin Page - http://world.episerver.com/Code/PatrickMJones/Vimeo-Video-Dynamic-Content-Plugin/