Concept

This feature allows hosting dojo on a separate machine from the application; usually the dojo instance is shared between multiple applications. It's especially useful for internet applications, where dojo will be cached by proxy servers close to the client, thus increasing performance. AOL hosts dojo in this way.

When the dojo instance is shared between multiple applications, the dojo.js on the shared server typically won't contain all the resources required by an individual application. Thus, when the application issues a dojo.require() call, it will download the resource (such as dojo.html.extras).

This feature allows dojo to load the resource across domains. The technique uses HTML script elements to load the resources. This technique is also referred to as xdomain loading or xdDojo.

Benefits

• You get more connections in MSIE, since you can load from another domain. Faster loading.
• You get increased cacheability/startup if many of your applications use the same installation.
• Resource loading does not block the rest of the page from filling in as with Dojo's normal, synchronous loading.
• With a local install, your ISP may charge you for all of those Dojo bits that you are serving.

Implications/Limitations

• Resource search paths are not supported. Only the first path in the search path is supported. So that means if you use something like dojo.require("dojo.dom.*") won't work because there is no dom/__package__.js file. You need to make sure to use the exact require syntax that maps to the first file in the resource search path.
• Not all external resources can be xdomain loaded, in particular widget images, and things like IFrameScriptTransport? and dojo.undo.browser because they need to load iframe_history.html. Therefore, it is still important that you have your own version of Dojo installed on your server. If you are very careful about what you need, you may be able to get away with not having your own installation. [as of 0.4.2, you do not need a local Dojo copy]
• Requires a "xdomain" build of Dojo (see below for more info on how to make a xdomain build). For 0.4.2+, you can use Dojo's web build system to make an xdomain dojo.js that includes just Dojo modules. The web built dojo.js is tied to an xdomain Dojo build on a Content Delivery Network (CDN).
• Asynchronous loading. MUST use dojo.addOnLoad() to register a callback function to get notification of package loading. This can be used even after the initial page load. Just do the dojo.require()s that you need, and then call dojo.addOnLoad() with a callback function, and once those new packages are loaded (or if they are already loaded), then the callback will be called.

Module-specific notes

For Dojo 0.4.2+:

Widget automatic loading

• xdomain loading does not support automatic loading of Dojo or custom widgets. You must explicitly include widgets you want to use by using dojo.require() statements for widgets you want to use.

dojo.debugDeep()

• Save src/debug/deep.html to your local server and set djConfig.dojoDebugDeepHtmlUrl to the location of that file.

dojo.flash

• This module uses document.write(), so you must do a custom web build that includes the following modules to use it:
  • dojo.event.*
  • dojo.flash

dojo.io.createIFrame()

• Save iframe_history.html to your local server and set djConfig.dojoIframeHistoryUrl to the location of that file.

dojo.rpc.YahooService

• Save src/rpc/yahoo.smd to your local server and set djConfig.yahooServiceSmdUrl to the location of that file.

dojo.storage

• This module uses document.write(), so you must do a custom web build that includes the following modules to use it:
  • dojo.event.*
  • dojo.storage

dojo.undo.browser

• Save iframe_history.html to your local server and set djConfig.dojoIframeHistoryUrl to the location of that file.
• If you do a custom build using the web tool and want to use dojo.undo.browser, be sure to include it in dojo.js. Do not load it after dojo.js loads, otherwise it will not work.

dojo.widget.GoogleMap

• Does not seem to work even if you include dojo.widget.GoogleMap in a custom build.

dojo.widget.Editor2, dojo.widget.Editor, dojo.widget.RichText

• Save src/widget/templates/richtextframe.html to your local server and set djConfig.dojoRichTextFrameUrl to the location of that file.

Usage

• In djConfig, add useXDomain = true.
• After the script tag for Dojo, set the following before any dojo.require statements:
  
  dojo.registerModulePath("dojo", "http://url/to/xdomain/dojo/installation/src");[For 0.4.2+, use djConfig.modulePaths instead (more info below)].
