All Dijits can be subclassed to change parts of their behavior, and then used as the original Dijits, or you can create your own Dijits from scratch and include existing Dijits (Forms, buttons, calendars, and so on) in a hierarchical manner.
All Dijits can be created in either of the following two ways:
- Using the dojoType markup property inside selected tags in the HTML page.
- Programmatic creation inside any JavaScript.
For instance, if you want to have a ColorPalette in your page, you can write the following:
<div dojoType="dijit.ColorPalette"></div>
But you also need to load the required Dojo packages, which consist of the ColorPalette and any other things it needs. This is generally done in a script statement in the <head> part of the HTML page, along with any CSS resources and the djConfig declaration. So a complete example would look like this:
<html>
<head>
<title>ColorPalette</title>
<style>
@import "dojo-1.1b1/dojo/resources/dojo.css";
@import "dojo-1.1b1/dijit/themes/tundra/tundra.css";
</style>
<script type="text/javascript">
djConfig=
{
parseOnLoad: true
}
</script>
<script type="text/javascript" src="dojo-1.1b1/dojo/dojo.js"></script>
<script type="text/javascript">
dojo.require("dojo.parser");
dojo.require("dijit.ColorPalette");
</script>
</head>
<body class=”tundra”>
<div dojoType="dijit.ColorPalette"></div>
</body>
</html>
Obviously, this shows a simple color palette, which can be told to call a function when a choice has been made. But if we start from the top, I’ve chosen to include two CSS files in the <style> tag.
The first one, dojo.css, is a reset.css, which gives lists, table elements, and various other things their defaults. The file itself is quite small and well commented.
The second file is called tundra.css and is a wrapper around lots of other stylesheets; some are generic for the theme it represents, but most are specific for widgets or widget families.
The two ways to create Dijits
So putting a Dojo widget in your page is very simple. If you would want the ColorPalette dynamically in a script instead, remove the highlighted line just before the closing body tag and instead write the following:
<script>
new dijit.ColorPalette({}, dojo.byId('myPalette'));
</script>
This seems fairly easy, but what’s up with the empty object literal ( {} ) as the first argument? Well, as some Dijits take few arguments and others more, all arguments to a Dijit get stuffed into the first argument and the others, the last argument is (if needed) the DOM node which the Dijit shall replace with its own content somewhere in the page.
The default is, for all Dijits, that if we only give one argument to the constructor, this will be taken as the DOM node where the Dijit is to be created.
Let’s see how to create a more complex Dijit in our page, a NumberSpinner. This will create a NumberSpinner that is set at the value ‘200’ and which has ‘500’ as a maximum, showing no decimals. To create this NumberSpinner dynamically, we would write the following:
<input type="text" name="date1" value="2008-12-30" dojoType="dijit.form.DateTextBox"/>
One rather peculiar feature of markup-instantiation of Dijits is that you can use almost any kind of tag for the Dijit.
The Dijit will replace the element with its own template when it is initialized. Certain Dijits work in a more complicated fashion and do not replace child nodes of the element where they’re defined, but wrap them instead.
However, each Dijit has support for template HTML which will be inserted, with variable substitutions whenever that Dijit is put in the page. This is a very powerful feature, since when you start creating your own widgets, you will have an excellent system in place already which constrains where things will be put and how they are called.
This means that when you finish your super-complicated graph drawing widget and your client or boss wants three more just like it on the same page, you just slap up three more tags which have the dojoType defining your widget.
How do I find my widget?
You already know that you can use dojo.byId(‘foo’) as a shorter version of document.getElementById(‘foo’). If you still think that dojo.byId is too long, you can create a shorthand function like this:
var $ = dojo.byId;
And then use $(‘foo’) instead of dojo.byId for simple DOM node lookup.
But Dijits also seem to have an id. Are those the same as the ids of the DOM node they reside in or what? Well, the answer is both yes and no.
All created Dijit widgets have a unique id. That id can be the same string as the id that defines the DOM node where they’re created, but it doesn’t have to be.
Suppose that you create a Dijit like this:
<div id='foo' dojoType='dijit._Calendar'></div>
The created Dijit will have the same Dijit id as the id of the DOM node it was created in, because no others were given. But can you define another id for the widget than for its DOM node? Sure thing. There’s a magic attribute called widgetId. So we could do the following:
<div id='foo' dojoType='dijit._Calendar' widgetId='bar'></div>
This would give the widget the id of ‘bar’.
But, really, what is the point? Why would we care the widget / Dijit has some kind of obscure id? All we really need is the DOM node, right? Not at all. Sure, you might want to reach out and do bad things to the DOM node of a widget, but that object will not be the widget and have none of its functions.
If you want to grab hold of a widget instance after it is created, you need to know its widget id, so you can call the functions defined in the widget. So it’s almost its entire reason to exist!
So how do I get hold of a widget obejct now that I have its id? By using dijit.byId(). These two functions look pretty similar, so here is a clear and easy to find (when browsing the book) explanation:
- dojo.byId(): Returns the DOM node for the given id.
- dijit.byId(): Returns the widget object for the given widget id.
Just one more thing. What happens if we create a widget and don’t give either a DOM or widget id? Does the created widget still get an id? How do we get at it?
Yes, the widget will get a generated id, if we write the following:
<div dojoType='dijit._Calendar'></div>
The widget will get a widget id like this: dijit__Calendar_0. The id will be the string of the file or namespace path down to the .js file which declares the widget, with / exchanged to _, and with a static widget counter attached to the end.
