Using Dojo with XULRunner

I recently started porting one of my previous research projects, which was originally implemented as a browser extension to Firefox, into a XULRunner application. The advantage of moving to XULRunner is that I will hopefully be able to reuse a bunch of my Firefox extension code, but at the same time I'm hoping to give a lot of that code a revamp. One of the ways that I want to do that is to adopt a better object-oriented approach for my code (or just any object-oriented approach for that matter!), and after not a lot of convincing I decided to go with the object model provided by the Dojo Toolkit.

If you're at all familiar with Dojo, you'll know that it's primarily a toolkit for building browser-based web apps. So how do I go about using it in a Firefox extension or as part of a XULRunner app? It's actually pretty straight-forward, but there's not a lot of documentation. For that reason, I thought I'd throw together this quick blog post both for my own memory and maybe to help out other people who try to do the same thing in the future.

Step #1: Create a custom Dojo build

There are a bunch of resources for how to do this generally, but I'll describe the process quickly. What's most important to know are the few parameters that you'll need to put into your build profile to generate a build of Dojo that will work.

First, download the Dojo SDK. As of today, Dojo downloads are available at http://dojotoolkit.org/download/. Scroll to the bottom of the page to find the SDK, and download either the .tgz or .zip versions depending on which compression method works best for you.

Now we create the custom build. To do this, you need to create a build profile. Some sample build profiles are included in the SDK that you downloaded at <dojo src dir>/util/buildscripts/profiles.

I started by copying the Rhino profile in rhino.profile.js to another file, such as xulrunner.profile.js. In your new build profile, make the following changes:

• Change hostenvType = "rhino" to hostenvType = "ff_ext".
• Modify the prefixes section as needed to include the Dojo extensions that you need. I personally kept dojox but removed shrinksafe from the Rhino profile. You might want to add other prefixes, though most of the other libraries (such as dijit) have to do with creating widgets and that capability seems less useful in the XULRunner environment.

Once you've got your build profile finished, you need to create the custom build. The command line for this depends on what you named your build profile in the previous step. If you used the name that I specified above, then the command line would be:

<dojo src dir>/util/buildscripts/build.sh profile=xulrunner action=release

This will create a new release directory at the same level as your dojo src directory.

Step #2: Add the Dojo code to your XULRunner project

How you do this depends a bit on the structure of your XULRunner project. Assuming you're creating a normal app and using the standard conventions, you should have a content directory in your XULRunner project which contains a XUL file (let's call it main.xul) that defines the user interface for your main window.

First, copy the dojo release directory that you created in step #1 inside your content directory. I named this directory dojo, and in my configuration the dojo.js file was located at content/dojo/dojo/dojo.js. The remaining description assumes these locations, so make changes as necessary for your application.

To enable Dojo for your project, add the following lines near the top of the main.xul file:


<script>
    // Specify the name of the package (from chrome.manifest)
    var packageName = "package";
   
    // Determine the current locale so that we can pass it to Dojo
    // Code taken from:
    // https://developer.mozilla.org/En/How_to_enable_locale_switching_in_a_XULRunner_application
    var chromeRegService = Components.classes["@mozilla.org/chrome/chrome-registry;1"].getService();
    var xulChromeReg = chromeRegService.QueryInterface(Components.interfaces.nsIXULChromeRegistry);
    var selectedLocale = xulChromeReg.getSelectedLocale(packageName);           

    // Create the Dojo configuration structure
    var djConfig = {
        isDebug: true,
        locale: selectedLocale,
        baseUrl: 'chrome://highlightxr/content/dojo/dojo/'
    };
</script>
<script src="chrome://highlightxr/content/dojo/dojo/dojo.js" type="application/x-javascript"/>

Note that internationalization is important to me, so I added some extra code to get the current locale from XULRunner and pass that value to Dojo. That may not matter to you, in which case you can just manually set locale in djConfig to "en-US" or whatever the appropriate string may be. 

You'll also need to insert your own package name in the snippet above. This is the name that you specified in your chrome.manifest file.

I hope that helps!

If you need any help with Dojo, I suggest checking out their web site or looking at Dojo: The Definitive Guide or Mastering Dojo: JavaScript and Ajax Tools for Great Web Experiences.