Dijit Tree with Multi State Checkboxes 1.7

Note: This article has been superceded by the The new Dijit CheckBox Tree. The interim 1.7 release referred to in this post is therefore no longer available for download.

More than 2 years after I posted the first version of the dijit tree with multi state checkboxes for dojo 1.4,  and after 20,000+ downloads it was time to get an updated version out.

Actually, it wasn’t until dojo 1.6/1.7 was released that I started to get feedback that the old version wasn’t working properly any more.

Well friends, the 1.7 tree is here with full support for the claro theme and I believe some nice additions. See the picture below.

Tree - claro

Issues reported

The issues reported using the Dijit Multi State Checkbox Tree version 1.4 with dojo 1.6/1.7 can be summarized as follows:

  1. Updates to checkboxes could not be seen until one would hover over the checkbox.
  2. The properties ‘branchIcons’ and ‘nodeIcons’ no longer worked.
  3. No support for the dojo 1.5 claro theme.
  4. Firebug reported the use of deprecated functions.

I’m happy to report, all of the issues have been resolved.

In addition, some people asked if there was any easy way to change the checkbox state programmatically. But then again, others asked if I could write their entire application using my dijit tree because they liked it so much.

I will follow this blog up with a more detailed explanation of the changes required to get everything working again for dojo 1.7. Most of the time went actually into setting up my environment again, you known, getting the latest and greatest version of every tool and then getting everything to work again. All-in-all it took about a day to get every updated and back to normal again. But here is just an excerpt of some of the reasons causing the problems:

As it appears the dojo team had decided to adopt the new AMD technology which stands for Asynchronous Module Definition. Starting with dojo 1,6 an entire refactoring was kicked off which, as far as I understand, should lead to the new and improved dojo 2.0 platform. The implementation of AMD introduced new language structures and as a result of the refactoring new feature were added and of course others got dropped or some behavior slightly changed.

If you are interested in reading more about AMD, and who isn’t right? checkout the following sites:



A good exercise to see how well your code holds up in relation to dojo 1.6/1.7 is to download the latest version of firebug (still the best javascript tool available, don’t leave home without it) and run dojo 1.7 in debug mode. Most likely you will get some warnings regarding the use of deprecated methods/functions.

What’s new in the 1.7 Checkbox Tree

As mentioned before, some people asked if there was an easy way to change the checkboxes programmatically. Well, if you are into dojo everything is simple, just do a fetch() on the model store and call the updateCheckbox() method for each store item with its new state.

Ok, to make is even simpler, version 1.7 has two new methods called check() and uncheck() which allow you to do just that. Both methods take three arguments:

  1. Query
  2. Callback
  3. Scope

The query argument can be either a string or query object. The optional callback argument is a function which is called on completion with the number of store items that matched the query and the number of store items that matched the query and actually changed state. Finally, the optional scope argument specifies the context in which the callback function is to be executed. The release notes have several sample of the new methods. As an example:

myTree.model.check( { name: "John" }, notifyMe, this );

The store will be queried for every item whos name property equals “John” and if the associated checkbox is unchecked it will get checked. How easy is that…

In addition, a new property was added to the tree model which allows to make checkboxes associated with branches read-only.

Download the latest version

The latest AMD version of the Dijit Tree with Multi State Checkboxes can be downloaded here.

And for those who are wondering: “will the 1.7 tree work with dojo 1.6” the answer is: NO, a quick test reveiled that the new language structures required for AMD support are not available in 1.6.

Dojo/Dijit Tree with Checkbox



The new and fully AMD compliant version of the Dijit CheckBox Tree can be found HERE. Please refer to the updated version going forward.

Like so many I have been looking for an implementation of a of Dijit tree structure with checkboxes but was unable to find one or at least one that provided the functionality I was looking for so I decided to create one myself. This document describes all the steps required to create a fully functional tree similar to what you are used to see with many software installation packages. I will try to keep things simple and at the same time try to explain some of the dojo and dijit fundamentals when needed. However, I do not claim to be a dojo expert (just a disclaimer).


