Dojo Module Packaging and Loading
by Peter Higgins

Another quick Cookie for Dojo-land: One really compelling reason to use Dojo. New in Dojo 1.2, the Dojo team decided to make clear and available for download the single dojo.js file from the overall toolkit. It has never been explained or marketed as a “drop in solution”, though it has always been able to perform as such.

You can download the dojo.js, and place it anywhere in your project. Simply load the file with an appropriate script tag:

<script src="scripts/dojo.js"></script>

Immediately after this script tag appears, you will be provided a host of core utility functionality, standard across every library. CSS Selector engine (dojo.query), DOM utilities (dojo.coords, .marginBox, .style, .byId, .place, and more!), Event handling (dojo.connect, dojo.pushlish, dojo.subscribe), Ajax (dojo.xhr, and a host of mappings like dojo.xhrPost, .xhrGet and so on), Animations and FX (dojo.anim, .animateProperty, .fadeOut/In), advanced Javascript helper functions (dojo.forEach, dojo.delegate, dojo.hitch, dojo.partial, dojo.indexOf), and additional tools for synthetic object-orientation with multiple inheritance via dojo.declare, dojo.mixin, and dojo.extend. All the potential to write really great apps is all wrapped up in this tiny package they call “Base Dojo”.

One thing we lose by using just “Base Dojo” is the one reason Dojo has never really explained “Base Dojo” outside of the context of the “Dojo Toolkit” — comprised of the aforementioned “Base Dojo”, “Core Dojo” (anything else in the dojo.* namespace), “Dijit” (the UI library), and “DojoX” (the extensions, incubator, and home of some really advanced functionality). How do you access all the rest of this great code?

Conveniently, “Base Dojo” provides and entire package organization and loading system, allowing you to easily write modular code. This cookie will explain some of the basic workings of the Dojo Package System, all built around two simple commands: dojo.provide and dojo.require. Here goes:

dojo.require works by paths relative to the path containing dojo.js, with dojo dijit and dojox assuming ../namespace by default (eg: dojox = ../dojox from lib/dojo12/dojo/dojo.js)

dojo.require(”dijit.form.Button”) will load lib/dojo/dojo/../dijit/form/Button.js (the dojo/../dijit is there to illustrate the redundancy) the full path ending up lib/dojo/dijit/form/Button.js

In this example, dijit/form/Button.js calls “dojo.provide(”dijit.form.Button”), explaining to the Package system the module has been (or is being) loaded, causing any subsequent dojo.require() calls for the same module to skip being tried again.

dojo.registerModulePath can be used to register a namespace at a specific location, again relative to the path containing dojo.js:

dojo.registerModulePath(”figgins”,”../../figgins”) would cause dojo.require(”figgins.samples”); to look for a file: lib/dojo12/dojo/../../figgins/samples.js or more simply: lib/figgins/samples.js

Everything works on relative paths, so assuming dojo.js is at a valid location, the rest of the system should “just work”.

Another handy function that uses this “modulePath” / require paradigm is called dojo.moduleUrl - This allows you generic access to file within registered namespaces (for example, “figgins” in ../../figgins, or the default of “something” in ../something with no registerModulePath in place). If we were to add our templates into a templates/ folder inside of the figgins/ namespace, we could access any of the files without worrying about where the overall code tree lives.

dojo.moduleUrl(”figgins, “templates/MyTemplate.html”); points to the file lib/dojo12/dojo/../../figgins/templates/MyTemplate.html, or more simply lib/figgins/templates/MyTemplate.html …

That’s all. The package system is really simple to use, and makes locating and storing modules, plugins, whathaveyou, in portable locations that “just work” once you successfully locate and load in your version of dojo.js - the heart of it all.

Tags: , , ,

This entry was posted on Thursday, October 9th, 2008 at 1:14 pm and is filed under Dojo Cookies. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.

One Response to “Dojo Module Packaging and Loading”

  1. Learning Dojo | SitePen Blog Says:

    [...] (article) Dojo Module Packaging and Loading [...]

Leave a Reply

You must be logged in to post a comment.