October 2008 Archives

Using the Dojo loader to include your own JavaScript module is very handy, and also works around several problems related to loading JavaScript code directly via the <script> tag. Often, however, you want to be able to load your modules across domains, so you need to write them in xd fashion. In itself, it's not a big issue as, with Dojo 1.2.0, a non-xd code such as this:

(function(){
    dojo.provide("cryo.Tree");
    dojo.provide("cryo.ForestStoreModel");

    dojo.require("dijit.Tree");
    
    dojo.declare("cryo.ForestStoreModel", dijit.tree.ForestStoreModel, {
        // class definition
    });

    dojo.declare("cryo.Tree", dijit.Tree, {
        // class definition
    });
})();

just needs to become as follows to work with the Dojo cross-domain loader:

dojo._xdResourceLoaded(function(){ return {
    depends: [
        ["provide", "cryo.Tree"],
        ["provide", "cryo.ForestStoreModel"],
        ["require", "dijit.Tree"]
    ],
    defineResource: function(dojo) {
    
    dojo.provide("cryo.Tree");
    dojo.provide("cryo.ForestStoreModel");

    dojo.require("dijit.Tree");
    dojo.declare("cryo.ForestStoreModel", dijit.tree.ForestStoreModel, {
        // class definition
    });

    dojo.declare("cryo.Tree", dijit.Tree, {
        // class definition
    });
})();

Easy enough, but what usually happens is that you work with non-xd files while developing, while using the cross-domain features in production. Or maybe the opposite. Or something similar. Anyhow, in this case you most likely don't want to maintain two copies of the same JavaScript module where only header and footer are different. For sure I don't, so I wrote a small Perl script which converts non-xd modules to xd-enabled ones automatically by performing the following tasks:

• It parses dojo.require and dojo.provide statements in order to create the xd header.
• It substitutes the header with an xd one containing the information obtained in the parsing operation.
• It substitutes the closing parentheses with others which match the new header.

OK, I know, there's also the Dojo Build System, but I didn't want to install Ant and a ton of Java-related dependencies for a task which requires 20 lines of code.

This script is a quick hack so it has caveats:

• It's a quickly (and therefore poorly) coded dirty hack.
• Read the code before using it and edit it if needed.
• It's supposed to work if the code is formatted a bit differently than the examples above, but there's no guarantee - I just tried out some variations.
• It produces xd code only suitable for Dojo 1.2.0 (but changing it for 1.1.1 is trivial)

On the other hand, using it makes no harm to your existing code: it will either work and produce (possibly broken) output files, or produce no files at all. So, I would say it is safe to try it.

Usage:

make_xd.pl file1.js file2.js ... filen.js

You can pass one or more files on the command line: the script will produce filename.xd.js starting from filename.js, which is left untouched.

Click here to download the script.

If you improve this script, please let me know.

Mastering Dojo
Rawld Fill, Craig Riecke, Alex Russell
Pragmatic Bookshelf, 2008
ISBN: 978-1-934356-11-1
US$ 38.95

Rating: 4/5 (very good)

The Dojo toolkit is, arguably, the most advanced JavaScript framework available today. jQuery might be designed equally well and be more compact, but it lacks advanced and ready to use GUI components. Ext JS might provide a ton of colourful widgets, but it lacks the implementation and API elegance of Dojo, not to mention it features a licensing system which is awkward enough to turn away any sane open source developer.

Dojo still has, however, one major drawback: the documentation is sparse at best, and completely missing in some areas. The API reference is not rich enough, and parts of the online free Dojo Book are outdated; the best option for programmers is often to skim directly through the well-commented source code and through the accurately done test suites. Dojo is a big and complex project, so it will take a while for the community to document it properly; in the meanwhile, the excellent forums, Dojo Campus and the IRC channel provide an excellent resource. Printed books also come to the rescue of programmers who want to use Dojo: being the project so interesting, there are quite a lot of titles available, and Mastering Dojo ranks among the most up-to-date and interesting ones.

Despite its name, this book is targeted to the programmer who doesn't yet use Dojo, as opposed to the Dojo programmer who wants to dig more deeply into the framework details. It, however, spans a wide range of Dojo-related topics: from the basics to the most advanced widgets (trees, grids) and other areas (internationalisation, extension of the framework). Basically, you just need to know JavaScript to read this book: even though Dojo also features an HTML declarative syntax, to obtain something useful out of the framework you really need to be comfortable with JavaScript.

Every chapter is devoted to a topic, and is made of an introduction followed by well-made examples. It doesn't provide a reference: you learn the main things, and then if you want to know all the API you'll want to find more documentation elsewhere. What it provides is however what you need if you're new to Dojo: a description of what you can do and some examples on how to do it - so that basically you understand that you'll be able to use Dojo to create a modern web application in and easy (although, as all computer programming tasks, not always straightforward) way.

Even though absolutely not a reference, Mastering Dojo can be used as such to some extent: the sections about events, DOM introspection and editing, classes and data are, for instance, enough in-depth to provide reference for most of the tasks a developer needs to perform. Others, such as the Grid and the Tree, are more like introductions to those advanced widgets, but are nevertheless very appreciated as it's not easy (if at all possible) to find coherent documentation elsewhere regarding them.

All in all, if you plan to use Dojo because to have to create a serious web application, this book is an excellent starting point, and will likely remain useful also when your knowledge of the framework has grown.