By Michael Woloszynowicz

By Michael Woloszynowicz

Saturday, November 13, 2010

The Dojo Toolkit - Lessons from the Trenches

Having spent the last few months working heavily with the Dojo toolkit to develop a large RIA document management tool I thought I'd share some of the lessons that I learned along the way. For those who haven't heard of Dojo, it is a JavaScript based RIA toolkit similar in nature to JQuery and Open Laszlo.

To get started let's discuss why I chose to use Dojo instead of the more popular JQuery toolkit. The primary motivators for me were as follows:
  • Dojo's syntax is very easy to read, write, and understand
  • Dojo has a fantastic collection of widgets that cover 90% of your needs
  • Dojo's class system turns JavaScript into a real programming language (more on this later)
  • Dojo does pretty much everything that JQuery does
  • On demand package loading means you can load what you need, when you need it
  • Comes with built in developer tools
To make this an objective post, there are a few downsides to Dojo that I've come accross:
  • It's not as popular as JQuery so it's harder to find new hires that already know it
  • Dojo is not as mature JQuery so documentation and code samples are not as easy to come by
  • Dojo is significantly larger than JQuery so it's easy to learn but hard to master
  • Dojo can become slow when writing a large application with lots of widgets or consuming a great deal of data (more on this later)
If you've made it to this point you're either already a Dojo coder or you're intrigued by its possibilities. If you are considering trying Dojo, my personal opinion is that you should. Having used both JQuery and Dojo, Dojo wins hands down as the better toolkit, a sentiment that is shared by many of co-workers. This post is not intended to be a rigorous tutorial on Dojo - there are many great books on this such as Dojo: The Definitive Guide - what I intend to do is give you some high level tips that books typically omit.

Tip 1: Use the Dojo class system
Dojo's class system is fantastic. It allows you to write proper Object Oriented code that you can nicely organize in a package structure. No matter how small a component you may be writing you should always encapsulate it in a Dojo class so that you can later extend it and load it on demand using Dojo's package loader. For those here that are back-end programmers I don't think I have to preach about the benefits of OO programming. Dojo provides it so just use it, it will only take you 30 seconds longer to wrap your code in a class. Dojo does allow for multiple inheritance and I encourage you to use it, but for the sake of your co-workers, document method uses of methods that are defined in parent classes. Unlike back-end languages it's difficult to trace the source of methods that originate up a complex inheritance chain.

Tip 2: Internationalize from the start
Dojo provides a great set of tools for internationalization (i18n). Even if you have no near term plan of supporting multiple languages, it's wise to house all of your copy into one or more master documents should the need for i18n arise. Although i18n is usually tedious, the tools provided by Dojo make it as easy as it gets. Doing this will only add a extra hour or two for each month of work.

Tip 3: REST
Dojo's AJAX package and widgets are heavily geared towards RESTful web-services which is both good and bad. The downside is that if you are trying to reuse non-REST back-end code, you may have to modify the behavior of some of the widget data stores (this is neither fun nor easy). The upside is that the support provided for RESTful web-services is outstanding right out of the box. If you're starting out with a new application I highly recommend you write your application as a RESTful API and build your front-end on top of that API (e.g. Twitter) using Dojo. This will not only make your front-end code clean but you'll simultaneously be developing a platform, not just an application.

Tip 4: Events, events, and more events
Dojo's architecture is heavily event driven, both with standard events and pub/sub style syndication. While event handling used to be tedious affair, it can now be handled with ease using built in tools such as dojo.connect [connect to an event] and dojo.hitch [bind a method call to a specific context]. I therefore highly recommend designing your objects and applications around an events based architecture. If you're tying multiple classes together, rather than passing object or method pointers across these classes, simply trigger events and have sibling or consuming classes connect to them. This allows your components to maintain a loose coupling resulting in a more robust application. Carefully decide when to use standard events vs. pub/sub as there are noticeable differences in performance between these two. If you really do need to broadcast an event to a wide audience where establishing individual connections would be too onerous, go for pub/sub, otherwise stick with standard events.

Tip 5: Go to the source
As I've mentioned, the documentation for Dojo is good but not great. The Dojo team does their best to maintain an up-to-date API and Reference Guide, also Dojocampus provides lots of examples but often times you just can't find what you're looking for. I've found that the best reference guide for Dojo is the source code itself. It is well documented but can be tricky to read. As described above, Dojo is heavily events based so when going over the source it's important to understand what events are being are being thrown and which objects are attached to those events. Debugging Dojo is not easy from the outset but once you learn its structure, it's quite consistent across its various components (with a few exceptions). Spend a day or two going through the source as this will pay off greatly in the long run. As an added bonus, Dojo was written by lots of great programmers, reading their code just might make you a better programmer. Another great tool for discovering the capabilities of an object is dojo.debug(). Simply pass your dojo object into the debug function and inspect it using Firebug's DOM inspector. This will give you lots of details about the objects contents in a runtime environment.

