Dummy’s Guide To Creating A Custom Dojo EPiServer Property

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 idiot’s guide (it’s the only way I learn) 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 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 🙂

Modules.config

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.

<?xml version="1.0" encoding="utf-8" ?>
<module>
<assemblies>
<add assembly="JonDJones.Com" />
</assemblies>
<dojoModules>
<add name="jondjones" path="Scripts" />
</dojoModules>
</module>

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

Custom_Dojo_Property_Assembly_Name

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. SO in this example scripts will look like this in our project directory:

Custom_Dojo_Property_Scripts_Folder

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.

Custom_Dojo_Property_Dojo_Location

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

define([
"dojo/_base/declare",
"dijit/_Widget",
"dijit/_TemplatedMixin",
'dojo/text!./templates/DojoProperty.html',
],
function (
declare,
_Widget,
_TemplatedMixin,
template
) {
return declare("jondjones.CustomProperty.DojoProperty", [
_Widget,
_TemplatedMixin], {
templateString: template
}
);
});

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.

Custom_Dojo_Property_view_location

Our view will then looks like this

<div>This is an html file</div>

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

[EditorDescriptorRegistration(
TargetType = typeof(String),
UIHint = "CustomProperty")]
public class DojoPropertyDescriptor : EditorDescriptor
{
public DojoPropertyDescriptor()
{
ClientEditingClass = "jondjones.CustomProperty.DojoProperty";
}
}

Create a .net class in your solution called DojoPropertyDescriptor and copy the following. The important thing in 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..

[Display(
Name = "Main Title",
Description = "Main Title",
GroupName = SystemTabNames.Content,
Order = 200)]
[UIHint("CustomProperty")]
public virtual string MainTitle { get; set; }

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.

<h1>@Html.PropertyFor(m => m.CurrentPage.MainTitle)</h1>

The final result should now look like this:

Custom_Dojo_Property

Conclusion

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.

Code Sample

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

JonDJones.com.EPiServerCustomDojoWidget

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

1 reply

Trackbacks & Pingbacks

  1. […] .If you want to know how to attach a front-end display in the EpiServer editor, then I would recommend  having a look at, Dummy’s Guide To Creating A Custom Dojo EPiServer Property […]

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 *