The new Dijit CheckBox Tree !

Introduction

A New Project

A new project comes with a new directory layout. Please note that the cbtree directory is located at the same level as dojo and dijit. This is important as the included demo applications and unit tests all use relative paths when referencing dojo and dijit modules.

If you haven't done so already and you want to setup a local HTTP server, the instructions can be found here. However, instead of downloading dojo 1.3.2 as recommended you need to get the latest dojo toolkit instead.

When migrating

If you are planning to migrate from the original Dijit CheckBox Tree to the new AMD implementation please refer to the documentation for a detailed description of all available properties. Also see the New Properties section for additional information.

What's New

Following is a summary of some of the new features and enhancements, the table is by no means a complete overview. Please refer to the CheckBox Tree documentation for more details.

Design Principles

In trying to understand what benefits AMD brings to the table and how to leverage it I decided to redesign and, as a result, rewrite the entire Dijit CheckBox Tree. As I mentioned before, AMD is, among other things, about loading only what you need without having implicit external dependencies. Therefore the practice of declaring multiple modules in a single source file is strongly discouraged and as a side effect, it truly creates cleaner code. What about the additional overhead of loading all these smaller modules you ask? Well, I haven't seen any HTTP 1.0 server in the last couple of years so I guess you won't notice the difference. Keep in mind you load a lot less code to begin with then you would have with previous dojo implementations, meaning a lot less network I/O. In addition, loading modules cross domain using a CDN, for example, has become a piece of cake.

Code Separation

Originally all modules, that is, CheckBox, CheckBoxStoreModel, _CheckBoxTreeNode and CheckBoxTree were all included in a single source file. With the new implementation however, they have been split into separate files and turned into anonymous classes. In addition, the CheckBox Tree now comes with its own dedicated store models which no longer inherit from the original dijit tree models.

Simple Accessors

Starting with dojo 1.6 simple accessors like get() and set() have been made available for all dijit widgets. These accessors are now also available for the NEW CheckBox Tree, Tree Styling API and Store Model API. For example, setting or getting the checked state of a tree node is as simple as:

nodeWiget.set("checked",true)
nodeWiget.get("checked")

New Properties

Even though the project is still referred to as The Dijit CheckBox Tree, the reality is that with the new implementation any widget capable of presenting a so-called checked state can now be used. For example, when creating a CheckBox Tree you can, by means of the tree widget property, specify a toggle button, or any other widget for that matter, to be used instead of the default checkbox.

The example on the left demonstrates the use of the ToggleButton widget. Because of these new capabilities the CheckBox Tree store models no longer refer to a CheckBox state, instead they refer to the more generic Checked state.

Therefore all properties formerly prefixed with checkBox are now simply prefixed with checked like: checkedAll instead of checkboxAll. In addition, new properties have been added while others have been removed or have moved from the tree to the model to better decouple the tree from the model.

If you are planning to migrate from the original Dijit CheckBox Tree to the new implementation please refer to the documentation for a detailed description of all available properties including many code samples how to use them.

Tree Styling

The AMD CheckBox Tree comes with a separate Tree Styling API which allows the user to apply styling to either the tree as a whole or set styling properties on a per data item basis using simple accessors like get() and set(). Styling can be applied to the tree node row, icon or label.

In contrast to the standard dijit tree, which applies tree node styling using callback functions, the Tree Styling API offers the ability to programmatically set styling properties. For example, to change the label styling for a given data item simply call:

tree.set("labelStyle",{color:red}, item)

To set an icon, or a set of icons, for a for a given data item call:

tree.set("icon", {iconClass:"myIcon"}, item)

tree.set("iconClass","myIcon", item)

Alternatively, you can designate a data item property as the default icon for the given item by setting the new iconAttr property of the store model. If set, both the model and the tree will recognise the item property as an icon class. Please refer to the Tree Styling documentation for details.

Note: With the Tree Styling API loaded you can still use the original dijit tree callback style styling.

Online Demo

The CheckBox Tree package includes a set of demo applications as well as some unit tests which you can you use to verify proper installation. A comprehensive AMD CheckBox Tree demo is also available online.

The online demo illustrates the CheckBox Tree configurable properties, the tree styling API, drag and drop feature and the extended store model API.

Also, the left accordion panel demostrate the multi model support, that is, click a checkbox on one tree and all other trees with checkboxes are automatically updated.

Download

Documentation

Code Sample

