Dojo Toolbox First Look

By on July 8, 2008 8:50 am

In the middle of May, we were given a mission: create a speedy, offline API documentation viewer and a graphical Dojo build tool. Here we are at the beginning of July, and the result is the Dojo Toolbox 1.0. This article is a first look at this new application.

Adobe® AIR™ has received a good deal of press attention over the past few months, and with good reason. It provides a way for web application developers to use the skills they already have to create cross-platform desktop applications. Starting with Dojo 1.1, Dojo has included support for AIR out-of-the-box. This made AIR an ideal target environment for the Dojo Toolbox.

The easiest way to get the Dojo Toolbox is from SitePen’s Dojo Toolbox page. There’s a widget on that page that can download the Adobe AIR runtime and the Dojo Toolbox quickly, and with a minimum of effort.

Installation of an AIR application is a breeze. When you double click the DojoToolbox.air file, you will see a security verification window like the one below:

Dojo Toolbox Install Security Check

Unlike a web application, AIR apps are able to access the files on your computer and have unrestricted access to the internet. For that reason, AIR applications are digitally signed so that you can decide if you trust the application’s publisher with this extra level of access.

We have signed the Dojo Toolbox with a certificate assigned to the Dojo Foundation by Thawte. So, installation of the Dojo Toolbox reflects that the publisher’s identity has been verified. The Dojo Toolbox requires access to your local file system, in order to be able to run builds, and to the internet in order to check for updates and to download the API documentation.

After you accept the security aspects of the installation, AIR asks you where you would like to place the newly installed app, presenting a default that is appropriate for your platform.

Dojo Toolbox Install Location Dialog

One thing you might already have noticed about AIR: its appearance is not the same as a native application. Though AIR apps have many of the capabilities of a native application, the way they are rendered is very much the same as a web application. If you imagine the incredible variety of appearances in web applications, you can imagine the diversity we’re likely to see in AIR applications.

The install process is easy, but updates are even easier. The Dojo Toolbox can check for updates for you and download and install an update with just a couple of clicks.

Unless you unchecked the checkbox on the installer screen, the Dojo Toolbox will launch as soon as it’s ready.

The Screencast

If you’d like to see, rather than read about, the Dojo Toolbox you can either install it for yourself, or take 5 minutes and watch the screencast:

The Dojo Toolbox Application

When you launch the Dojo Toolbox, you’re greeted with a small “launcher” window:

Dojo Toolbox Tool Launcher Window

You’ll notice right away that it’s not a native-looking window. That’s another nice feature of AIR: you can create “chromeless” windows that have their own distinctive look and feel.

The Dojo Toolbox is designed to be unobtrusive, so you can leave it sitting around and reach for it whenever you need it. You can drag the launcher around your desktop, and it will remember its position for the next time you launch it.

If you click on the Dojo logo, the launcher will expand so you can access the available tools. Currently, there are three: the API Viewer, Builder and Resources.

Dojo Toolbox Launcher Expanded

Let’s take a closer look at them in the order in which they’re presented.

API Viewer

The first time you launch the API Viewer, it will download the Dojo API documentation zip file and then uncompress it. This file is a version of that has been reformatted specifically for the Dojo Toolbox.

When the API Viewer is ready, you’ll get a view of the Dojo API documentation that is similar to the one on the web.

Dojo Toolbox API Viewer

The navigation on the left allows you to easily find a module within the Dijit, Dojo and DojoX packages. Not surprisingly, choosing a module on the left will give you the docs for that module on the right. At the top of the window, there are left and right arrow buttons. Those are like the back and forward buttons in your browser.

One feature that you’re likely to use all the time is the search box at the top. Type in the name of a Dojo function (for example dojo.forEach) or the words that you’re looking for and you’ll get a list of matching help topics.

API Viewer Search Results

All of the topics that match any of the terms you enter will be displayed, sorted with a simple scoring mechanism. You can also search for topics that do not include a particular word by putting a “-” before the word.

The API Viewer gives you amazingly fast access to the wealth of information available in the Dojo API documentation. Even on an airplane!

Introducing the Builder

The Builder tool is the most complex tool in the current Dojo Toolbox. It has many options spread out over three tabs.

Dojo Toolbox Builder

You can productively use the Builder without touching most of those options. The goal with the Builder is to provide an easier way to take advantage of the power of Dojo’s build system, which was previously available only as a command-line tool.

