dojo.addOnLoad

Introduction

dojo.addOnLoad() has been deprecated in favor of the (equivalent) dojo.ready function, and more recently, in favor of the The AMD API, and the domReady! plugin.

The documentation below is preserved for legacy purposes:

Old Documentation

dojo.addOnLoad is a fundamental aspect of using Dojo. Passing addOnLoad a function will register the function to run when the DOM is ready. This differs slightly from document.ready and body.onload in that addOnLoad waits until all dependencies (and their recursive dependencies) have loaded before firing.

Sooner or later, every JavaScript programmer tries something like this:

if(dayOfWeek == "Sunday"){
    document.musicPrefs.other.value = "Afrobeat";
}
<form name="musicPrefs">
    <input type="text" name="other">
    ...

It doesn’t work because the “other” control is not defined yet. You can move the code to the bottom of the page, but that removes the linear nature of HTML. If you’re reading the code, you want to zero in on a control, and see the code that influences it close by.

dojo.addOnLoad(...) defers script execution until all the HTML and modules are loaded. It is currently deprecated and replaced by the dojo.ready function, and more recently, in favor of the The AMD API, and the domReady! plugin. When use Dojo 1.7+, you should require ‘dojo/ready’ and use ‘ready((...))’ function instead, or use the domReady AMD plugin. So this code:

// Dojo 1.7+ (AMD, domReady plugin)
function setAfrobeat(){
   document.musicPrefs.other.value="Afrobeat";
}

require(["dojo/domReady!"], function(){
  setAfrobeat();
});
// Dojo 1.7+ (AMD, dojo/ready module)
function setAfrobeat(){
   document.musicPrefs.other.value="Afrobeat";
}
require(["dojo/ready"], function(ready){
     ready(function(){
         setAfrobeat();
     });
});

conveniently replaces this code:

// Dojo <1.7
function setAfrobeat(){
   document.musicPrefs.other.value="Afrobeat";
}
dojo.addOnLoad(setAfrobeat);

When the function is small, you may prefer to write it inline:

// Dojo 1.7+ (AMD, domReady plugin)
require(["dojo/domReady!"], function(){
   document.musicPrefs.other.value="Afrobeat";
});
// Dojo 1.7+ (AMD, dojo/ready module)
require(["dojo/ready"], function(ready){
  ready(function(){
    document.musicPrefs.other.value="Afrobeat";
  });
});
// Dojo <1.7
dojo.addOnLoad(function(){
    document.musicPrefs.other.value="Afrobeat";
});

This is the function literal or anonymous function construct of JavaScript. If it looks really, really weird to you, take a peek ahead at Functions as Variables for an explanation.

Another use is “embedded onLoad”. We’ll define an addOnLoad function (anonymous), and within that function will load more components, registering a second addOnLoad function. The first will execute very quickly (assuming you are only loading dojo.js), and the second will wait until the package dependencies are complete:

// Dojo 1.7 (AMD)
require(["dojo/ready"], function(ready){
    ready(function(){
        require(["dijit/Dialog", "dijit/TitlePane"], function(Dialog, TitlePane){
            ready(function(){
                // dijit.Dialog and friends are ready, create one from a node with id="bar"
                var dialog = new Dialog({ title:"Lazy Loaded" }, "bar");
            });
        });
    });
});
// Dojo <1.7
dojo.addOnLoad(function(){
    dojo.require("dijit.Dialog");
    dojo.require("dijit.TitlePane");
    dojo.addOnLoad(function(){
        // dijit.Dialog and friends are ready, create one from a node with id="bar"
        var dialog = new dijit.Dialog({ title:"Lazy Loaded" }, "bar");
    });
});

If no in-flight XHR activity is found, and all dependencies have been solved, addOnLoad functions fire immediately.

Examples

Let’s dynamically include code on button press and fire an event once the code is included:

The HTML markup is pretty simple, just a button to click on

<button data-dojo-type="dijit.form.Button" id="buttonOne">Click me!</button>

The JavaScript code fires a dojo.require when you click the button.

// Dojo <1.7
dojo.require("dijit.form.Button");

// connect to button
dojo.addOnLoad(function(){
    dojo.connect(dojo.byId("buttonOne"), "onclick", "loadCode");
});

function loadCode(){
    alert("About to dojo.require dijit.layout.BorderContainer.");
    dojo.require("dijit.layout.BorderContainer");

    // add a dojo.addOnLoad
    dojo.addOnLoad(function(){
        alert("This fires after BorderContainer is included. Now it is: " + dijit.layout.BorderContainer);
    });
}
Error in the documentation? Can’t find what you are looking for? Let us know!