Dojo 1.4 Custom Build

Nov 09, 2011
Dario Mora

Dojo's default configuration loads javascript resources from the server only as they're required, Dojo, in its source distribution, contains many separate files and resources. Normally each “dojo.require” statement results in a synchronous HTTP call to the server to retrieve a resource


Large applications that have many dependencies can take a very long time to load when a build isn't used and because browsers wait for each synchronous call to complete before continuing with anything else the large series of requests performed by Dojo may significantly degrade page-load times. Dojo does not include a single file containing every possible dojo function, to compensate this common issue, Dojo includes functionality to create a custom build that meets the needs of your particular web site and configure which resources are bundled directly to dojo.js


A Dojo custom build groups together modules into layers. A layer, which is one big .js file, loads faster than the individual .js modules that comprise it.


A layer is a single, minified JavaScript file which combines all of the JavaScript code from multiple source files, including dependencies. This file can then be included on the site using standard HTML script tags.


The following instructions describe how to create a Custom Profile for Dojo:

Prerequisites

  • A source code version of Dojo, it can be downloaded from download.dojotoolkit.org, be sure to select the source code build, which has -src in its file name:  dojo-release-1.4.2-src.zip

  • Java™ 1.4.2 or later

Creating a Custom Profile

A Dojo profile controls how the build system creates the custom layers . This file defines exactly what the build system will include to create the custom Dojo layer.


We use dojo.require to specify modules that an application needs, but larger Dojo applications put this list of requirements into a single file that only includes a list of dependencies. You specify, via a build profile, exactly which resources to include in the layers that you build.


Dojo build profile structure:

dependencies = {
  layers : [ ],
  prefixes : [ ]
}; 

The layers section is an array of layer files you want to create.


The prefixes section is an array of individual prefix objects. Each prefix object describes where a particular top-level module's source is found relative to dojoRootDir/dojo.


The profile should be a file named something.profile.js, and should be located in dojoRootDir/util/buildscripts/ profiles


This is an example of dojo layer that includes the functionality for dojo.fx, dojo.xml.parser

dependencies ={
    layers:  [
        {
        name: "mynewdojo.js",
        dependencies: [
            "dojox.xml.parser",
            "dojo.fx"            
        ]
        }
    ],
    prefixes: [
        [ "dijit", "../dijit" ],
        [ "dojox", "../dojox" ]
    ]
};

Custom build

The Dojo build script is located in the dojoRootDir/util/buildscripts directory, to begin your build, you use the build.sh or build.bat on Windows.

build.bat profileFile = <profile_file> action=<actions>

The build system has a command line parameters, the most important are:


profile

The profile to be used for the build.


action

The list of actions to perform. The most common one is release which does the default build magic. The clean option removes previous build artifacts.


version

Optional. The version number of the build. When you interrogate dojo.version, this is the number that will be reported.

Use  a Custom Build

Include the calls to the javascript files in your HEADER section:

<!-- dojo.js provides the package system and base utilities -->
<script type="text/javascript" src="/js/dojo/dojo.js"></script>
<!-- include the rest of the modules we need -->
<script type="text/javascript" src="/js/dojo/mylayer.js"></script>

Summary

This small “how to” show you how to use Dojo build functionality to create a custom build that meets a specific requirements. A custom build ensures that we does not include unneeded modules and can achieve a fast Dojo load without tricks or hacks, just the use of <script src=”…”> to load your custom build of Dojo.