Create your own dojo widgets module

There are already some really nice articles on how to create dojo widgets. The one I like most at the moment is Develop HTML widgets with Dojo.

After having gone through some of these dojo tutorials I was so enthusiastic about dojo's widget system that I wanted to create my own ones. But what really annoyed me was that most of these tutorials explained widget development by putting them into dojo's widget folder itself and thus merged the original distribution with my own stuff. I think that this is fine for an introduction. But to start my own widgets I wanted to have them separate from dojo's distribution. Imagine a new version of dojo comes along and I have to figure out which are dojo's and which are my files in order to make the upgrade.

So I decided to take the time and find out how my widgets could be separated from the dojo distribution. It took me a couple of hours of trial and error and changes in the new version (0.4.0) seem to have made it a bit difficult since some hints on webpages I found did not seem to be valid anymore.

Anyway it was worth it and since I could not find a description on the topic elsewhere I thought it would make sense to write down what I did since it might be useful for others as well. If you want to you can leave a comment on my jroller page here.

Folder structure

So first let me show you how I setup my folder structure. I decided to have a folder called lib into which I wanted to put all library stuff in like dojo, my own dojo stuff (which I called dojox) and other things like scoop for example. Each of these things should have it's own folder so that I ended up with somethings like this:

I downloaded dojo-0.4.0-ajax.zip unpacked it, renamed it to dojo-0.4.0 and put it into lib.

In parallel to lib I wanted to have all my different projecs making use of the stuff in lib. In the picture only the project tutorial is shown. Tutorial is used as an example project for this article which is like the example in the already mentioned Develop HTML widgets with Dojo Tutorial with the difference that the described HelloWorld widget will be outside the dojo distribution (if you haven't looked at that tutorial I can only recommend to do so). Translated to my directory structure this means the HelloWorld files will not go into lib/dojo-0.4.0 but instead into lib/dojox. This will make it possible in case a new dojo version comes along to simply switch to the new version and my own widgets should still be OK.

Setup your own HelloWorld widget

Next I set up the folder structure of lib/dojox as follows:

Into the folder dojox I put a file named __package__.js with the following content:

dojo.provide("dojox.*");

Into the folder dojox/widget I put another file named __package__.js with the following content:

dojo.provide("dojox.widget.*");

Into the folder dojox/widget also goes the first file for my hello world widget: HelloWorld.js with the following content:

dojo.provide("dojox.widget.HelloWorld");
dojo.require("dojo.widget.HtmlWidget");

dojo.widget.defineWidget("dojox.widget.HelloWorld", dojo.widget.HtmlWidget,
  {
    widgetType: "HelloWorld",

    templatePath: dojo.uri.moduleUri("dojox", "widget/templates/HtmlHelloWorld.html"),
    templateCssPath: dojo.uri.moduleUri("dojox", "widget/templates/HtmlHelloWorld.css"),

    // Widget attributes:
    text: "???",
    
    // dynamic setters:
    setHtml: function(aHtmlString)
    {
        this.domNode.innerHTML = aHtmlString;
    },
    onClickHander: function(evt)
    {
      alert("Node clicked");
    },
  });

The important difference to the original example here is the use of the moduleUri function which constructs a URI in relation to our new dojo module dojox. I will soon show you how to tell dojo about it's existence.

Into the folder dojox/widget/templates I put HtmlHelloWorld.css with the following content:

.helloWorld_caption {
  font-family: Verdana;
  font-size: 10pt;}

and HtmlHelloWorld.html with the following content:

<div class="helloWorld_caption" dojoAttachPoint="domNode" dojoAttachEvent="onClick: onClickHander;">
  ${this.text}
</div>

At this point the separate dojo module is setup and includes the HelloWorld widget. Let us look at how to use it.

Use our widget

Into the folder tutorial I put dojox_widgets_example.html with the following content:

<html>
  <head>
    <title>Example</title>
    <script type="text/javascript">
      djConfig = { isDebug: true };
    </script>
    <script type="text/javascript" src="../lib/dojo-0.4.0/dojo.js"></script>
    <script type="text/javascript">
      dojo.registerModulePath("dojox", "../dojox");
      
      dojo.require("dojo.widget.*");
      dojo.require("dojox.*");
      dojo.require("dojox.widget.HelloWorld");    
    </script>
  </head>

  <body>
  <div dojoType="dojox:HelloWorld" text="hello world from Sven"></div>
  </body>
</html>

The important part here is dojo.registerModulePath("dojox", "../dojox"); which registers a new module called 'dojox'. The second argument of the function call is the module's path relative to the dojo folder (the folder which contains dojo.js).

That's it! For your convenience I put together a zip file (without the dojo distribution) to make the start for you as easy as possible.