Dojo is a bit of an evil word around most of the Episerver teams I've encountered, but, with a bit of persistence, you can write your own custom properties and introduce other cool and funky editor functionality.

This tutorial will give you a step-by-step guide on how to create a dojo property that works via HTML files and attach it to a property. Most of the tutorials I've found on the subject seem to assume you have some competence doing this.. so hopefully, this will stop you from having some of the same pains as I did. Oh.. if this still doesn't make sense then there's a fully working code sample included too :)


When we work with Episerver and dojo you will need to know about modules.config. The modules.config is the area in your website that defines your dojo properties and general stuff to customise the Episerver UI.

The first thing you need to do is define your assembly section, this value matches the assembly name in my project.


The dojo module section points to the folder that will contain our dojo stuff. Important all these folders will live within the ClientResources folder. You can't change this. In this example scripts will look like this in our project directory:


In case you're wondering, 'jondjones' is an arbitrary namespace name I've created, it doesn't need to match your solutions name or anything like that. This namespace can be anything you want, but it will have to match the namespaces in your modules. I'll cover this later but by making a typo in here the editor will throw a 404 against your dojo definition js file when it tries to load your property.

Creating Your Dojo files

Within your scripts folder, you need to create your dojo file. For this tutorial I have created a folder called CustomProperty.


In here I'm going to create my dojo file called, DojoProperty.js, that will look like this:

This is the very bare-bones structure you need to get a dojo property to work. The defined property lists the dependencies and properties that will be passed into the function. Notice the line 'dojo/text!./templates/DojoProperty.html' and how it maps to the variable template.

This is the line that points out custom property to the html file that will be used to render itself. In the declare part, we specify the dojo widgets namespace "jondjones.CustomProperty.DojoProperty". Remember how we set-up the scripts folder above? The name we used 'jondjones' must match the first part of this namespace, otherwise EPiServer will not be able to find the file. The second part 'CustomProperty' matches the folder name under scripts. The last part 'DojoProperty' matches the filename without the file extension. Within the declare, we also set the templateString to equal our template property. This is the part that tells Episerver where to find the view associated to this property.

Dojo View

We defined the location of the properties view in 'dojo/text!./templates/DojoProperty.html'. This path is related to the files location, so we need to define a folder called templates with a DojoProperty.html file.


Our view will then looks like this

This is an html file

For this demo I'm sticking to some basic text but in your controls I'm sure things will be a lot more complex. The things to note is that you have to wrap everything within a div tag. If you forget to wrap everything around a div then your control will not render correctly. That's all the configuration that is needed from the Javascript side of things. The next part is getting back to C♯ and creating an EditorDescriptor.

Editor Descriptor

Create a .net class in your solution called DojoPropertyDescriptor and copy the following. The important thing here is the UiHint. This is the thing that will register a property to use our dojo widget. The other thing is the ClientEditingClass; this needs to match the namespace we defined in the declare method in the dojo code.

Adding the property to a page

Registering a page to use the dojo property is the same as any other call. You set a UiHint on it..

To display your dojo widget in your pages or blocks view, you simply call the PropertyFor on the defined property and it should display. Note, you have to use PropertyFor and not just call it via the model otherwise the dojo widget won't trigger.

The final result should now look like this:



In this tutorial, we've gone step-by-step of everything you need to do to register and create a custom dojo property. The example we've used was very basic but sometimes just getting something working can be one of the trickiest parts of getting your head around the dojo. side of things.

First, we created a modules.config file and registered the web projects assembly and the Scripts location relevant to the namespace we used (the namespace can be anything) We then created a dojo javascript file and view, implementing the bare bones to get dojo working with a custom HTML file.

Lastly, we created an Episerver editor descriptor in .Net that registered the dojo widget in Episerver. We then decorated a property with a UiHint that matched the UiHint defined in the editor descriptor and used the PropertyFor MVC extension to render out the properties custom view.

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