Dojo Builder Documentation

The page contains the documentation for the various features of the Eclipse based Dojo Builder application.

Dojo Builder is divided into four Views.

• Ant Builder Control is placed at the top of the window. It can be used to specify an Ant build file to import, and to perform the build by clicking the Build button
• Dojo Controls is the primary view by which you will control Dojo Builder. It contains the functionality for checking code out from the source code repository and configuring it.
• Ant Properties lists all the properties available on the Ant project. Most people can safely ignore this view, unless you want to manually edit Ant properties. However, the Dojo Controls should generally be sufficient to take care of whatever Ant property manipulation that is necessary.
• Ant Targets lists all the targets available on the Ant project. As with the Ant Properties view, most people can ignore this, unless you want direct control over which Ant targets are executed. Unless you really know what you're doing, this is not advised - just use the Dojo Controls view.

Checking out files from Dojo's source repository

In the Dojo Controls view, select a build number from the SVN Repository combo box. Choose a folder to store the file in the Svn Dir text box. Finally, click the Sync Repository button. You'll see a progress dialog showing the files being downloaded.

Importing an Ant build file

Dojo Builder acts as a GUI frontend over Dojo's existing Apache Ant-based build process. Therefore, you have to import an existing Ant build file (usually called build.xml). You have two options here, either to choose the default Dojo build file, or choose one that has been customized for Dojo Builder.

For the builds 0.4.1 and earlier, check the Use customized build source. This is necessary as earlier build files used problematical Python scripts, and these had to be removed. For builds after 0.4.1, choose Use SVN as Build Source to use the standard Dojo build file.

When you choose one of the build files, you'll be given the option to import the build file. This instantiates all the options available to you, reading them from the Ant build file. At this point, the Ant Properties and Ant Targets are populated. These can be safely ignored, and are really just for power users who want direct control of the build process. Instead, use the controls provided in the Dojo Controls view.

If you have checked out the Dojo source files without using Dojo Builder, then you can choose to use it's build.xml file using the Build File text box in the Ant Control view at the top of the application, and click the Import button.

Performing A Build

Once you've imported a build file, it is now time to create a build. To perform the simplest type of build, Choose release from the Target Set combo box. Choose a build profile to use from the Build Profile combo box. ajax is a common choice, which gives you the communication and event code. Choose a folder you would like to place the resulting files in using the Build Dest text box. Click the Build button in the topmost view.

Compressing Files

Dojo Builder can perform two different types of JavaScript compression. The standard Dojo compression using the Mozilla Rhino JavaScript engine. Select this method of compression by checking the Quick Compress check box. Super compression using the Packer compressor. This makes far smaller JavaScript files, but also takes far longer to execute. Select this method of compression by checking the Super Compress check box. You also have the option of compressing the entire set of Dojo JavaScript files, rather than just the dojo.js file. To do this, check the Apply to all files checkbox.

Creating/Editing Profile Files

In order to define which JavaScript files become build into the dojo.js file, you must define what is called a profile file. The default Dojo process requires that you write a JavaScript file for this, however Dojo Builder has a user interface that takes care of this.

First, if you haven't already got a build of Dojo checked out from the source repository, check one out using the instructions here

Import a build file, using the instructions here

To create a new profile, click the New button beside the Build Profile combo box. This launches the Profile Builder.

The leftmost list, with the label Files available for inclusion, lists all the files that you can choose to add to a profile. Double click on entries in the list to select them and move them to the list with the label Files to be included in the profile.

To generate a preview of the dojo.js file that will result from this profile, click the Update Preview button. After a short wait, the resulting file will be shown in the Preview dojo.js text box. This file can be saved bly clicking the Save generated preview button.

The profile can be saved by giving it a name, then clicking the Save Profile button.

Editing an existing profile

To edit a custom profile, open the preferences dialog by clicking Window->Preferences->Ant Builder->General Dojo Settings, choose the custom profile file and click the Edit Profile button. This will launch the Profile Builder and allow you to edit the profile.

Using the preference page, you can also import hand-written profile files, create new profiles, and delete them.

Working with Custom modules

If you have created new modules (namespaces) that can be used with Dojo, and want to be able to build them into the dojo.js file, then you have to register them with Dojo Builder. To do this, open the preferences page by clicking Window->Preferences->Ant Builder->External Dojo Modules. Now enter the module name and the path to the module's base folder on your hard drive, then click the Add and OK buttons. Now the next time you open the Profile Builder, you will have the option to include files from your custom module in the Dojo Build.