11 common Dojo gotchas

November 27, 2010 – 9:29 pm 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”.


Missing dojo.parser

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


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”.


No call to startup() with programmatic dijits

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

var thingy = new my.Thinger();

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!


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


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


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


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.

Share this:
  1. 3 Responses to “11 common Dojo gotchas”

  2. Hi Jani,

    Thanks for compiling this list – it is useful. I don’t know if I’ve mentioned this to you over email, but I’m pretty much a green horn when it comes to working with the dojo toolkit.

    Would love to actually work with Dojo with the same facepalm-less flow I have with Zend Framework.

    One day I suppose, I’ll get enough time to sit down and actually mess around with Dojo.

    Till then, I guess I’ll be treating Dojo as a blackbox and just sticking with documented usage and examples as per docs.dojocampus.org

    Great post. Thanks again.

    Keep in touch brother.

    By rvdavid on Nov 28, 2010

  3. Its really frustating, always when i search something that is dojo related in google it pulls out the page of the old documentation that simply redirects you to dojo campus, where you have to do another search. Thats why, now, i always do query like this “dojo campus docs dijit.dialog” to be sure to get the results from campus.

    But another new but great source of information with the examples from dojo campus is:


    By chrisweb on Nov 29, 2010

  4. @chrisweb that’s one of my pet peeves. It annoys the crap out of me sometimes because at least 70 – 80% of the results on google (at the time) were from the old prefixed domain.

    But yeah, docs.dojocampus.org and the dojo toolkit reference site give some good answers and some _basic_ examples too.

    By rvdavid on Nov 29, 2010

Post a Comment

You can use some HTML (a, em, strong, etc.). If you want to post code, use <pre lang="PHP">code here</pre> (you can replace PHP with the language you are posting)