Before we get started I want to define the functional requirements for our tree. I know, what do we need requirements for you say, let’s just start hacking. Well in order to set some goals and to make sure everybody is on the same page so I’ll go ahead anyway.

Function Requirements

The functional requirements I wanted to implement are as follows:

  • The tree must be based on the dojo framework and the digit tree in particular.
  • It must be able to support both trees with and without checkboxes so I only need one widget going forward.
  • The tree must be able to maintain a parent-child checkbox relationship. What I mean by this is that for example if a parent checkbox is checked all child and grandchild checkboxes will automatically be checked as well, or if one of the children is unchecked the parent and potentially its parent is unchecked automatically.
  • I want to be able to specify the initial state (checked/unchecked) of a checkbox but I don’t want to be forced having to do this for every checkbox. For example, if all checkboxes have a default state of ‘checked’ with the exception of only a few, I want to be able to define the default state once and only deal with the exceptions.
  • I want to be able to define if the root node of the tree requires a checkbox. (more on the root of a tree later).

Well, if that’s what you have been looking for too, stick around and continue reading if not Oh well go have fun with what you are doing.

Step 1 – The Development Environment

In order to get started you need to make sure you have version 1.3.2 of dojo installed on your system. I would recommend to get the source version of dojo because it will include some very useful utilities. Dojo can be downloaded from:


The file you will be looking for is: dojo-release-1.3.2-src both zip and tar versions are available. All source samples in this tutorial are based on dojo version 1.3.2 and will NOT work with version 1.4. I picked version 1.3.2. because it is currently the most used version. I will address the relevant differences between dojo 1.3.2 and 1.4 with regards to the dijit Tree at the end and yes I do also have a version available that does work with dojo version 1.4.

You are also going to need some sort of http server, I’m not going to make any recommendations but I’m using the latest version of Apache. Apache by the way is used by many prepackaged web servers like WAMP or ZendServer CE.

Second, you will need to create the appropriate directory structure to follow this tutorial. If you don’t you will have to make the necessary changes while reading along. The directory structure I use looks as follows:

Directory Structure

I renamed my dojo directory from ‘dojo-release-1.3.2’ to’ dojotoolkit’, If you don’t have the \dojotoolkit\util directory you did not install the dojo source version, just to make sure, it is not required for this tutorial. Beside the standard dojo directory structure I created two additional directories call ‘datastore’ and ‘tmpdir’. The datastore directory will hold the Json source file we will be using for this exercise and can be downloaded from: http://dojocampus.org/explorer/#Dijit_Tree_Basic
Next, after installing your web server point your web server docroot to the html subdirectory, I would recommend to configure a virtual server , something like this:

Listen 8080
<VirtualHost *:8080>
DocumentRoot “D:\MyServer\html”
<Directory “D:\MyServer\html”>
Options All +Indexes +FollowSymlinks
AllowOverride all
Order allow,deny
Allow from all

If you are not familiar with Apache checkout the Apache httpd website for more information: http://httpd.apache.org/ or if you just need info on virtual host configuration http://httpd.apache.org/docs/2.0/vhosts/.

Ok, now that we have most of the basics out of the way and our system setup it is time to start talking about the standard dijit tree implementation. The latest installment of the dijit tree is implemented using the Model-View-Controller architectural pattern, the general idea here is to isolate any logic from the input and presentation. I’m not going to spend any time on the MVC pattern, there is enough MVC stuff on the web if you really want to get into it you could start at: http://en.wikipedia.org/wiki/Model-view-controller

The most important part you need to know is that dojo uses the following classes to implement the MVC pattern:

Model \html\js\dojotoolkit\dijit\tree\ForestStoreModel.js
View \html\js\dojotoolkit\dijit\Tree.js
Data \html\js\dojotoolkit\dojo\data\ItemFileReadStore.js

In this tutorial we will follow the same MVC model and again if you are not familiar with it I think you will start to like it once you see what it will do for us and our checkbox tree. The final result will show there is relatively little we need to do to the original dijit tree. Ok, its time to start get some coding going.

In case you can’t wait until the end of the tutorial, you can download the fully documented source files from here.

In STEP 2 we’re first explore the default dijit tree and then start our project.