Tip 6: Don't settle
Dojo is designed to have its components extended to suit your specific needs. It will not cover 100% of your use cases so extending functionality will quickly become a reality. Whatever you do, don't change the Dojo source, extending a class may take a bit longer but it ensures that when you migrate to a new version your application doesn't break down completely. When extending a Dojo class, try to use this.inherited(arguments) [call the parent classes method with all the arguments] whenever possible so as to minimize the amount of code you have to copy and paste from the Dojo method you are overwriting. As mentioned Dojo can become slow if your application becomes large and you are using a number of widgets. To overcome this you will have to extend certain Dojo widgets and create optimized versions of methods so that they don't fire any unneeded events, especially if you are performing bulk operations. If you are not using any widgets on your page then you will not encounter any performance issues.

Tip 7: Don't rush it
As programmers we have a tendency to read the first 20 pages of a technical book then hit the ground running, learning as we go. Dojo is no different than any other language, you have to use it to become good at it but I would highly recommend at least skimming an entire book on Dojo before taking on a larger project. I made the mistake of getting half way through the book, then finishing the rest two months down the road only to realize that Dojo has already provided solutions to problems I was running into.

Tip 8: Think like a real programmer
For the longest time, JavaScript was seen as a lousy language and if you were a JS programmer you weren't a real programmer. Dojo changes all this by bringing in a wide array of tools that back-end programmers have utilized for years. The chaos is gone so take the time to design your class and event structures and take pride in your code, just as you would with any other language.

If you have any other Dojo tips that you've discovered while using it, please share them in the comments.

If you liked this post please follow me on Twitter for more.


  1. Couple of comments...

    Firstly, I'd suggest revising your Dojo documentation links to the following:

    These are versions of the API docs and reference guide that are exported at every major release. The docs are the source of the reference-guide material, but this means that what you see on dojocampus may actually reflect material beyond the current release (e.g. for 1.6). The API you linked ( has not been updated since sometime between 1.4.

    Secondly, I'd argue that "not as popular as jQuery" is not only a downside; I consider jQuery's popularity (and perhaps moreover its accessibility to people who don't necessarily know how to write good code, if at all) to be a double-edged sword.

    Yes, it's hard to find people who know Dojo, but once you do, the chances seem higher that the person in question actually knows how to write code. When you find someone who says he/she "knows jQuery" (which you see fairly more often), you really have no immediate guarantees.

    I say this from experience of being forced to work with such a person last year, and from hearing other such accounts. I'm certainly not saying that there aren't some really intelligent people using any particular framework, just that the sea of jQuery talent seems far more diluted. Of course, to an extent this is the price of "popularity".

  2. Thanks Ken, I've revised the links. I agree 100% with your comments on jQuery vs. Dojo programmers, it really does work both ways. When it comes to front-end programmers I've found that too many say they know JavaScript or jQuery when in reality they know how to animate a div or validate a form, nothing more. I think those that choose to use Dojo have a better programming foundation from the start. Dojo doesn't have that casual nature that jQuery has.

  3. My biggest complaint about Dojo is its documentation. As an engineer, I naturally look to the API for authoritative and complete documentation. Much to my surprise, I've had people tell me that is the authoritative source. That seems very misplaced to me. Even then, I've had situations where I couldn't find what I was looking for. For example, last year, it took me about a week to get a dnd component to work the way that I needed because it was slightly more complicated than the example in the sitepen tutorial (the only decent documentation that I could find on it).

    "On demand package loading means your pages load faster"

    Until you finish your RIA and realize that your initialization is taking forever because you're making tons of synchronous requests for includes.

    If you treat your includes, or in this case, `dojo.require` as you would when programming in a typical server-side language, you're going to be in trouble. The trade off to organizing classes into individual files (which you *should* be doing) is application initialization performance.

    There is a work around to this though, and that's using dojo's layer compiler. Just be cognizant of this ahead of time when you're designing your application and publishing process, because working it in after the fact is a PITA (as I have just learned from experience).

    However, all of that being said, the include system is definitely something that sold me and keeps me using Dojo.

    If there's any lesson that I would provide, it's to acquaint yourself with the following functions:


    For me, the main benefit of Dojo is that it is a programming library, and not just a DOM toolset. Get cozy with these methods and your code will get farther than it could with entire other libraries.

  4. I agree with you on the documentation Justin, I've had several occasions where my scenario was just a bit more complex than an example and spent hours and hours trying to figure it out. The good thing is that you tend to learn a lot along the way, but if you're in a time crunch it's frustrating as hell. Hopefully that will improve over time as more people adopt it.

    Thanks for the list of functions, I agree that those are all extremely useful.

  5. As a java developer, I think dojo is a natural choice because its good readability code sintaxe.

    About documentation, I'm worked around it by examining dojo source tests folders.

    God bless you all!!!

  6. The problem with Dojo is that it's bloated and has lot's of errors in it. But the api is real nice. I would like to see a really fast small subset of dojo which is absolutely errorfree. Then i would use it all the time. If you don't like libraries you can always write pure js - which is actually really good around 2011..