We answer many, many, many questions on a daily basis through our Dojo training workshops, JavaScript support plans and during our customers’ development projects.

We have bucket-loads of answered questions. What to do with them all…
Oh? Provide you with the answers? Ok.

Here it is! Each week we’ll answer a commonly asked question about Dojo and then we’ll give it to you. Here we go!

A question we commonly get is what the difference between dojo/domReady and dojo/ready is and why we would actually choose one over the other. In order to understand the answer to this question, let’s quickly look at how they work under the hood.

dojo/domReady

require(["dojo/domReady!"], function () {
	console.log("The DOM is ready");
});

require(["dojo/domReady"], function (domReady) {
	domReady(function () {
		console.log("The DOM is ready");
	});
});

The most common use of dojo/domReady is as a plugin in a require call, but it can also be used as a function. In order to determine when the DOM is ready, domReady listens for the DOMContentLoaded event where available and window.onload as a fallback. If the document is not yet ready, it will queue any registered callbacks, and will execute them in the order that they are queued. If used after the DOM is ready, the callback is immediately invoked.

dojo/ready

require(["dojo/ready"], function (ready) {
	ready(function () {
		console.log("The DOM is ready");
	});
});

require(["dojo/ready"], function (ready) {
	ready(100, function () {
		console.log("The DOM is ready");
	});

	ready(1, function () {
		console.log("This fires first");
	});
});

The dojo/ready module provides a function that registers a callback that will run once three conditions have met:

  1. The DOM is ready
  2. All outstanding modules of requested code have completed loading
  3. Other registered functions with a higher priority have completed.

It can take up to three parameters:

  • priority signifies the order in which to execute the callback relative to other registered callbacks, where lower values are considered higher priority. This argument is optional, defaults to 1000, and must be a number.
  • context is the context in which to execute the registered callback (the value of this in the invocation). This argument is optional.
  • callback is the function to be registered. It is required.

Internally, dojo/ready uses dojo/domReady to determine when the DOM has loaded. Additionally, the dojo/parser module uses dojo/ready to queue up its automatic parse when parseOnLoad is set to true, so it can be used to ensure that the parse has completed before you perform further work that may be dependent on the fully parsed page.

Determining the right module to use

As you can see, the primary difference between dojo/domReady and dojo/ready is that dojo/ready allows you to specify a priority and context, and dojo/ready cannot be used as a plugin, like dojo/domReady. Additionally, dojo/ready waits for all requested code to finish loading, as opposed to simply just waiting on the DOM to be ready. Given these differences, we can easily determine the appropriate time for each module.

If you need to ensure that your callbacks execute in a set order, or they need to wait for things like all modules of code to finish loading, dojo/ready is the right choice. If you’re depending on parseOnLoad in your application, you need to use dojo/ready.

If you don’t need to wait for all code other than your dependencies to complete loading, or you don’t need to worry about the parsed results, dojo/domReady is the recommended solution, as it requires no changes to your code other than adding the dojo/domReady! dependency to your require call.

In Closing

As you can see, both of these modules are useful and have their purposes in registering callbacks to fire when the DOM is ready. If you’re interested in diving into the Dojo Toolkit more, SitePen offers a number of workshops that will help broaden and deepen your knowledge of Dojo!