Installation

Before You Begin

The Dojo Toolkit Module requires that you are running Drupal 5.x. This module was developed and tested on Apache 2, PHP 5, and MySQL 5 in a Linux environment. It has not been tested on any other configuration, so consider yourself warned.

Downloading the Module

You can download the latest version from the main Dojo Toolkit Module page. The file is a tar.gz archive and should be a snap to extract. To extract the file from the command line, run the following command:

tar -xvzf dojo_toolkit_module-5.x-X.X.tar.gz

Once you have extracted the archive, there will be a directory called "dojo". Put the "dojo" directory into the /sites/all/modules directory or /sites//modules directory. You can also put in the /modules directory, but this is not recommended since it makes upgrading Drupal a pain.

Enabling the Module

Once the files are in place, log into Drupal and navigate to:

• Administer > Site building > Modules

Scroll down to the "Other" modules section, click the "Dojo Toolkit" checkbox, then save the configuration.

Installation Complete! Now what?

For starters, take a tour of the instant benefits of the Dojo Module. Then you can dive into configuring the module to better suite your needs.

Battle of the Toolkits

The Hammer

Drupal chose jQuery as their Javascript toolkit of choice to handle those neat collapsible panes and check all boxes. It does the job, but simply Dojo is a better. Visit the Why Dojo? page over at the Dojo Toolkit's site for more info.

The Sledgehammer

While a hammer might get the job done, sometimes a sledgehammer can get the job done better. Dojo is like jQuery, but has a lot more stuff.  Dojo can do all the animation, event handling, and Ajax stuff, but it also has a 2D drawing library, offline storage, a custom build system, and much, much more.

Dojo and jQuery can coexist at the same time, but the problem is file sizes, transfer and load times, and memory usage. If you want to use the Dojo Toolkit to code something in a module or theme you are developing, why load an extra 45KB of Drupal and jQuery Javascript code?

Giving jQuery the Heisman

By enabling the Dojo Toolkit Module, most places that use jQuery have been replaced with Dojo code. This way, only the Dojo files need to be loaded and thus the page will load faster. If a non-core module requires an external script that uses jQuery, then jQuery will be automatically loaded.

For a full tour of the jQuery replacements, continue on to the Tour of Features.

Tour of Features

Supercharged Editing

The Dojo Toolkit Module will replace the old boring with textarea fields with new boring textarea fields, but the new ones have a link to enable the Dojo rich text editor.

Enabling the editor will drop in the editor with a toolbar full of goodies to make entering content easier.

The editor can be customized by defining an editor profile which is discussed in the configuration section.

Collapsible Panes

In the spirit of removing the need for jQuery, the collapsible panes are now written using Dojo.

Auto-complete Fields

Finally, the auto-complete fields were rewritten to use Dojo's Ajax library.

Turning Off Dojo Form Elements

To keep the original jQuery form elements, you can uncheck the form elements on a per config profile basis.

More Features...

There are more features that will be described in the following sections.

Configuration

Dojo Toolkit Configuration Page

You can access the Dojo Toolkit Module configuration page by navigating to the following:

The first page of the configuration page is the Dojo Config and Editor Profiles. These allow you to customize the settings and associate them to an access roles.

Also accessible from this page is the Dojo Subversion Repository where you can check out the latest code.

Extending Drupal with Dojo

Where Should I Use Dojo?

There's lots of places you can put Dojo code:

• Use it in a page's content
• Use it in a module
• Use it in a theme
• Use it in a block

The uses for Dojo are virtually endless. As long as the Dojo Module is enabled, you don't need to worry about including the Dojo Javascript files or module paths.

Dojo 1.0

The examples on this page use Dojo 1.0.

Creating Dojo in Your Content

Dojo has some really neat widgets that you can use pretty easily. For example, let's have some fun with the FisheyeList widget. Create a page and for the content, enter the following:

