How To Render A Custom View In The Episerver Asset Panel

Episerver provides a number of ways for developers to customise the Episerver editor.  Today, I’m going to create two widgets that will be available in the right hand asset management panel.  One will display a custom html page and one will display a custom view generated via a controller.

Custom_Asset_View

Dojo

Dojo is a bit of a cursed word around most offices I work in.  Dojo is a front-end library that the Episerver editor is based on.  If you want to customise the Episerver editor, eventually you’ll stumble upon Dojo. The annoying thing with Dojo is it’s lack of main stream usage.  If I was building a front-end Ui with scripting languages, I’d use JQuery, Angular, Node etc.. Learning the in’s and out’s of a framework just to be able to write a few Episerver editing components once or twice a year is a big ask for any developer.  Luckily, to get our view working, the script that we need is very easy.

Defining Our Widget

First we need a class that registers the widget within Episerver.  To do this you have to decorate a class with the Component attribute in the EPiServer.Shell.ViewComposition namespace.  This attribute will register where Episerver should display the widget, what it should be called etc…

[Component(PlugInAreas = PlugInArea.Assets,
Categories = "cms",
WidgetType = "jondjones.jondjones.UserManual",
Title = "User Manual",
SortOrder = 1100)]
public class UserManualWidget
{
}

The code is very simple:

  • PlugIn Areas : Tells Episerver which area to render the widget, in this tutorial we just case about the asset panel but we have several other options available to us as well
  • Categories : Where to display the widget, in the CMS, Commerce, Find etc..
  • WidgetType : Tells Episerver where to find the custom js file that will define which view should be loaded.
  • Title : The name that will be displayed within Episerver
  • Sort Order : Which position it should render in the assets panel

Important In WidgetType, the jondjones.jondjones bit is the js namespace dojo will use to find the appropriate js files we’ll use.  These values will have to exactly match up the namespace values in the preceding steps.  The namespace part has to be all lower-case, otherwise Episerver will not find your JS file and will likely throw an error.

Module.Config

Next, if you haven’t got one already, you will need to create a modules.config in your webroot

<?xml version="1.0" encoding="utf-8" ?>
<module>
<dojoModules>
<add name="jondjones" path="Scripts/widgets" />
</dojoModules>
</module>

Notice how the name value in the add dojoModules section matches the first part of the namespace. One importmant thing to note is that the path attribute is relative to the ClientResources folder in the website root, e.g. in the ClientResources folder it will look in Scripts/widgets for your custom widget js scripts.

Creating The Correct Folder Structure

The last piece of the puzzle is to create the JS file that will load our custom view.  If you haven’t already got the folder structure defined in the modules step in your web root, you will need to create them now.

In you webroot create the following folders:

ClientResources -> Scripts -> widgets -> jondjones

In this case the ‘jondjones’ is the second part of the namespace that we defined in the WidgetType.

Client_resources_folder_structure

Creating the Dojo Dijit

In the ‘jondjones’ folder, we are going to create the dojo digit file that will tell Episerver which view to load.  The name of the js file needs to match the last part of the WidgetType that we defined in the first step, in this case it’s called UserManual.

define([
"dojo/_base/declare",
"dijit/_WidgetBase",
"dijit/_TemplatedMixin"
], function (
declare,
_WidgetBase,
_TemplatedMixin
) {
return declare("jondjones.jondjones.UserManual",
[_WidgetBase, _TemplatedMixin], {
templateString: dojo.cache("/Static/UserGuide/ContentEditorsUserManual.html")
});
});

The declare value also needs to exactly match the WidgetType definition.  It’s this key that makes the magic work.

The above code defines all the most basic requirements that an EPiServer widget needs.  Dojo supports several different methods for separating views.  The one we will use is the _TemplatedMixin.

In the templateString property, we define which view we want Episerver to render in the assets pane. Note the templateString defines the URL of the view we want to import.  If your view does not work, the Episerver editor will not render correctly.  When setting this up, I would first check that the view loads correctly for the url you are using and you can view it in a browser. If you can’t, the whole thing will break.

The other thing to note is the Url starts from the webroot.  In this example, I have referenced a file in a folder in Static -> User Guide.  This part can be tricky to get right.  If you get this file path wrong, the whole editor can break.  Debugging can also be annoying due to bowser caching.  On each page load it’s a good idea to clean your browser internet cache each time.  If you make changes to the js file and nothing happens, blame browser caching.

Creating Your HTML file

This is the last step. As mentioned in the last section you will need to create the following html file /Static/UserGuide/ContentEditorsUserManual.html.

ImportantIf you add the whole pages html mark-up within your view, the editor will break; in order for the view to render correctly it must be wrapped in two div tags only:

<div>
<h3>Content Editors User Manual</h3>
</div>

After you save html file, load the site up, log into the editor and as long as you copied everything correctly you should see a User Manual tab which displays the content defined in the html file in the right hand asset panel that contains text.

User_Manual_In_Assets+Pane

Displaying a view from a controller

We have displayed a static html file.. next let’s display a view from a controller.  There are two ways we can create views, using the standard MVC controller or the Episervers Controller.  I’m going to go with the Episerver one for simplicity.  First, we create a page type so we can create the page in the Episerver editor.

[ContentType(
DisplayName = "Custsom Page",
GUID = "9F2C5DD2-5B7E-45BA-AF70-677B3B131F4C",
Description = "Custsom Page",
GroupName = "Standard")]
public class CustomPage : GlobalBasePage
{
[Display(
Name = "Page Title",
Description = "Page Title",
GroupName = SystemTabNames.Content,
Order = 100)]
[CultureSpecific]
public virtual string PageTitle { get; set; }
}

Next, we create the controller.  Note how I’ve added the Authorize attribute to the controller.  This means only logged in episerver editors will be able to view the controller.

[Authorize(Roles = "WebEditors, WedAdmins, Administrators")]
public class CustomViewController : BasePageController<CustomPage>
{
public ActionResult Index()
{
return PartialView("~/Views/Widgets/CustomView/Index.cshtml");
}
}

The last part is defining the view, remember it has to be wrapped in two div’s:

<div>Custom View</div>

After you have created all the files in your webroot, go into the Episerver editor and create a page of type Custom Page and publish it.  On your website, load the page up and make a note of the URL. Next in our Dojo Dijit js file, point the templateString property to the custom pages url:

templateString: dojo.cache("/en/customview")

Rending_A_Controller_In_Assets_Pane

Caution If you link to a page in the editor and it gets deleted, the whole of the editor will break.  You will have to go into the code and comment out the widget if you want to get the site up and running again.

Conclusion

So, that wraps up how you can display custom views in the Episerver assets pane.  In the first example, we added a tab that could be used to display a user manual for content editors, for example. In here you could, say, add video’s, links to PDF’s etc..

In our second example, we used displayed dynamic content rendered via Episerver.  Adding in custom displays can make your content lives a lot easier.  From my experience with custom display widgets, is that they can be very tricky and finicky to get up and running.  If you deleted your page, for example, the whole of the editor breaks.  On a product site this is bad thing so be careful when you use it.

Working Code Example

All the above code can be downloaded in a fully working website from my github account here.

JonDJones.Com.CustomViewInAssetPanel

{

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

0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *