Here are all of the functions and constructors in Dojo except for the widgets. Some developers are using Dojo only to get access to the many visually stunning and highly functional GUI widgets that it provides, so they may be surprised that there is an entire hidden underworld in Dojo consisting of many functions to make JavaScript coding easier but that don’t require GUI widgets at all. This directory is where all that under-the-hood plumbing code resides.

Here are the Dojo widgets. Why didn’t the creators of Dojo just combine this with the “dojo” directory? Actually, that is how early versions of Dojo were packaged. But by separating out the widgets from the rest of the Dojo code, it made Dojo more organized. And even more importantly, it makes it easier for developers to use just the parts of Dojo they need.

These are the extended features of Dojo that, for one reason or another, are not considered ready to be included in “dojo” or “dijit” yet. The reasons for exclusion. The functions may not be robust enough. They may not be fully internationalized yet, or maybe they won’t be used by enough developers to justify taking up space in the main “dojo” directory. Then why include them at all? Well, for those developers who do need them, the functionality is very powerful and useful. Over time, functions in “dojox” may migrate into “dojo” or “digit.”

These are files needed to perform unit testing on the Dojo functions during development. You can also use these features to run unit testing for code that you develop. Nothing in this directory is needed for an application that is in production.

This module consists of a number of general functions used in many different contexts. The module name stands for “language” and is similar in purpose to the “java.lang” package that may be familiar to Java programmers. Think of them as foundational functions that can be used by other Dojo functions (and available to you in your custom JavaScript, of course).

This module consists of a single function, dojo.declare, which is used to create constructors used to build new objects. This is an extremely useful function but sometimes difficult to understand if you are new to Object Oriented Programming (OOP). That is why an entire chapter has been devoted to its use. For an in-depth discussion of OOP and the dojo.declare function, see Chapter 12, “Objects and Classes.”

This module consists of functions that associate event handlers with events. Event handlers are simply functions that are called automatically when an event is triggered. The browser itself monitors the actions of the user to detect events. Almost anything the user does with the keyboard or mouse triggers an event that some event handler can be associated with. For instance, when the user places the cursor over a DOM element, an onmouseover event is triggered for that element. An event will only call the event handler if it has been associated with the event—otherwise nothing happens. For more on event handlers see Chapter 14, “Events and Event Handling.”

The following table describes functions in the dojo.connect module. As a convenience to allow shorter function names, it is not necessary to specify the module name.

This module consists of a single function, dojo.Deferred, which is used to provide communication between threads. “Threads!?” you might say. “But I thought that browsers don’t support threading.” And you would be right—except for the XMLHttpRequest object, which does run in its own separate thread. This function provides a generic technique for thread notification. And though we don’t quite have one yet, we’re just starting to hear about the beginnings of a threading model within JavaScript. So this function will have some special use now and possibly more use in the future as the threading model evolves. We cover this topic more thoroughly in Chapter 17, “Testing and Debugging.”

This module contains functions for working with JavaScript Object Notation (JSON), a text-based protocol for representing objects. It is quite popular in the JavaScript community as a replacement for XML. Table 11.3 summarizes the JSON functions, but we also cover them in more detail in Chapter 13, “Strings and JSON.”

This module consists of functions that make it easier to work with array objects and other objects that have array-like features. Among other things, the functions provide the capability to easily iterate (loop) through all the elements in an array or iterate just through certain elements.

This module consists of functions that allow a developer to represent colors (used internally by Dojo to perform color transitions).

The way that events are handled differs between browsers. The functions in this module provide a consistent behavior for events and event handlers. Events and event handling are covered in much more detail in Chapter 14.

This module consists of functions that can manipulate HTML and DOM objects. To understand how these functions work, you need to understand something called the “box model,” which describes the components of a DOM element. For illustrative purposes, Figure 11.4 provides a reproduced a diagram showing the box model from the W3C specification.^[3]

Figure 11.4. CSS box model

Some of the functions in this module allow a developer to access or set “box model” properties for a DOM element.

This module consists of functions for working with a list of DOM elements. A NodeList is a subclass of Array and extends Array to include a plethora of additional handy functions that perform useful manipulations on DOM elements such as chaining, common iteration operations, animation, and node manipulation. Many of the methods in NodeList are versions of methods from the array and html modules, given that a NodeList is really just an array of DOM elements.