<script type="text/javascript">
dojo.require("dojox.widget.FisheyeList");
</script>
<style type="text/css">
.dojoxFisheyeListItemLabel {
	font-family: Arial, Helvetica, sans-serif;
	background-color: #eee;
	border: 2px solid #666;
	padding: 2px;
	text-align: center;
	position: absolute;
	display: none;
	white-space: pre; 
}
.dojoxFisheyeListItemLabel.dojoxFishSelected { display: block; }
.dojoxFisheyeListItemImage { border: 0px; position: absolute; }
.dojoxFisheyeListItem { position: absolute; z-index: 2; }
.dojoxFisheyeListBar { position: relative; margin: 0 auto; text-align: center; }
.outerbar { background-color: #666; text-align: center; border: 1px solid #333; }
</style>
<div class="outerbar">
<div dojoType="dojox.widget.FisheyeList" itemWidth="50" itemHeight="50"
    itemMaxWidth="200" itemMaxHeight="200" orientation="horizontal" effectUnits="2"
    itemPadding="10" attachEdge="top" labelEdge="bottom" id="fisheye1">
  <div dojoType="dojox.widget.FisheyeListItem" id="item1" label="Item 1"
      onclick="alert('click on ' + this.label + ' (from widget id ' + this.id + ')!');"
      iconSrc="/sites/all/modules/dojo/MyBuild/dojox/widget/tests/images/icon_browser.png">
  </div>
  <div dojoType="dojox.widget.FisheyeListItem" label="Item 2"
      iconSrc="/sites/all/modules/dojo/MyBuild/dojox/widget/tests/images/icon_calendar.png">
  </div>
  <div dojoType="dojox.widget.FisheyeListItem" label="Item 3"
      onclick="alert('click on ' + this.label + ' (from widget id ' + this.id + ')!');"
      iconSrc="/sites/all/modules/dojo/MyBuild/dojox/widget/tests/images/icon_email.png">
  </div>
  <div dojoType="dojox.widget.FisheyeListItem"
      iconSrc="/sites/all/modules/dojo/MyBuild/dojox/widget/tests/images/icon_texteditor.png">
  </div>
  <div dojoType="dojox.widget.FisheyeListItem" label="Really Long Item Label"
      iconSrc="/sites/all/modules/dojo/MyBuild/dojox/widget/tests/images/icon_update.png">
  </div>
  <div dojoType="dojox.widget.FisheyeListItem"
      iconSrc="/sites/all/modules/dojo/MyBuild/dojox/widget/tests/images/icon_users.png">
  </div>
</div>
</div>
<div style="clear:both;"></div>

You may need to change the iconSrc paths to reflect your directory structure. Save the page and check out the neat FisheyeList! It should look something like this:

Using Dojo in a Module's Form

Probably the most powerful use of Dojo is to create widgets that can provide a better user interface than the simple form elements Drupal allows.

So, let's create a module called "dojodemo". The module is going to have a form where you enter your birthday. We are going to create 3 interations:

• Create the form with a standard input field and no Dojo stuff
• Add a Dojo date picker to the text field
• Modularize the date picker text field for reuse

First, let's create the .info file:

; /sites/all/modules/dojodemo/dojodemo.info
name = "Dojo Demo Module"
description = "Demo of the Dojo Drupal module"
version = "1.0"
dependencies = dojo

Now let's create the .module file:

<?php
// /sites/all/modules/dojodemo/dojodemo.module

// first we create our hook_menu
function dojodemo_menu($may_cache) {
  $items = array();
  if ($may_cache) {
    $items[] = array(
      'path' => 'dojodemo',
      'title' => 'Dojo Demo!',
      'callback' => 'drupal_get_form',
      'callback arguments' => array('dojodemo_myform'),
      'access' => TRUE
    );
  }
  return $items;
}

// version 1 of the form with no Dojo
function dojodemo_myform() {
  $form = array();
  $form['birthday'] = array(
    '#type' => 'textfield',
    '#title' => t('Enter your birthday')
  );
  return $form;
}

Enable the module and take a peek. At this point the form looks pretty boring.

Start of out-of-date info

Now, let's add a Dojo date picker widget. Most Drupal form elements support a '#suffix' argument and we'll use this to dump our Javascript code.

// version 2 of the form with Dojo
function dojodemo_myform() {
  $form = array();
  // note that in this version we have to give the form element
  // an '#id' so Dojo knows which form element to update
  $form['birthday'] = array(
    '#id' => 'birthday',
    '#type' => 'textfield',
    '#title' => t('Enter your birthday'),
    '#suffix' => <<<EOD
<div id="datepicker"></div>

<!-- need to override table styles defined by the theme -->
<style type="text/css">
  .datePickerContainer table { margin: 0; }
  .datePickerContainer td, .datePickerContainer th { padding: 0; }
  .datePickerContainer tbody { border: 0; }
</style>

<script type="text/javascript">
// tell Dojo to load the DatePicker widget
dojo.require("dijit.DatePicker");

// when the page loads, create the DatePicker widget and then
// connect an event to DatePicker that updates the text field
// when a date is selected
dojo.addOnLoad(function() {
  var w = dojo.widget.createWidget("DatePicker", {}, dojo.byId("datepicker"));
  dojo.connect(w, 'onValueChanged', function() {
    dojo.byId("birthday").value = w.getValue();
  });
});
</script>
EOD;
  return $form;
}

Save the module and reload the page and you'll see we have a cool date picker now. When you click the date, it will dump the value in the field.

But what if you want to reuse this on all pages? Not a problem. Drupal has an "elements" hook that gets fired every time a field is created on all pages. In order for this to work, we are going to add our own key to the form element called #dojo-datepicker. Any time a field with that key is created, it will create our data picker version. Below is the third version of our form and the elements hook.

function dojodemo_myform() {
  $form = array();
  $form['birthday'] = array(
    '#dojo-datepicker' => TRUE,
    '#type' => 'textfield',
    '#title' => t('Enter your birthday')
  );
  return $form;
}

function dojodemo_elements() {
  $type = array();
  $type['textfield'] = array('#process' =>
    array('dojodemo_process_textfield' => array())
  );
  return $type;
}

function dojodemo_process_textfield($element) {
  if ($element['#dojo-datepicker']) {
    // use the Dojo Module's helper function to require the Dojo
    // files this will ensure the DatePicker is only requested
    // once to load per page
    dojo_require_js('dijit.DatePicker');

    // get the element's id and if doesn't have one, generate one
    $elem_id = $element['#id'];
    if (!$elem_id) {
      $elem_id = 'temp_id_' . md5(mt_rand());
      $element['#attributes']['id'] = $elem_id;
    }

    // generate a unique id for our placeholder div
    $div_id = 'temp_id_' . md5(mt_rand());

    $element['#suffix'] .= <<<EOD
<div id="$div_id"></div>

<!-- need to override table styles defined by the theme -->
<style type="text/css">
.datePickerContainer table { margin: 0; }
.datePickerContainer td, .datePickerContainer th { padding: 0; }
.datePickerContainer tbody { border: 0; }
</style>

<script type="text/javascript">
// when the page loads, create the DatePicker widget and then
// connect an event to DatePicker that updates the text field
//  when a date is selected
dojo.addOnLoad(function(){
  var w = dojo.widget.createWidget("DatePicker", {}, dojo.byId("$div_id"));
  dojo.connect(w, 'onValueChanged', function() {
    dojo.byId("$elem_id").value = w.getValue();
  });
});
</script>
EOD;
  }
  return $element;
}

That's not so bad, was it?

End of out-of-date info

Dojo Module Helpers

There are 4 functions that the Dojo Toolkit Module defines that are really helpful:

dojo_add_js($data, $type)

This function is just like drupal_add_js(), except it forces it to be added to the header only. Additionally, it will check the current config profile and see if it should allow jQuery to be loaded. If you need to output some Javascript code or include a external script that references Dojo, you should use this function instead of Drupal's.

dojo_register_module_path_js($module, $path)

This functions allows you to tell Dojo where to find your custom namespaces. For example, say you have a module called "test" and you'd like to use a Dojo widget called "MyWidget", then you would do something like this:

// PHP
dojo_register_module_path_js('test', drupal_get_path('module', 'test'));
dojo_require_js('test.MyWidget');
// now you your Javascript you can do:
//   var myWidget = new test.MyWidget();

dojo_require_js($package)

This function will add the dojo.require() in the page header and will ensure that it is only added once. You will need to require all Dojo packages that you want to use, so this will come in handy.

dojo_create_widget_js($element, $type, $params = NULL)

This function will help create a widget and assumes that the $element is the placeholder. If the element does not have an ID, one will be generated. $type is the name of the widget to be created such as "DatePicker" or "cb1:MyWidget". $params is an optional argument that must be a simple value or array that will be serialized into JSON and passed into the widget.

This is meant to be used for simple scenarios. There are circumstances where you may need more control over the widget creation process and you will need to write your own function.

What next?

That's up to you! Be creative. Read code in the Dojo examples and tests as well as the code behind the Dojo Module. There's lots of good stuff in there, so have fun with it!

Creating a Custom Build

Build Profiles

The Dojo Toolkit Module provides two build profiles: one for CDN builds and one for local builds. In order to perform a custom Dojo build, you need to download the source from the Dojo Toolkit's website.

These instructions are intended for Linux/Unix like systems, but the concepts should work under Windows. The $ signifies the command prompt.

Downloading the Dojo source

In order to perform a custom Dojo build, download the source release from:

• http://download.dojotoolkit.org/release-1.0.0/dojo-release-1.0.0-src.tar.gz

Save the file in the Dojo Module's directory, then extract the files:

$ tar -xvfz dojo-release-1.0.0-src.tar.gz

Build Bug Workaround

Before running a build, there was a pretty big bug that shipped with 1.0.0 that needs to be fixed. Edit the file /dijit/form/ValidationTextBox.js. There are 2 instances of the text "\x00". Change both instances to "$_unset_$".

This bug has been fixed the day after 1.0.0 shipped, so new versions will work.

Building The dojo-module-local Profile

Go to the buildscripts directory:

$ cd dojo-release-1.0.0-src/util/buildscripts

Then execute the build:

$ ./build.sh profileFile=../../../profiles/dojo-module-local.profile.js \
   action=clean,release version=1.0.0-2.1 releaseDir=../../../ \
   releaseName=MyBuild

You can change the "releaseName" to whatever you like, but don't use spaces. When the build completes, go to the Dojo Module settings page and create a build profile. From the Dojo Build field, select your new build from the menu.

Building The dojo-module-cdn Profile

Go to the buildscripts directory:

$ cd dojo-release-1.0.0-src/util/buildscripts

Then execute the build:

$ ./build.sh profileFile=../../../profiles/dojo-module-cdn.profile.js \
  releaseName=delete-me action=clean,release loader=xdomain \
  xdDojoPath=http://o.aolcdn.com/dojo/1.0.0 version=1.0.0-2.1-xdomain

This will put the following files in the dojo-release-1.0.0-src/release directory:

• DojoModuleAdmin.js
• DojoModuleAdmin.js.uncompressed.js
• DojoModuleAdmin.xd.js
• DojoModuleAdmin.xd.js.uncompressed.js
• DojoModuleMain.js
• DojoModuleMain.js.uncompressed.js
• DojoModuleMain.xd.js
• DojoModuleMain.xd.js.uncompressed.js

Since we only care about the compressed .xd versions, we are interested in:

• DojoModuleAdmin.xd.js
• DojoModuleMain.xd.js

Due to limitations in the build system, you must manually add the requires
to these two build files. At the beginning of these files is an array of
provide()'s and we need to add the requires to the array. The requires are
different for each file.

DojoModuleAdmin.xd.js

Locate the following code which is actually on a single line:

depends:[
  ["provide","drupal.form.AutoComplete"],
  ["provide","drupal.form.Editor"],
  ["provide","drupal.layout.CollapsiblePane"],
  ["provide","drupal.DojoModuleAdmin"]
]

After the last provide statement, change it so it looks like:

depends:[
  ["provide","drupal.form.AutoComplete"],
  ["provide","drupal.form.Editor"],
  ["provide","drupal.layout.CollapsiblePane"],
  ["provide","drupal.DojoModuleAdmin"],
  ["require","dijit._Widget"],
  ["require","dijit._Templated"],
  ["require","dijit.form._FormWidget"],
  ["require","dijit.Dialog"],
  ["require","dijit.Tooltip"],
  ["require","dijit.Tree"],
  ["require","dojo.data.ItemFileReadStore"],
  ["require","dojox.collections.ArrayList"]
]

Don't forget to put a comma after the last provide statement. You'll want to
make those changes on a single line.

DojoModuleMain.xd.js

Locate the following code which is actually on a single line:

depends:[
  ["provide","drupal.form.AutoComplete"],
  ["provide","drupal.form.Editor"],
  ["provide","drupal.layout.CollapsiblePane"],
  ["provide","drupal.DojoModuleMain"]
]

After the last provide statement, change it so it looks like:

depends:[
  ["provide","drupal.form.AutoComplete"],
  ["provide","drupal.form.Editor"],
  ["provide","drupal.layout.CollapsiblePane"],
  ["provide","drupal.DojoModuleMain"],
  ["require","dojo.fx"],
  ["require","dijit._Widget"],
  ["require","dijit.Editor"],
  ["require","dijit._editor.plugins.AlwaysShowToolbar"],
  ["require","dijit._editor.plugins.EnterKeyHandling"],
  ["require","dijit._editor.plugins.LinkDialog"]
]

Don't forget to put a comma after the last provide statement. You'll want to make those changes on a single line.

After the requires have been added, move the DojoModuleAdmin.xd.js and DojoModuleMain.xd.js files to the "drupal" directory in the Dojo Module directory. You may delete the "release" directory in the dojo-release-1.0.0-src directory.

When the build completes, go to the Dojo Module settings page and create a build profile. From the Dojo Build field, select your new build from the menu.