Since I’ll suddenly have copious free time on my hands once I turn in my final book manuscript this weekend, I decided that it might be helpful to start a short column on some of the fundamental Dojo building blocks. Although I certainly won’t be able to give this column the same “definitive guide” coverage that you’ll get in the book, my hope is to show you some tools that will increase your Dojo awareness and get you excited about some of the things that Dojo can do for you.

To kick off this series, let’s start out with a few entries on Base, the highly optimized kernel of the toolkit that I like to think of as the JavaScript standard library that you shouldn’t be missing out on. In a nutshell, Base provides a swath of language utilities for lots of those “things you wish you didn’t have to write yourself” that tend to junk up your code. You know, things like styling nodes, adding and removing classes, querying the DOM, manipulating scope, simple animations like fades, standardizing the event model, and the list could just go on and on ad infinitum (almost.)

AOL serves Dojo over their Content Delivery Network (CDN), and Base comes “across the wire” (gzipped) at about 27KB, so right away, let’s get rid of the blanket statement that Dojo is bloated. A payload of 27KB is smaller than most Flash-based advertisements you’ll find inundating the web and is a quick download even over the slowest of connections. AOL’s CDN is a geographically edge-cached system, so you won’t be waiting very long for the page to load either.

But enough of this jibber-jabber. Let’s get to looking at some code that can actually do you some good. Here’s the basic template that loads Base into the page:


<html>
    <head>
        <title>Dojo Goodness, Part 1 </title>

        <script type="text/javascript"
            src="http://o.aolcdn.com/dojo/1.0/dojo/dojo.xd.js">
        </script>

        <script type="text/javascript">
            dojo.addOnLoad(function() {
                /* Do stuff... */
            });
        </script>
    </head>
    <body>
        <a href="http://dojotoolkit.org">Dojo</a>
    </body>
</html>

As you can see, there’ nothing to it except including a SCRIPT tag that loads all of the Dojo goodness into the page. The dojo.addOnLoad block provides a safe place to actually start using Dojo, which is necessary since the SCRIPT tag is satisfied asynchronously. This is similar to other constructs such as jQuery’s ready event.

So, let’s actually do something.

One of the most commonly used features of Dojo is the dojo.query function–basically, it accepts a CSS selector as its first argument, queries the DOM and returns back a NodeList of whatever it found that matched the selector criteria. A NodeList is a subclass of Array, provided as part of Base, that provides syntactic sugar for chaining together operations. The official API call for dojo.query is here.

Let’s assume that you want to make something happen someone clicks on the link–perhaps trigger an alert that bids you farewell before leaving the page. Here’s what you’d do:


//put this code inside of the dojo.addOnLoad block
dojo.query("a").onclick(function(evt) {
    alert("Thanks for visiting");
});

To deconstruct that blurb a bit, the dojo.query function uses the CSS selector provided, which says to find all of the anchor elements in the page (there is one of them in this case), and then these results get operated on via NodeList’s onclick method, which assigns a custom handler to each of them. The function triggers an annoying popup that appears before you leave the page, and that’s the end of it.

What’s you may not have known, however, is that the evt argument that gets passed into that custom function is standardized according to the W3C spec, so you can count on it working across platforms without issue. For example, to prevent the default action of leaving the page when you click on the link, you could call preventDefault on it like so:


//put this code inside of the dojo.addOnLoad block
dojo.query("a").onclick(function(evt) {
    alert("Thanks for visiting");
    evt.preventDefault(); // now the page doesn't reload when you click
});

But that’s not all. NodeList also packs a lot of other really useful functions for DOM events as well as things like indexing into the NodeList, manipulating classes, slicing into the NodeList, and more–all of the things you would probably expect to be in there. You can read its complete API here.

Let’s finish off this segment with a small extension to our working example that highlights the link when you hover over it. Here’s the update:


//put this code inside of the dojo.addOnLoad block
dojo.query("a")
.onclick(function(evt) {
    alert("Thanks for visiting");

    // comment out if you really do want to leave the page
    evt.preventDefault();
})
.onmouseover(function(evt) {
    dojo.style(evt.target, "background", "yellow");
})
.onmouseout(function(evt) {
    dojo.style(evt.target, "background", "");
});

As you can see, chaining together results is just as intuitive as what you’d probably expect, and the only new construct introduced is the fairly self-descriptive dojo.style function. Basically, dojo.style accepts three parameters: a node (which in accordance with the W3C spec, you can get at via evt.target), a style name, and a value for that style. In this case, we merely add a yellow background when the mouse moves over the node and remove it when the mouse moves out. The API call for dojo.style is here.

What would you like to see in future columns? I’d like to do a few more on some of the Base essentials, but I also understand that lots of folks might want to see some of the stock widgets in action. Feel free to leave your requests below.