Dojo’s build system can dramatically reduce page load time by cutting the number of requests that the browser needs to make and reducing how much data is sent on each of those requests. Internet Explorer has a default limit of just two simultaneous requests, which means that reducing the number of requests required can have a huge impact on page load time.

To use the Builder, there are just two things you need to provide it: the top directory of the copy of Dojo of which you wish to make a build, and the location of a profile file. Assuming that you already have a copy of Dojo that you have downloaded previously, you can click the “Select Directory…” button to choose the directory containing your Dojo. The Builder will remember that choice so that you can select it next time.

Next, you need a profile file. The profile describes how JavaScript modules will be collapsed into separate JavaScript files. You can learn more about creating profiles from the online Dojo Book. Once you have a profile available, you can click the “Select File…” button to select that profile for building. As with your Dojo directory, the Builder will remember which profile was last used for building, so that you can easily grab it again.

And that’s all you absolutely have to choose before you can run a build. Click the “Build It!” button, and you’re off to the races.

Running a build in the Dojo Toolbox

While the build is running, you will see a progress meter with a short description of what is happening. In addition, you get a log window that displays the log output of the build. That is the same log output you get when running the Java build.

The amount of time it takes to run a build in the Dojo Toolbox is comparable to how long is spent on a build using the traditional Java-based build tool.

Speaking of the Java-based build tool, the mysterious-sounding “Command” button will give you the command line options to use with the Java build tool.

Dojo build tool command line options

That means you can use the Builder as a graphical front end to the command line build tool, making it easy to run automated builds.

Build Options

Dojo’s build system can handle sophisticated needs. With so many options available, it can be difficult to know what each one is all about.

Luckily, help is built in to the Builder tool. You’ll notice that many of the field names are underlined. If you click those underlined headings, you’ll see a Tooltip that describes what that setting is for.

Builder Option Tooltip

The text for these Tooltips is from the command line build tool help, so these will always stay in sync.

I want to mention a very important option: the ShrinkSafe option. ShrinkSafe is Dojo’s tool that compresses JavaScript files by eliminating excess whitespace and removing comments. ShrinkSafe is “safe”, unlike some other JavaScript compression tools, because it works off of the syntax tree produced by a customized version of Rhino, the JavaScript engine written in Java. Rhino is not available within the AIR environment.

As of this writing, the only ShrinkSafe optimization choice available is “none”. We left the option on the page, however, because we are actively working on providing two options for using ShrinkSafe with the AIR-based build. The first is “Remote ShrinkSafe”, which will use the ShrinkSafe web service to compress the files. We also recognize that many people might not want their custom JavaScript files being passed across the Internet. For this reason, we are also working on a “Local ShrinkSafe” option which will use a small Java-based service running on your computer for the compression.

The Resources Tool

The third tool in the Dojo Toolbox is called, simply, “Resources”.

Resources Tool

Resources provides you with a consolidated, quick click-and-go list of some amazingly useful sources of knowledge and help for working with Dojo. We’ll be keeping this resource list up-to-date as new articles are published and new tools are created.

After 1.0

We’re very excited to be offering this new, simple way to help you get more out of Dojo. And 1.0 is really just the beginning. We have tons of ideas for new tools and features for the Dojo Toolbox, and I’m sure you do, too.

Download the Dojo Toolbox today to take advantage of the great features today. Then, join us on the Dojo Toolbox mailing list and tell us how we can make this open source application even better.

