11 common Dojo gotchas

Tags:

Dojo is a great JavaScript toolkit, but it’s not perfect: It has a couple of gotchas that can be hard to debug just based on the error (or the lack of it).

To rectify this, here’s a list of some common mistakes and their solutions. It’s usually good to just go through each of these if you can’t figure out what’s up – it has helped me quite many times.

Missing dojo.require

Always remember to require any code you use. Even dijits used through markup require this.

A typical error message for this case is “my.Thinger is not a constructor”.

dojo.require('dijit.form.TextBox');

Missing dojo.parser

If you use dijits in markup, you need to require dojo’s parser class in order for them to work.

dojo.require('dojo.parser');

Note that parser has to be required even if you have parseOnLoad enabled.

No parseOnLoad/dojo.parser.parse

If your dijits in markup don’t work, remember to make sure you have either parseOnLoad in djConfig, or that you call dojo.parser.parse

var djConfig = {
    parseOnLoad: true
};

Missing dojo.provide

Always add a dojo.provide when declaring classes. Without it, dojo.require will not function properly.

A typical error you’ll get for this usually says something like “Could not load my.Thinger”.

dojo.provide('my.Thinger');

No call to startup() with programmatic dijits

When instanciating dijits programmatically, always remember to call d.startup()

var thingy = new my.Thinger();
thingy.startup();

Trying to access dijit’s DOM too early

You should not use a dijit’s constructor to access the dijit’s DOM. The function where this should be is either postCreate or startup.

constructor: function() {
    //this.domNode etc. is not ready yet
},
 
postCreate: function() {
    //this.domNode is ready
},
 
startup: function() {
    //this.domNode is ready
}

Note: If you have child dijits and need to access them, you must use startup instead of postCreate.

More than one root in a _Templated dijit

Dijit templates must only have a single root node. If you have more than one, it will not work – this includes HTML comments!

Wrong:

templateString: '<p>foo</p><p>bar</p>'

Wrong:

templateString: '<!-- Main foo --><p>foo</p>'

Right:

templateString: '<div><p>foo</p><p>bar</p></div>'

Sharing two ID’s

Similar to DOM, an ID given to a dijit must be unique.

Missing theme class

Dijits not rendering like they should? Make sure you have loaded the correct CSS files and set the body’s class to the theme’s name.

<body class="claro">

Spelling mistakes

However obvious, this is something that can happen and the error messages produced are rarely useful.

Check all class names, method names, etc. in dojo.provides, requires, dojo.connects and so on.

Using the wrong docs

Often Dojo-related google results point to the old, often outdated or poor, documentation of Dojo. You should usually try to find documentation from docs.dojocampus.org

More?

Do you have a common issue you stumble with when working with Dojo? Share it in the comments!

Thanks to @rvdavid for inspiring this post and the guys at the #dojo IRC channel for some suggestions to this list.