• Register a callback function to get notification of when the packages are loaded by using dojo.addOnLoad().

An example is at the end of the Usage section.

Resource Loading Timeout

You can optionally set a wait time in milliseconds (djConfig.xdWaitSeconds) that specifies how long the resource loader should wait for a resource to load until returning an error. Since script elements do not give information about failed or long-running requests, this timeout is used to prevent infinite waiting in the browser. An exception via dojo.raise() will be thrown to indicate a load error. The default xdWaitSeconds is 30 for Dojo versions before 0.4.2, and 15 for 0.4.2+.

djConfig.modulePaths

In Dojo 0.4.2+, instead of calling dojo.registerModulePath() a bunch of times to register all of your custom module paths, you can use djConfig.modulePaths to set up the module to path mappings:

Complete Example

This example shows cross-domain loading pieces that should be in the head element of an HTML page:

<script type="text/javascript">

var djConfig = {

baseScriptUri: "../path/to/local/dojo/",

useXDomain: true,

xdWaitSeconds: 10

};

</script>

<script type="text/javascript" src="http://some.domain.com/dojo/dojo.js"></script>

<script language="JavaScript" type="text/javascript">

dojo.registerModulePath("dojo", "http://some.domain.com/dojo/src");



//Now any Dojo resources that are referenced via dojo.require()

//will be xdomain loaded.

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



dojo.addOnLoad(function(){ alert("Resources are loaded!");});

</script>

Note that it is important to always follow any block of dojo.require() statements with a dojo.addOnLoad() call to register a function that should be called after the asynchronous package loading finishes. So, if you had this function before using an xdomain build:



function someFunctionThatIsRunAfterPageIsFirstLoaded(){

dojo.require("dojo.html");

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



//Use dojo immediately

dojo.event.connect(....);

}



With xdomain asynchronous loading, this becomes:



function someFunctionThatIsRunAfterPageIsFirstLoaded(){

dojo.require("dojo.html");

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



dojo.addOnLoad(function(){

//Use dojo after all the packages are ready.

dojo.event.connect(....);

});

}

Making a "XDomain" Build

Specify a dojoLoader=xdomain parameter to the build command. For instance, to build the Ajax custom build with xdomain loading:

ant -Dprofile=ajax -DdojoLoader=xdomain -Ddocless=true clean release intern-strings

dojoLoader=xdomain will include loader_xd.js in dojo.js, and generate the *.xd.js files that are needed to enable the build to be loaded across domains. The "intern-strings" part will inject the HTML and CSS used by widgets into the widget JavaScript file so that it can be loaded across domains.

New options for 0.4.2+

As of 0.4.2, there are two new options you can add to the ant build. Also, it is no longer necessary to specify -Ddocless=true. The task that uses the "docless" value has been removed for 0.4.2.

xd-dojo-config

This ant task will set djConfig.useXDomain = true; inside the built dojo.js, effectively making the dojo.js always want to try to do xdomain loading (you can always load some modules locally by using dojo.registerModulePath()). It will also automatically register the module path for Dojo, so that you do not have to specify dojo.registerModulePath("dojo", "[url goes here]");. In order for the xd-dojo-config task to work, you must define -DxdDojoUrl. Also, this task should be run after the release ant target. Example:

ant -Dprofile=ajax -DdojoLoader=xdomain -DxdDojoUrl=http://some.domain.com/dojo/release-0.4.2/src clean release intern-strings xd-dojo-config

If you use this task, then for pages that use this dojo.js, you do not have to explicitly set djConfig.useXDomain or call dojo.registerModulePath() for the Dojo module.

strip-resource-comments

This task will remove the comments from the files in src/. This helps the download size of modules that are not part of dojo.js and are loaded via dojo.require(). This ant task is available for regular builds too. It should be the last task in the list. Example:

ant -Dprofile=ajax -DdojoLoader=xdomain -DxdDojoUrl=http://some.domain.com/dojo/release-0.4.2/src clean release intern-strings xd-dojo-config strip-resource-comments