5 things to know about Dojo
This blog post is part 2 of “Learn how to develop your own Dojo widget”. If you haven’t read part 1, I recommend you to read it. You may find it here.
In part 1 I promised to write 10 tips, it ended up being 5. I hope you can forgive me.
1. Including modules – define
When looking at Dojo you will find a lot of definitions at the top. Dojo is separated into several small modules, which means that you only add the parts you are going to use. This is very nice since you only add the once you actually need. On the other hand, it is a bit annoying since you have to keep track of several modules.
EPiServer has built some modules of their own. To be honest I do not have a complete overview of all of them, but they are documented here http://world.episerver.com/documentation/Javascript-Library/?version=9&product=cms
After the definitions there is a list of function names which is the name you give the added modules. Through these function names you may use the modules in your javascript code.
define([
"dojo/_base/array",
"dojo/on",
"dojo/_base/declare",
"dojo/_base/lang",
"dijit/_CssStateMixin",
"dijit/_Widget",
"dijit/_TemplatedMixin",
"dijit/_WidgetsInTemplateMixin",
"dijit/form/Textarea",
"epi/epi",
"epi/shell/widget/_ValueRequiredMixin"
], function (
array,
on,
declare,
lang,
_CssStateMixin,
_Widget,
_TemplatedMixin,
_WidgetsInTemplateMixin,
Textarea,
epi,
_ValueRequiredMixin
) {
2. templateString
This is the HTML representing your widget. Say, if you want to create an input text field, this is where you put your HTML. The important thing to know is that instead of using IDs or class names to handle your HTML in the JavaScript you should/must use data-dojo-attach-point. This way Dojo will create a reference to it and it will be available through the widget as this.attach-point-name.
Example templateString:
'<div class="dijitInline">\
<div data-dojo-attach-point="textArea" data-dojo-type="dijit.form.Textarea"></div>\
</div>' Notice the data-dojo-type in the example above. Dojo creates new elements based on the Dojo-type. In our case it will create a textarea since we are using the dijit.form.Textarea.
3. startup and postCreate
PostCreate is a built-in Dojo method which runs after all the properties are set up, but it runs before the templateString is added to the DOM. It is a method where you may start/initialize other methods.
Startup is also a built-in Dojo method, but runs after postCreate and after the templateString is added to the DOM. This is where you may add bindings or any other needed setups.
4. Saving changes
When the editor is done, you want to save the data that is changed or added. There are mainly two methods you want to run doing that, this.onChange and this. set.
this._set sets the value to the widget and notify any observers.
this.onChange is for letting the widget wrapper updating the UI when the value is changed.
The exampe below is taken from the other blog post, part 1. It uses both this_set and this.onChange when saving changes.
_setValue: function (value, updateTextarea) {
//avoids running this if the widget already is started
if (this._started && epi.areEqual(this.value, value)) {
return;
}
this._set("value", value);
// set value to textarea
updateTextarea && this.textArea.set("value", value);
if (this._started && this.validate()) {
// Trigger change event
this.onChange(value);
}
},
5. Connect vs on
The built-in methods for binding events, connect and on, is two methods for the same thing. I've noticed that connect is used in several EPiServer Dojo examples. According to the Dojo Documentation connect is deprecated. Based on that we should use the dojo/on module to bind events instead.
this.connect(this.textArea, "onChange", this._onTextAreaChanged);
on(this.textArea, "change", lang.hitch(this, this._onTextAreaChanged));
Nice write up, thanks for sharing!