build customBase ¶

Author:	Scott Jenkins
Project owner:	?
since:	V?

Contents

build customBase

Custom base is used to make an extremely small file size version of dojo.js.

Introduction ¶

Normally, when the builder system creates dojo.js it includes the entire base set of Dojo APIs (almost everything that can be accessed directly in the dojo namespace). This provides robust and usable core functionality in a file that is approximately 76.7 KB uncompressed and 26.5K gzipped as of Dojo 1.2.3.

However, in some cases, such as creating web applications intended for use on smart phones, you may desire to create an even smaller dojo.js. Using customBase you can achieve minimal Dojo versions as small as approximately 6k (including the stubs described below).

This is a very advanced feature, and if you think you need to use it, you should think carefully first. If after careful consideration, you still want to use this feature, be very, very careful and document it thoroughly for your own understanding.

dojo.require for base functions ¶

When you use the customBase option, some base Dojo functions are not copied into your dojo.js file, in order to reduce the file size.

Instead, a dojo.require statement is generated for each base resource that the builder identifies as being used in your module. This identification is done with regular expression matching, and is by design somewhat lax to ensure it catches all resources that are needed.

This allows you to still use the entire base API, but at the cost of additional an additional round trip to the server at the time a function not in base is first called.

Usage ¶

In the profile for your build, specify the following for your dojo layer (note the customBase property):

layers: [
  {
       name: "dojo.js",
       customBase: true,
       dependencies: [
       ]
  },

 // ... remainder of profile

 ]

If, as shown in this example, you specify customBase: true, but do not specify any dependencies for the dojo.js layer, then then none of dojo._base gets added to dojo.js.

You just end up with the following from dojo/_base/_loader, basically, just bare utilities for browser detection:

dojo.ready

addOnUnload

dojo.require

dojo.provide

bootstrap.js

hostenv_browser.js

loader.js

Including Specific Resources ¶

To include specific dojo base resources in your minimal build, use the dependencies list for the dojo.js layer.

For example, if you specify customBase: true, but want a particular dojo/_base module, say just the array help functions and dojo.Deferred, your profile dojo.js layer would look like this:

{
       name: "dojo.js",
       customBase: true
       dependencies: [
               "dojo._base.Deferred",
               "dojo._base.array"
       ]
}

Caveats ¶

If you use customBase: true, then the build system will use regular expressions to see if any of the modules in the build (dojo, dijit, dojox, your custom namespaces) use any dojo._base methods, and if they detect a usage, it will inject dojo.require calls into the built modules.

This helps avoid issues where you use a module that needs a dojo._base module that you did not include in your dojo.js. However since it is using regular expressions, you may get more dojo.require calls for dojo._base modules than necessary. The idea was to have the detection be very lax in what it matches to avoid run time errors.

Example: if the build finds “indexOf” in the module, it will add in a dojo.require("dojo._base.array"), but that indexOf in the module could have been a String method call.

Known Bugs ¶

customBase: true should not be used with djConfig.require. There is a bug where the djConfig.require will not be included correctly depending on if you leave out dojo._base.browser: http://bugs.dojotoolkit.org/ticket/7756

build customBase

build customBase¶

Introduction¶

dojo.require for base functions¶

Usage¶

Including Specific Resources¶

Caveats¶

Known Bugs¶

Table of Contents