I just migrated a reasonably large project over to the latest Dojo release 0.4, and since i ran into a few basic gotchas i thought i would share some of the stuff i ran into here for you to compute.
If you have no idea what Dojo is and do no not usually slap Javascript with a large stick for fun and profit feel free to not read this post at all.
If you have been dutifully adapting your Javascript/Dojo code to be compatible with the nightlies you probably won’t run into any of these issues, if you (like me) were still stuck in 0.3.1 on the other hand you will probably run into these issues yourself.
The new namespace system
There used to be a time when you simply set your paths and required everthing you needed. 0.4 features autoloading though, which seems to lighten the load on my server so it’s heartily recommended. When you are running custom widgets you might need to make some adjustments though.
You used to be able to get away with lot’s of these:
dojo.require("acme.widget.MyWidget");
No more! You need to delete those require statements and instead add a manifest.js to the directory where your custom widget lives. This make my new setup look like this:
First we add the good old HTML to load the Dojo library in the head of my page. The reference to dojo.js loading the library, the post_dojo.js containing the bootstrap code to get up and running. Nothing has really changed here.
<script type="text/javascript" src="/js/dojo/dojo.js"></script>
<script type="text/javascript" src="/js/post_dojo.js"></script>
But the contents of post_dojo.js has changed; acme are directories containing my custom code which live next to the dojo directory in my js directory. Since registerModulePath() needs paths relative to dojo this becomes; ‘../acme’.
// load widget handler code
dojo.require("dojo.widget.*");
// Load user custom widgets
dojo.widget.manager.registerWidgetPackage('acme.widget');
dojo.registerModulePath('acme', '../acme');
So the above code will work for this directory structure:
{webroot}/js/dojo/dojo.js
{webroot}/js/dojo/{more dojo code here}
{webroot}/js/acme/
{webroot}/js/acme/widget/{my custom widgets here}
As you can see i am not requiring all the widgets i need from my acme directory like i used to in Dojo 0.3.1. Instead 0.4 offers autoloading which loads the widgets when they are encountered in the page or requested from code.
The new manifest.js file
For this to work dojo still needs to know what is available though. To achieve this you place a manifest.js file in your custom widget directory. In my case manifest.js contains the following code:
dojo.provide("acme.manifest");
dojo.registerNamespaceResolver("acme",
function(name){
var map = {
"mywidget": "MyWidget",
"myotherwidget": "MyOtherWidget"
}
return "acme.widget."+map[name];
}
);
As you can see i have to translate the request for a lowercase named widget to the uppercase name by which it is known in your code, as well as tell dojo in which directory or javascript file they live. If you keep all your widgets in one big file you resolver function could simply return the name of that file.
Calling widgets from HTML
Although Dojo makes it possible to create widgets from code i like to use the built-in functionality to create widgets from HTML. This way i can make a non-javascript version first and then simply ‘overlay’ this version with my javascript widgets thus making sure that non-javascript enabled browsers also receive a usable page. In Dojo 0.4 i would create a widget from HTML using the following code:
<input name="search" value="" dojoType="acme:autoComplete" acme:locale="nl-NL" />
The above code will load a widget called autoComplete in our custom acme namespace. Furthermore it will set a local variable in this widget called locale to the value; “nl-NL”. In Dojo 0.3.1 there was no need to include the namespace in the dojoType and locale attributes, in 0.4 there is.
sidenote: in 0.3.1 it was possible to load a widget from a class attribute by typing something like class=”dojo-autoComplete”. Sadly class=”acme-autoComplete” does not work so there is no good way to make your pages totally W3C validated for now. This will probably be resolved in the near future though.
Other Changes
Besides the new namespace structure you are bound to run into some deprecated methods. In my project i had rename references to the dojo.style.* package to dojo.html.* and dojo.html.style.*.
After that i had to remove a few remaining calls to this.extraArgs. In the code above for instance i used to be able to read out the value of my custom locale attribute by saying:
localVar = this.extraArgs.locale;
extraArgs does not exist anyomre so this simply becomes:
localVar = this.locale;
And that was it. About an hours work all in all and my complete project is now running 0.4. A noticably faster version of Dojo that adds a whole slew of bugfixes and interesting new functionality.