Adobe, the Adobe logo and Adobe AIR are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.


  • David

    The API Viewer looked promising but when I try and load it it gets to “loading resources” and just hangs after that. Then it just starts sucking up CPU and RAM and I have to kill the process.


  • Hi David,

    Sorry to hear about that. Two questions: 1) what platform are you using? and 2) how long did you wait?

    It can take a couple of minutes to completely unpack the file (but not more than a couple of minutes, I should think).


  • Michael Schall

    I’m trying to sign up for mailing list and get a message box:

    A username and password are being requested by The site says: “SitePen Web Projects”



  • @Michael Thanks for the report! It turns out that the listinfo page was open to the public, but the subscribe form URL was not. This is fixed, so subscribing should no longer be a problem!

  • Pingback: Blue Sky On Mars » What I’ve been up to: The Dojo Toolbox()

  • Pingback: Continuing Intermittent Incoherency » A Lovely Box For Your Toolkit()

  • Pingback: Dojo Toolbox - endlich eine Offline API-Doku zu Dojo |

  • Ha! “Error, Adobe AIR is not available for your system”

    My system? OpenSuse 11.0 with FireFox.

    So, is Dojo now sponsored by Microsoft?

    Regards, Jules.

  • @Jules: The Mac and Windows versions of AIR are complete, and Adobe is close to releasing a production version for Linux… hopefully very soon.

  • Vaibhav

    I am too much eager to use dojo toolbox but when i download it i got the .air file. What are the minimal requirement to run the dojo toolbox.

    Thanks in advance

  • Hi, Vaibhav

    What platform and browser are you using?

    On the main Toolbox page,, there is an Adobe-provided Flash widget that will install both AIR and the Toolbox in one easy step for you.

    You can also get Adobe AIR separately from here:

    Once you’ve installed that package, double-clicking the .air file should install the package for you.


  • Vagh

    Is it possible to download the updates ZIP separately and then connect it with AIR application?

  • @Vagh

    I’m assuming you’re talking about the documentation zip file? That gets updated automatically, and trying to simulate what that update process does would not be easy (because it stores some metadata about which version of the documentation you have).

    There have not yet been updates to the documentation. (Expect that when Dojo 1.2 comes out.)


  • Vagh

    Thank you for the response, Kevin. Yes, I’m talking about the documentation which is downloading when running API tool for the first time. In fact I need to download one time and use it in 3 different computers with the same installation of the toolbox. Is it possible? Where is downloaded data stored on a hard disk?

  • The data is unpacked into the “Application Storage Directory”, and the URL of the download file is stored in __DOJO_STORAGE/apiviewer/version in there. If you copy the apiviewer directory and the __DOJO_STORAGE/apiviewer directory over then it should work.

    The “application storage directory”is platform specific and also has a key embedded in its name. On the Mac, for example, it’s in ~/Library/Preferences/org.dojotoolkit.DojoToolbox.SOMEKEY/Local Store

    (Obviously, it wasn’t designed to be used on multiple computers like that…)

  • Lloyd Burgess

    I have just installed the toolbox on a Windows XP machine. The toolbox looks great however I have a problem …

    As mentioned above, the data is unpacked into the “Application Storage Directory” (under C:\Documents and Settings\\Application Data).

    I have a profile storage limitation (imposed by my company) on my system and so cannot store much data under …\Application Data.

    Can I change where the application storage directory is e.g. to “E:\OtherAppData” ?

    Thanks in advance

  • Hi Lloyd,

    It sounds like the only way to change it would change the location of your Application Data for all apps, which is not desirable.

    I’ve opened a ticket in our tracker to allow the user to specify a location for the docs when initially downloading them. I believe we may be able to add that feature in the near term along with some other API viewer changes we’re making to accommodate Dojo 1.2.


  • By the way, some information about AIR’s application storage directory location is here:

  • Lloyd

    Great – thanks Kevin.

  • Dani Estevez

    Nobodoy noticed a problem with Adobe AIR last update??

    Our guess is that Dojo Toolbox CSS seems to show incorrectly with this automatic update by Adobe; our problem here is quite important, since we use the “Custom Dojo Builds” option frequently and it’s impossible now !! “Build it” button is hidden behind the form fields and we can’t run the dojo build anymore.

    Can anybody help me with this?

  • Supun

    Hi… I’m from Sri-Lanka. I’m quite new to dojo. We have a project about dojo and I have download the toolbox yesterday. Can u tell me plz what can do from this toolbox?? And my dojo codes aren’t work properly.. How i import dojo to my html.

  • Ram

    Is Dojo 1.4.0 documentation supported in API viewer ?

  • AngeloP

    I’m not able to setup toolbox under windows 7
    paths :
    I chooose

    Select Base Directory [C:\Program Files\DojoToolbox ]
    Specify Profile [ ]

    I’ve not founded any helps. Your movie sample is under Mac
    The validation message for every fields is “Directory must be a valid..”
    There is an help about settings under windows ? THANKS

  • Pingback: Way Too Much Information About Randy’s Thoughts on Design » Toolkits, Frameworks, and Libraries, Oh My!()