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.
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
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.
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