OBSOLETE? - Now in book

Notes on the Dojo packaging system, by Dylan Schiemann

Purpose

The packaging system allows you to list a single script include file, which will then find and fetch packages as they are needed for your application, from the Dojo source tree. This means in the simplest case, no build process is required, and yet there is no need to include a script tag for every script file that is to be loaded.

Additionally, the packaging system allows for the creation of a compressed package file that contains all of the script code needed for your app, no more, and no less, through an Ant build step.

NOTE: For Dojo 0.3+, dojo.hostenv.conditionalLoadModule() has been replaced with dojo.kwCompoundRequire() and dojo.hostenv.moduleLoaded() has been replaced with dojo.provide(). To use the old methods with Dojo 0.3+, please use a compatibility package.

Example package file format

// contents of dojo/src/webui/widgets/__package__.js

dojo.kwCompoundRequire({
	common: ["dojo.webui.widgets.parse"] // a generic dependency
});

dojo.provide("dojo.webui.widgets.*");

Definitions

kwCompoundRequire

passes an object of modules, grouped by host environment

provide

Conclude with the name of the module that is now considered loaded.

A Longer Example

here's the contents of a package file located at dojo/src/foo/__package__.js:

dojo.kwCompoundRequire({
    common: ["dojo.foo.Foo", "dojo.foo.Bar"],
    browser: ["dojo.foo.Baz"]
});

dojo.provide("dojo.foo.*");

This set of definitions says that when someone writes dojo.require("dojo.foo.*"); from within a browser, Foo.js, Bar.js, and Baz.js will get included from this directory. When run from the command line, only Foo.js and Bar.js will get included.

Including Dojo from source files

Once your packages are specified, to include Dojo from it source tree, you simply include the following tag in your html source:

<script type="text/javascript" src="/dojo/dojo.js"></script>

Additionally, you will need to specify the modules to load as you need them loaded. I do this in a separate script file to initialize Dojo. For example, if you have code that required the Dojo event system, you would add the command:

dojo.require("dojo.event.Event");

Profile build file format

var dependencies = [ 
	"dojo.io.*",
	"dojo.event.*",
	"dojo.xml.*",
	"dojo.graphics.*",
	"dojo.io.BrowserIO",
	"dojo.webui.*",
	"dojo.webui.widgets.foo.*",
];

load("getDependencyList.js");

Building a package

After specifying a profile file as shown above that statically specifies the packages you want to include, save the file as /buildscripts/profiles/foo.profile.js. Then run Ant and specify the profile name as a parameter. For example:

ant -Dprofile=foo clean release

Then, in your html source, you can simply include Dojo by adding the following tag:

<script type="text/javascript" src="/dojo/release/dojo/dojo.js"></script>

Revision History

• 0.1, Initial brain dump, July 13, 2005