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.
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 React or Angular. Learning the in's and out's of an out-of-date 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
Create 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...
The code is very simple:
- Plug-in Area: 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
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.
Next, if you haven't got one already, you will need to create a modules.config in your webroot
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 thewebroot create the following folders:
ClientResources -> Scripts -> widgets -> jondjones
In this situation. the 'jondjones' is the second part of the namespace that we defined in the WidgetType.
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.
The declared 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.
The templateString defines the URL of the view we want to import. If your view does not work, the Episerver editor will not render it 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 browser 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. f 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:
After you save the 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 that displays the content defined in the HTML file in the right-hand asset panel that contains the text.
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 Episerver's 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.
Next, we create a 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.
The last part is defining the view, remember it has to be wrapped in two div's:
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:
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.
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 videos, 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 production site this is bad thing so be careful when you use it.
All the above code can be downloaded in a fully working website from my GitHub account here. #ILoveEpiserver