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:
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.
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:
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.
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 api.dojotoolkit.org 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.
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.
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.
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.
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.
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.
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 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.