Extending the User Interface of EPiServer 7

You have probably not missed that EPiServer 7 comes with a brand new user interface for content editing. This is built on top of a new UI-framework that is also used on the new dashboard. In this blog series I’ll explain how to implement some of the most common extension scenarios.

Note: The code in this blog series is based on the latest build and might not work in EPiServer 7 preview or other later builds.

How the UI is built up

In previous versions of EPiServer CMS the user interface consisted of a simple page containing a table structure with a bunch of iframes where each function was plugged in or in some cases hard coded. The page was running in quirks document mode to enable resizing of the each iframe.

In EPiServer 7, the UI-framework that is used to build the dashboard and CMS edit view works quite different:

1. A simple page is loaded. It contains some script and styling references and a JavaScript bootstrapper that is responsible for setting up the UI.
2. The bootstrapper fetches the components for the specific view using a REST-based store, start them up and adds them to their correct hierarchical placement.

All this is done on the client using the JavaScript framework Dojo. It’s still possible to use your jQuery-style gadgets to plug in to the new UI-framework but writing components in Dojo will give you more built in functions and styling for free. It’s up to you to decide what suits your needs and skills best.

If you are new to Dojo (which I guess most of you are) there is an introduction section in the framework SDK that points to some good resources to get started. For instance, there are some good tutorials here:

• Arrays Made Easy
• Creating a custom widget
• Events with Dojo
• Getting Started with Deferreds
• Classy JavaScript with dojo.declare

Setting up a module

If you don’t already have a shell module set up we need to add this to be able to add plug-ins to the user interface. The simplest way to get started is to add the following configuration into a file named module.config to the root folder of your site:

<?xml version="1.0" encoding="utf-8"?>

<module>

    <assemblies>

        <!-- This adds the Alloy template assembly to the "default module" -->

        <add assembly="EPiServer.Templates.Alloy" />

    </assemblies>

    <dojoModules>

        <!-- Add a mapping from alloy to ~/ClientResources/Scripts to the dojo loader configuration -->

        <add name="alloy" path="Scripts" />

    </dojoModules>

</module>

Note: The assembly should match the name of your template assembly in this case.

Using web forms

We recommend writing your plug-ins using Dojo or potentially jQuery to get a nice integrated look and feel. Sometimes you just want to add something simple or quickly convert a plug-in for CMS 6 –> 7. To enable this we have added an attribute to be able to load a web forms page or user control inside an iframe. A simple example of this could look like this:

using EPiServer.Shell.ViewComposition;

using EPiServer.UI;

using EPiServer.Web;

namespace EPiServer.Templates.Alloy

{

    [IFrameComponent(Url = "~/IFramePageExample.aspx",

        ReloadOnContextChange = true,

        PlugInAreas = "/episerver/cms/assets",

        Title = "Iframe test",

        Categories="cms",

        MinHeight = 100,

        MaxHeight = 500)]

    public partial class IframePageExample : ContentBaseWebForm

    {}

}

Note: We are inheriting from the class ContentBaseWebForm that is located in the EPiServer.UI assembly since we want to be able to handle all content types and not just pages. The attribute itself is defined in the EPiServer.Shell assembly.

Update: In EPiServer 7.5, the base class to use is: EPiServer.Shell.WebForms.ContentWebFormsBase

ReloadOnContextChange: Can be defined to reload the iframe content with a new content id each time the user changes context.

PlugInPaths: Can be used to auto-plug in a component into a given location in the user interface.

Categories: Defines where this components can/should be added. The current implementation is to only show components to the user that matches the category of the view. Currently used categories are “cms” and “dashboard” but we will probably add more categories as we convert more views to the new framework.

To see that we are loading the current item we add a simple output of the name in the code-front file:

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="IframePageExample.aspx.cs" Inherits="EPiServer.Templates.Alloy.IframePageExample" %>

<html xmlns="http://www.w3.org/1999/xhtml">

<head runat="server">

</head>

<body>

    <form id="form1" runat="server">

    <div>

<%

   1: =CurrentContent.Name 

%>

    </div>

    </form>

</body>

</html>

Which will result in the following in the UI:

We will continue writing more samples and update the links below:

Extending the User Interface of EPiServer 7

Creating a Dojo based component

Creating a content search component

Adding a more advanced property editor