The following is a simple application which creates a CheckBox Tree and connect to the onCheckBoxClick event. Whenever a checkbox on the tree is clicked the function checkBoxClicked() is called displaying the updated checked state for the associated tree node.

  1 <html lang="en">
  2   <head>
  3     <title>Dijit Tree with Checkboxes</title>
  4     <style type="text/css">
  5       @import "../../dijit/themes/claro/claro.css";
  6       @import "../themes/claro/claro.css";
  7     </style>
  8     <script type="text/javascript">
  9       var dojoConfig = {
 10             async: true,
 11             parseOnLoad: true,
 12             isDebug: true,
 13             baseUrl: "../../",
 14             packages: [
 15               { name: "dojo",  location: "dojo" },
 16               { name: "dijit", location: "dijit" },
 17               { name: "cbtree",location: "cbtree" }
 18             ]
 19       };
 20     </script>
 21     <script type="text/javascript" src="../../dojo/dojo.js"></script>
 22   </head>
 23   <body class="claro">
 24     <h1 class="DemoTitle">Dijit Tree with Multi State CheckBoxes</h1>
 25     <div id="CheckboxTree">
 26       <script type="text/javascript">
 27         require([
 28           "dojo/_base/connect",
 29           "dojo/data/ItemFileWriteStore",
 30           "dojo/domReady",
 31           "cbtree/Tree",                    
 32           "cbtree/models/ForestStoreModel"  
 33           ], function( connect, ItemFileWriteStore, domReady, Tree, ForestStoreModel) {
 34             function checkBoxClicked( item, nodeWidget, evt ) {
 35               alert( "The new state for " + this.getLabel(item) + " is: " + nodeWidget.get("checked") );
 36             }
 37             var store = new ItemFileWriteStore( { url: "../datastore/Family-1.7.json" });
 38             var model = new ForestStoreModel( {
 39                                 store: store,
 40                                 query: {type: 'parent'},
 41                                 rootLabel: 'The Family'
 42                              });
 43             var tree = new Tree( {
 44                               model: model,
 45                               id: "MenuTree",
 46                               branchIcons: true,
 47                               branchReadOnly: false,
 48                               checkBoxes: true,
 49                               nodeIcons: true
 50                             });
 51             connect.connect( tree, "onCheckBoxClick", model, checkBoxClicked );
 52             domReady( function() {
 53               tree.placeAt('CheckboxTree');
 54             });
 55         });
 56       </script>
 57     </div>
 58     <h2>Click a checkbox</h2>
 59   </body>
 60 </html>
        

The CheckBox Tree package and documentation include many more examples.

How Does It Work

The easiest way to exaplain how the Dijit CheckBox Tree works is by using some simplified sequence diagrams and a high level overview of some of the internal functions. If you want all the details then the source code is going to be your best friend. In this How To section I'm going to use two diagrams to explain how the above sample code works and what happens under the hood.

Creating the CheckBox Tree

On lines 37-50 we instantiate the store, model and tree. When the model is created it connects, or better yet subscribes, to the onSet event of the store. Whenever a property of a data item changes, the store will generate an onSet event. The onSet event holds information about the data item, the property that changed and what the new property value is.
When the tree is created on line 43, it internally connects to the onChange event of the model. As part of the post create stage of the tree it starts loading the data store by calling validateData() and for each data item a tree node and checkbox is created.

The models validateData() is an essential part of the CheckBox Tree, it loads the store data items and synchronizes their checked state when the parent-child checkbox relationship is requested.

The diagram below shows the sequence of events involved in creating a CheckBox Tree.

If you take a closer look at the sequence diagram you will notice that the tree never interact with the store directly, this is part of the Model-View-Controller design pattern.

Getting notified

In order for our sample application to get notified whenever the user clicks a tree checkbox it needs to connect to the onCheckBoxClick event of the tree. On line 51 the application connects to the event specifying checkBoxClicked as the callback function.

connect.connect( tree, "onCheckBoxClick", model, checkBoxClicked );
        

The function checkBoxClicked() on line 34 will be called in the context of the model, that is, the "this" object equates to model.
So what happens when a user clicks a checkbox? The following diagram show the sequence of events that take place each time a user clicks a tree checkbox. The first thing the tree node will do is to verify the click event took place on a DOM element of type "input", if so, it gets the new checked state from the checkbox.

Next, the tree node will tell the store model to update the checked state for the data item associated with the node by calling setChecked(). Simply speaking, the model will take the request and in turn asks the underlying store to do the same. On completion the store will generate an onSet event.

Because the model subscribed to the onSet event of the store, as shown in the first diagram above, it gets notified about the store update and this is were the interesting stuff starts to happen. Any data item in the store may have any number of parent items so, assuming the parent-child relationship for the model is enabled, the model will take the onSet event and updates the checked state of all parent items according to the new state of the checkbox that just got updated.
Although not visible on the sequence diagram, any update to a parent item results in another call to the setChecked() function untill all have been updated. So a single click on a tree checkbox can result in several store updates. Also, if the tree node whose checkbox was clicked has any children those children will also be updated.

Being the system architect that you are, you are wondering: why not update the parent items and potential children as soon as the original setChecked() call comes in? It would make things alot easier as you don't have to handle the onSet event from the store.
The answer is: there can be multiple models operating on the same store. For example, lets assume you have two trees A and B, and each tree has its own model A and B. If a checkbox gets clicked on tree A, the tree will call setChecked() of model A, therefore model B has no notion of any click event. However, because both models are subscribed to the onSet event of the common store, both models will be notified of the store update thus allowing both model A and B to update their own tree.

Finally, when the model receives the onSet event it will generate a matching onChange event which is caught by all trees associated with the model. Note, you can associate multiple trees with a single model. The tree will then search for all tree nodes associated with the data item and send a set("checked", newValue) request to each of them.