The NodeList functions operate a little differently than most other Dojo functions. Most Dojo functions take the object that they operate upon as an argument. Nodelist functions work on the object they are part of. To use these functions you must first create a new NodeList (or get one back from a function) and then run the functions as methods on that object. For example, if you wanted to perform some function on a DOM element with an id of tree, you would use the following code:

     el = new dojo.NodeList(dojo.byId("tree"));
     el.forEach(function() { // some code; });

Notice how the forEach method is run on el. The el object is not passed as a parameter to forEach. Also the given NodeList only contains a single element even if the DOM element tree has multiple children.

As a convenience, shortcut functions on NodeList provide features that are available on DOM elements directly. By having the functions also appear on a NodeList, your code can be smaller and more readable.

Some of the NodeList functions are rather complex, and the brief description next may seem inadequate. That is why a number of these functions get a more complete treatment later. For example, the animation functions (fadeIn, fadeout and animateProperty) are described in more detail in Chapter 16, “Working with the DOM.”

onmouseover()
onclick()
onmouseout()
onmousemove()
onblur()
onmousedown()
onmouseup()
onmousemove()
onkeydown()
onkeyup()
onkeypress()

This module essentially consists of a single function, dojo.query. This may seem a little unbalanced, especially compared to all the functions in a module like dojo._base.NodeList. But what you’ll soon see is that this single function is really quite a monster and extremely powerful.

The Document Object Model (DOM) contains the representation of the web page and for most pages contains a large number of individual elements, sometimes in the thousands. Cascading Style Sheets (CSS) introduced a technique for separating the style of an element from the tag itself but introduced a problem: How could a CSS style be easily applied to one or more page elements when so many elements existed? This problem was solved with a pattern matching language called “CSS selectors,” which provided a syntax for identifying HTML elements based on one of their characteristics such as tag type, class, or some attribute value.

Many AJAX techniques also require manipulating elements, so it is very useful to be able to find the few elements you need from the many elements that exist in a typical DOM. The same solution already developed for applying CSS styles can also be used to find DOM elements for AJAX. And that is exactly what dojo.query gives us—a technique for using the CSS selector pattern matching language to find DOM elements. You specify the selector string, and the function will return an array of elements meeting that criterion. The array is returned as a NodeList, which is an object type that we’ve already reviewed and has lots of useful methods.

Following is an example of some code that will search the DOM for all HTML <div> tag elements that have a class of codeSample. The code returns an object of type NodeList containing zero or more elements.

     nl = dojo.query("div.codeSample")

We’ll explore this function, along with the syntax for CSS selector strings, in Chapter 16.

This module consists of functions for working with the XMLHttpRequest (XHR) object, the heart of AJAX. Descriptions here will be brief because we spend more time on these functions in Chapter 15, “Ajax Remoting.” The XHR object is used to send a request to the server without doing a page refresh. Different types of HTTP requests may be sent, such as GET and POST. This module provides wrappers that will be used to create the various types of requests. By providing these wrapper functions, Dojo allows your code to be simpler and easier to read than if you used the XHR object directly. It is usually necessary to send some data along with the request. This module also contains a number of useful functions for manipulating data and transferring it from one common format to another.

This module consists of a number of functions that can be used to provide basic visual effects on DOM elements. As you can see in Table 11.9, there seems to be a rather limited number of effects, just fadeIn, fadeout and animateProperty. Although it may not at first seem like much, it turns out that one of the functions, animateProperty, is actually extremely powerful because it lets you work with any CSS property.

dojo.xhrGet()
dojo.xhrPost()
dojo.xhrDelete()

dojo.rawXhrPost()
dojo.rawXhrPut()

dojo.formToObject()
dojo.objectToQuery()
dojo.formToQuery()
dojo.formToJson()
dojo.queryToObject()

Some of these functions may remind you of similar functions associated with NodeList, and they should considering they are exactly the same! The difference is that these functions work by being passed a DOM element as the first parameter instead of operating against an array of DOM elements as they do in NodeList.

The signature for these methods is deceivingly simple. They all take a single object as their argument. That object, however, can be quite complex. It should always contain a property called node, which is the id of the element on which to perform the animation. Other properties control the animation itself. We explore these further in Chapter 16.

This ends the discussion of the “base” features. One final note: The technical reason that these are called “base” functions is that the original code for the features (before they are aggregated in dojo.js) is contained in the “_base” directory under “dojo,” hence the name “base.” Let’s consider some additional features next. They’re termed the “core” functions because they are still important and useful, just not part of “base.”

The way that files and directories are organized for “core” features is a little more complex than for “base” features. The organization of related JavaScript functions into files and subdirectories is termed “packaging,” and a single group of related functions is called a “module.”

Dojo features in the base module are included in the single “dojo.js” (or “dojo.js.uncompressed.js”) files, while “core” features are organized in one of two different ways. A “core” module may consist of a single JavaScript file within the “dojo” directory. Or it may consist of a subdirectory under the “dojo” directory. Why two approaches? The primary purpose is two provide the developer with a fine-grained technique for including features within a single page. For example, the dojo.date module contains functions related to dates. However, you’ll notice that these functions are included in two different JavaScript files (“locale.js” and “stamp.js”) contained in a subdirectory called “date” under the main “dojo” directory. The functions in “locale.js” provide various internationalization processes on date strings. The functions in “stamp.js” allow conversion between various common date types. The Dojo architects are anticipating that developers may often need one or the other of these features sets, but not usually both.

A developer can include the functions for internationalization with the following code:

   dojo.require("dojo.date.locale");

This would make the functions in “dojo/date/locale.js” available to the page but not the functions defined in “dojo/date/stamp.js.” To include those you would need to provide an additional dojo.require statement in your code.

Note: There is a shortcut that provides a technique for including all the files within a module. You can use the * wildcard. The code that follows would make all the functions defined in both of the date files available to your page:

   dojo.require("dojo.date.*");

Be careful when using this approach. While it will certainly work, the reason that Dojo organized the functions into two separate files is so that you don’t have to include both of them. By including both in your page, the page may take longer to load and execute. So only include both files if you really need to use the functions in them.

You may notice that there is an additional file containing date functions, “dojo/date.js,” which you may use. It contains functions such as getDaysInMonth(), which returns the number of days in the same month as a specified Date object. To include these functions, use the following code:

   dojo.require("dojo.date");

Notice that this code does not use the wildcard because it is getting a single specific file “dojo/date.js.”

Another subtlety in using Dojo modules is that some functions require functions defined in other modules. Those modules also need to be included in your page for the code to work properly. The dojo.date.locale functions are examples of this. To work, they also need the following modules to be included:

At this point, you may be breaking out into a cold sweat. How can you possibly be expected to know all the dependencies between various Dojo modules? The good news as that you don’t have to. Dojo modules contain this information. Near the top of the file “dojo/date/locale.js” you can find the following lines of code that cause Dojo to load all the dependent modules:

     dojo.require("dojo.date");
     dojo.require("dojo.cldr.supplemental");
     dojo.require("dojo.regexp");
     dojo.require("dojo.string");
     dojo.require("dojo.i18n");

We’ve now exhausted the various approaches to including date-related Dojo functions in your page. The date module uses all the various approaches to packaging available in Dojo and is a good module to study to understand the techniques. However, most of the modules are simpler. So after you understand how the date module works, the others will be more obvious.

The Dojo packaging system is very powerful and allows us to achieve the best of all possible worlds (at least in the context of loading JavaScript files!).

As a final comment, much thought and effort have gone into the creation of the Dojo packaging system. It addresses the problems of making complex JavaScript code available to a web page. You will face the same problems in organizing the JavaScript code that you write yourself. And the good news is that you can use the Dojo packaging system on your own code!

There are a number of Dojo “core” modules, some of which are so important and useful that they require their own chapters to describe them. So for now, we examine them at a summary level, merely describing their purpose without delineating the functions they contain.

Table 11.11 summarizes the purpose of the primary “core” modules in Dojo. (Note: If you’re checking for completeness, there are a few modules I’ve skipped because you are unlikely to use them such as AdapterRegistry.)

This concludes are introductory discussion of the Dojo “base” and “core” features. As you can see, Dojo covers a broad range of functionality. Subsequent chapters allow us to explore these features in more detail and review more examples of actual usage.

The next chapter provides an overview of using Object Oriented Programming (OOP) techniques when working with Dojo. This is important because the Dojo features are exposed to developers as objects. So if you not familiar with OOP, as Bette Davis once famously said, “Get ready for a bumpy ride.” Only kidding, OOP concepts aren’t really that difficult, and after you understand them, you’ll be able to program in a new and useful way.