EPiServer : How To Create A Custom Admin Plug-in in Less Than 5 Minutes

In this tutorial, I will show you how to quickly create an EPi server admin plug-in from scratch… in less than 5 minutes, that will also load and save data into Epi-server.  The plug-in will display the current time and a button to update it.  The time will be stored within epi-server so it will persist.  After we create the plug-in you will be able to see it in the Admin section for your site, available from :  Admin Mode -> Tools menu (as seen below)

Epi Admin Plugin Screenshot

The first thing is to create the aspx page that will display the plugin.  In Visual Studio, create a new standard Page type.  You will need to decide where your admin plug-in is going to live within your webroot.  For this example, I am going to add them into a folder in Webroot -> Templates -> Plugins as the actual location doesn’t matter but for keeping your project easy to maintain, I would recommend putting it somewhere within templates under your site folder.  For my page I have called the page ‘Example’ with a matching namespace.

My aspx file is very simple. All I’m doing is adding a button and a call to a method to display the time :

<%@ Page Language="c#" Codebehind="ExamplePlugin.aspx.cs" AutoEventWireup="False" Inherits="Example.AdminPlugin" Title="Example" %>
The time is <%= GetTheTime() %>

The code behind is a bit more tricky as it has to do several things :

  • Define the control as an Epi plug-in
  • Define GetTheTime to display the time
  • Define UpdateTheTime to get time
  • Store everything within Episerver so the time persists.

In our code behind, the first thing we need to do is change the base type of the control from the .NET ‘Page’ to an EPI ‘SimplePage’. Next we need to add the Epi server plug-in declaration attribute so it displays in the back-end.  This is a single line that you need to place on top of the class declaration. Call it whatever you want but make sure the Url property points to the aspx page in your webroot.

[GuiPlugIn(DisplayName = "Example", Description = "Example", Area = PlugInArea.AdminMenu,
Url = "~/Templates/Plugins/ExamplePlugin.aspx")]

The next step is to create a method to load and store the time into Epi.  This data access is done via the Epi API using the PlugInSettings with the Populate and Save method.  The only downside of using ‘PlugInSettings’ is it works using DataSets, which isn’t ideal.  To keep things simple, I’ve wrapped these calls into a custom class that my page will call.  In the constructor of the class I initialise a new Dataset on creation and stores or loads a string.

 public class AdminPluginSettings
{
private DataSet customDataSet;
private string Key = "Example";
private static readonly log4net.ILog Logger = log4net.LogManager.GetLogger
(System.Reflection.MethodBase.GetCurrentMethod().DeclaringType);
public AdminPluginSettings()
{
customDataSet = new DataSet();
customDataSet.Tables.Add(new DataTable());
customDataSet.Tables[0].Columns.Add(new DataColumn(Key, typeof (string)));
}
public string LoadData()
{
var returnValue = string.Empty;
try
{
PlugInSettings.Populate(typeof (AdminPluginSettings), customDataSet);
returnValue = customDataSet.Tables[0].Rows[0][Key].ToString();
}
catch (Exception ex)
{
Logger.Error(ex);
}
return returnValue;
}
public void SaveData(string stringToSave)
{
try
{
var newRow = customDataSet.Tables[0].NewRow();
newRow[Key] = stringToSave;
customDataSet.Tables[0].Rows.Add(newRow);
// Stores your data in EPI no need to worry about config files or custom database calls
PlugInSettings.Save(typeof (AdminPluginSettings), customDataSet);
}
catch (Exception ex)
{
Logger.Error(ex);
}
}
}

One thing to note is that  I’m using Log4net out the Epi box in all EPi sites for error handing.  You can see in Load and Save that I’m using ‘PlugInSettings’ to store or load the data.  Now the only bit left to do is wire up the new class in our control.

    [GuiPlugIn(DisplayName = "Example", Description = "Example", Area = PlugInArea.AdminMenu,
Url = "~/Templates/Plugins/ExamplePlugin.aspx")]
public partial class AdminPlugin : SimplePage
{
public string PluginDisplayString { get; set; }
private AdminPluginSettings _settings;
public AdminPlugin()
{
_settings = new AdminPluginSettings();
}
protected override void OnLoad(EventArgs e)
{
base.OnLoad(e);
if (!PrincipalInfo.HasAdminAccess)
{
AccessDenied();
}
}
public string GetTheTime()
{
return _settings.LoadData();
}
protected void UpdateTheTime(object sender, EventArgs e)
{
var time = DateTime.Now.ToString("HH:MM:ss");
_settings.SaveData(time);
}
}

It really is that simple.  You can download the full source code here, Epi Admin Plugin Example, enjoy 🙂

Jon D Jones

Software Architect, Programmer and Technologist Jon Jones is founder and CEO of London-based tech firm Digital Prompt. He has been working in the field for nearly a decade, specializing in new technologies and technical solution research in the web business. A passionate blogger by heart , speaker & consultant from England.. always on the hunt for the next challenge

More Posts