Modules

Dojo's code is split into logical units called modules. These are much like packages in Java, except that in Dojo a module can contain both constructors (like classes in Java) and simple functions.

For example, the "dojo.html" module contains a number of functions, such as dojo.html.getContentBox(). The "dojo.dnd" module contains a number of constructors for things like HtmlDragObject etc.

Note the naming convention - functions start with a lowercase letter, and constructors (which are technically functions but act more like classes) start with a capital letter.

Modules could be called "namespaces", except for the fact that "namespaces" has a different (but related) meaning w.r.t. widgets.

Resources

In the simple case, a Dojo module is defined in a single JavaScript file. But sometimes, a single module is split into multiple files.

For example, the dojo.html module, although originally defined in a single file, was getting too big, so we split into multiple files. This is for performance reasons, so that the browser only downloads the code it needs.

Unfortunately this implementation detail is not transparent to the Dojo user. You have to know which file contains the functions you need, and then include that file explicitly.

Each of these files is called a resource.

The line:

dojo.require("dojo.html.extras")

will include the file src/html/extras.js, which in turn defines some of the functions (but not all the functions) in the dojo.html module.

A single JavaScript file never defines multiple modules, although often a single file will define multiple constructors. In Java this would be equivalent to defining two classes in the same file.

All of this complication is for performance reasons, trying to balance

• not downloading more stuff than you need
• not downloading too many tiny files

Setting up Require Statments

How do you know what resources to dojo.require()?

1. modules

First, find out what modules you are using. In this example we'll assume you are using dojo.lfx.html.

2. resources

By reviewin the API doc you can see that dojo.lfx.html is defined in two files:

• src/lfx/html.js
• src/lfx/extras.js

Depending on what functions you are using, you will either do

dojo.require("dojo.lfx.html");

or

dojo.require("dojo.lfx.html");

dojo.require("dojo.lfx.extras");

Wildcards

There is a wild card include, such as dojo.lfx.* . New users might be surprised to learn that this may not necessarily include everything under lfx. Rather, there is an __package__.js file that defines what is included with the wild card, and this may also depend on the environment in which Dojo is loaded. For example, a browser will likely load different modules than Dojo would when loaded with Rhino on the command line.

dojo.provide()

Each file defining a resource should have (exactly) one line at the top defining the name of the resource.



Example:

  dojo.provide("dojo.html.extras")

For historical reasons, the dojo.provide() call serves two functions:

1. define the name of the resource (and register that the resource is loaded)
2. make sure that the resource's module exists (ex: make sure that dojo.html exists), so that statements like "dojo.html.foo = ..." don't fail with an error about dojo.html not existing.

Widget Namespaces

Widgets are combined into groups called namespaces. All the widgets built into Dojo are in the "dojo" namespace, but someone else could write their own widgets and put them in a different namespace. For example, you could write your own button and checkbox widgets, and put them into an "acme" namespace. Then "acme:Button" would be your button, and would be unrelated to the button object built into dojo, called "dojo:Button".



Information on writing your own widgets occurs later in this book.