Mostly Harmless

Dojo comes with a great set of widgets, but is it often necessary to create custom widgets for application specific needs. In this tutorial, I will walk through an example of such a custom widget. The custom widget resides on my own server, while rest of the Dojo (and dijit) is used from AOL CDN hosted xdomain build. Live demo of the widget is also available. This custom widget is built on Dojo 1.0.2 and works great on Firefox 2, Konqueror 3.5.1, IE 6 and IE 7.

We will create a new widget named blogscope.TestWidget which extends the dijit.TitlePane. Looking at the TitlePane code, one can see the empty function onDownloadEnd which is called when the widget finishes downloading content from an external url. For the custom widget, we will extend the TitlePane by filling in this function with a simple alert() statement.

First, we will use dojo.declare to extend the dijit widget to create the new custom widget. I will omit the details of this part, but you can find examples elsewhere.

dojo.provide("blogscope.TestWidget");
dojo.require("dijit.TitlePane");
dojo.declare(
"blogscope.TestWidget",
[dijit.TitlePane],
{
 onDownloadEnd: function(currentConent){
  // summary:
  //  called when download is finished
  alert('Contents Loaded from '+this.href);
 }
}

If you are not using AOL CDN, then simply put the code above in file TestWidget.js. Place this file in directory blogscope such that the dojo path is /js/dojo/ and this widget file is in /js/blogscope/TestWidget.js. Then you can register the widget as dojo.registerModulePath("blogscope", "../blogscope") (the directory name containing the custom widget is relative to the Dojo directory) and use dojo.require("blogscope.TestWidget") in your code. The name of the widget has to be the same as the name of the file containing the code.

Since we wish the xdomain build of Dojo, we need to do some more work. First, the custom widget source code has to be in file TestWidget.xd.js and not TestWidget.js. For the cross-domain build we need to add some more information as to what this module is providing and what all modules it depends on so that Dojo loading system can make sure that the dependencies are met. The contents of this file are as shown below.

dojo._xdResourceLoaded({
depends: [["provide", "blogscope.TestWidget"],
["require", "dijit.TitlePane"]],
defineResource: function(dojo){
 if(!dojo._hasResource["blogscope.TestWidget"]){ 
  dojo._hasResource["blogscope.TestWidget"] = true;
  dojo.provide("blogscope.TestWidget");
  dojo.require("dijit.TitlePane");
  dojo.declare(
  "blogscope.TestWidget",
  [dijit.TitlePane],
  {
   onDownloadEnd: function(currentConent){
    // summary:
    //  called when download is finished
    alert('Contents Loaded from '+this.href);
   }
  }
 );
 }
}});

Note: Ideally, one should use the dojo build system to generate .xd.js files from .js code. But I don't know how to use the build system, so I created the file manually. The main drawback of manual authoring is that the format of .xd.js files may change with version (it is already different for Dojo version 1.1).

Copy the file TestWidget.xd.js on the server such that it is available at say http://www.blogscope.net/js/dojo/blogscope/TestWidget.xd.js. Modify the djConfig variable to set module path as shown below.

<script type="text/javascript"
  djConfig="isDebug: true, parseOnLoad: true, useXDomain: true, modulePaths: {'blogscope': 'http://www.blogscope.net/js/dojo/blogscope'}"
  src="http://o.aolcdn.com/dojo/1.0.2/dojo/dojo.xd.js"></script>
 <script type='text/javascript'>
 dojo.require("blogscope.TestWidget");
 dojo.require("dojo.parser");
 </script>

Since, the module name blogscope is registered to path http://www.blogscope.net/js/dojo/blogscope, dojo.require() adds the a link to http://www.blogscope.net/js/dojo/blogscope/TestWidget.xd.js which can be seen using Firebug.

The widget is now ready to use using the following HTML.

<div dojoType="blogscope.TestWidget" open="false" title="Click to Expand the Widget" href="ajaxContents.html">
</div>

Also See

• Cross Domain Resource Loading in Dojo 0.4.2+ and 0.9
• Timing Issue when loading from CDN