lib/CheckBoxTree.js

   1 dojo.provide("lib.CheckBoxTree");
   2 dojo.provide("lib.CheckBoxStoreModel");
   3
   4 // THIS WIDGET IS BASED ON DOJO/DIJIT 1.4.0 AND WILL NOT WORK WITH PREVIOUS VERSIONS
   5 //
   6 //      Release date: 02/05/2010
   7 //
   8
   9 dojo.require("dijit.Tree");
  10 dojo.require("dijit.form.CheckBox");
  11
  12 dojo.declare( "lib.CheckBoxStoreModel", dijit.tree.TreeStoreModel,
  13 {
  14         // checkboxAll: Boolean
  15         //              If true, every node in the tree will receive a checkbox regardless if the 'checkbox' attribute
  16         //              is specified in the dojo.data.
  17         checkboxAll: true,
  18
  19         // checkboxState: Boolean
  20         //              The default state applied to every checkbox unless otherwise specified in the dojo.data.
  21         //              (see also: checkboxIdent)
  22         checkboxState: false,
  23
  24         // checkboxRoot: Boolean
  25         //              If true, the root node will receive a checkbox eventhough it's not a true entry in the store.
  26         //              This attribute is independent of the showRoot attribute of the tree itself. If the tree
  27         //              attribute 'showRoot' is set to false to checkbox for the root will not show either.
  28         checkboxRoot: false,
  29
  30         // checkboxStrict: Boolean
  31         //              If true, a strict parent-child checkbox relation is maintained. For example, if all children
  32         //              are checked the parent will automatically be checked or if any of the children are unchecked
  33         //              the parent will be unchecked.
  34         checkboxStrict: true,
  35
  36         // checkboxIdent: String
  37         //              The attribute name (attribute of the dojo.data.item) that specifies that items checkbox initial
  38         //              state. Example: { name:'Egypt', type:'country', checkbox: true }
  39         //              If a dojo.data.item has no 'checkbox' attribute specified it will depend on the attribute
  40         //              'checkboxAll' if one will be created automatically and if so what the initial state will be as
  41         //              specified by 'checkboxState'.
  42         checkboxIdent: "checkbox",
  43
  44         updateCheckbox: function(/*dojo.data.Item*/ storeItem, /*Boolean*/ newState ) {
  45                 // summary:
  46                 //              Update the checkbox state (true/false) for the item and the associated parent and
  47                 //              child checkboxes if any.
  48                 // description:
  49                 //              Update a single checkbox state (true/false) for the item and the associated parent
  50                 //              and child checkboxes if any. This function is called from the tree if a user checked
  51                 //              or unchecked a checkbox on the tree. The parent and child tree nodes are updated to
  52                 //              maintain consistency if 'checkboxStrict' is set to true.
  53                 //      storeItem:
  54                 //              The item in the dojo.data.store whos checkbox state needs updating.
  55                 //      newState:
  56                 //              The new state of the checkbox: true or false
  57                 //      example:
  58                 //      | model.updateCheckboxState(item, true);
  59                 //
  60
  61                 this._setCheckboxState( storeItem, newState );
  62                 //if( this.checkboxStrict ) { I don't need all this 1-1 stuff, only parent -> child (fox)
  63                         this._updateChildCheckbox( storeItem, newState );
  64                         //this._updateParentCheckbox( storeItem, newState );
  65                 //}
  66         },
  67         setAllChecked: function(checked) {
  68                 var items = this.store._arrayOfAllItems;
  69                 this.setCheckboxState(items, checked);
  70         },
  71         setCheckboxState: function(items, checked) {
  72                 for (var i = 0; i < items.length; i++) {
  73                         this._setCheckboxState(items[i], checked);
  74                 }
  75         },
  76         getCheckedItems: function() {
  77                 var items = this.store._arrayOfAllItems;
  78                 var result = [];
  79
  80                 for (var i = 0; i < items.length; i++) {
  81                         if (this.store.getValue(items[i], 'checkbox'))
  82                                 result.push(items[i]);
  83                 }
  84
  85                 return result;
  86    },
  87
  88         getCheckboxState: function(/*dojo.data.Item*/ storeItem) {
  89                 // summary:
  90                 //              Get the current checkbox state from the dojo.data.store.
  91                 // description:
  92                 //              Get the current checkbox state from the dojo.data store. A checkbox can have three
  93                 //              different states: true, false or undefined. Undefined in this context means no
  94                 //              checkbox identifier (checkboxIdent) was found in the dojo.data store. Depending on
  95                 //              the checkbox attributes as specified above the following will take place:
  96                 //              a)      If the current checkbox state is undefined and the checkbox attribute 'checkboxAll' or
  97                 //                      'checkboxRoot' is true one will be created and the default state 'checkboxState' will
  98                 //                      be applied.
  99                 //              b)      If the current state is undefined and 'checkboxAll' is false the state undefined remains
 100                 //                      unchanged and is returned. This will prevent any tree node from creating a checkbox.
 101                 //
 102                 //      storeItem:
 103                 //              The item in the dojo.data.store whos checkbox state is returned.
 104                 //      example:
 105                 //      | var currState = model.getCheckboxState(item);
 106                 //
 107                 var currState = undefined;
 108
 109                 // Special handling required for the 'fake' root entry (the root is NOT a dojo.data.item).
 110                 // this stuff is only relevant for Forest store -fox
 111 /*              if ( storeItem == this.root ) {
 112                         if( typeof(storeItem.checkbox) == "undefined" ) {
 113                                 this.root.checkbox = undefined;         // create a new checbox reference as undefined.
 114                                 if( this.checkboxRoot ) {
 115                                         currState = this.root.checkbox = this.checkboxState;
 116                                 }
 117                         } else {
 118                                 currState = this.root.checkbox;
 119                         }
 120                 } else {        // a valid dojo.store.item
 121                         currState = this.store.getValue(storeItem, this.checkboxIdent);
 122                         if( currState == undefined && this.checkboxAll) {
 123                                 this._setCheckboxState( storeItem, this.checkboxState );
 124                                 currState = this.checkboxState;
 125                         }
 126                 } */
 127
 128                 currState = this.store.getValue(storeItem, this.checkboxIdent);
 129                 if( currState == undefined && this.checkboxAll) {
 130                         this._setCheckboxState( storeItem, this.checkboxState );
 131                         currState = this.checkboxState;
 132                 }
 133
 134                 return currState  // the current state of the checkbox (true/false or undefined)
 135         },
 136
 137         _setCheckboxState: function(/*dojo.data.Item*/ storeItem, /*Boolean*/ newState ) {
 138                 // summary:
 139                 //              Set/update the checkbox state on the dojo.data store.
 140                 // description:
 141                 //              Set/update the checkbox state on the dojo.data.store. Retreive the current
 142                 //              state of the checkbox and validate if an update is required, this will keep
 143                 //              update events to a minimum. On completion a 'onCheckboxChange' event is
 144                 //              triggered.
 145                 //              If the current state is undefined (ie: no checkbox attribute specified for
 146                 //              this dojo.data.item) the 'checkboxAll' attribute is checked     to see if one
 147                 //              needs to be created. In case of the root the 'checkboxRoot' attribute is checked.
 148                 //              NOTE: the store.setValue function will create the 'checkbox' attribute for the
 149                 //              item if none exists.
 150                 //      storeItem:
 151                 //              The item in the dojo.data.store whos checkbox state is updated.
 152                 //      newState:
 153                 //              The new state of the checkbox: true or false
 154                 //      example:
 155                 //      | model.setCheckboxState(item, true);
 156                 //
 157                 var stateChanged = true;
 158
 159                 if( storeItem != this.root ) {
 160                         var currState = this.store.getValue(storeItem, this.checkboxIdent);
 161                         if( currState != newState && ( currState !== undefined || this.checkboxAll ) ) {
 162                                 this.store.setValue(storeItem, this.checkboxIdent, newState);
 163                         } else {
 164                                 stateChanged = false;   // No changes to the checkbox
 165                         }
 166                 } else {  // Tree root instance
 167                         if( this.root.checkbox != newState && ( this.root.checkbox !== undefined || this.checkboxRoot ) ) {
 168                                 this.root.checkbox = newState;
 169                         } else {
 170                                 stateChanged = false;
 171                         }
 172                 }
 173                 if( stateChanged ) {    // In case of any changes trigger the update event.
 174                         this.onCheckboxChange(storeItem);
 175                 }
 176                 return stateChanged;
 177         },
 178
 179         _updateChildCheckbox: function(/*dojo.data.Item*/ parentItem, /*Boolean*/ newState ) {
 180                 //      summary:
 181                 //              Set all child checkboxes to true/false depending on the parent checkbox state.
 182                 //      description:
 183                 //              If a parent checkbox changes state, all child and grandchild checkboxes will be
 184                 //              updated to reflect the change. For example, if the parent state is set to true,
 185                 //              all child and grandchild checkboxes will receive that same 'true' state.
 186                 //              If a child checkbox changes state and has multiple parent, all of its parents
 187                 //              need to be re-evaluated.
 188                 //      parentItem:
 189                 //              The parent dojo.data.item whos child/grandchild checkboxes require updating.
 190                 //      newState:
 191                 //              The new state of the checkbox: true or false
 192                 //
 193
 194                 if( this.mayHaveChildren( parentItem )) {
 195                         this.getChildren( parentItem, dojo.hitch( this,
 196                                 function( children ) {
 197                                         dojo.forEach( children, function(child) {
 198                                                 if( this._setCheckboxState(child, newState) ) {
 199                                                         var parents = this._getParentsItem(child);
 200                                                         if( parents.length > 1 ) {
 201                                                                 this._updateParentCheckbox( child, newState );
 202                                                         }
 203                                                 }
 204                                                 if( this.mayHaveChildren( child )) {
 205                                                         this._updateChildCheckbox( child, newState );
 206                                                 }
 207                                         }, this );
 208                                 }),
 209                                 function(err) {
 210                                         console.error(this, ": updating child checkboxes: ", err);
 211                                 }
 212                         );
 213                 }
 214         },
 215
 216         _updateParentCheckbox: function(/*dojo.data.Item*/ storeItem, /*Boolean*/ newState ) {
 217                 //      summary:
 218                 //              Update the parent checkbox state depending on the state of all child checkboxes.
 219                 //      description:
 220                 //              Update the parent checkbox state depending on the state of all child checkboxes.
 221                 //              The parent checkbox automatically changes state if ALL child checkboxes are true
 222                 //              or false. If, as a result, the parent checkbox changes state, we will check if
 223                 //              its parent needs to be updated as well all the way upto the root.
 224                 //      storeItem:
 225                 //              The dojo.data.item whos parent checkboxes require updating.
 226                 //      newState:
 227                 //              The new state of the checkbox: true or false
 228                 //
 229                 var parents = this._getParentsItem(storeItem);
 230                 dojo.forEach( parents, function( parentItem ) {
 231                         if( newState ) { // new state = true (checked)
 232                                 this.getChildren( parentItem, dojo.hitch( this,
 233                                         function(siblings) {
 234                                                 var allChecked  = true;
 235                                                 dojo.some( siblings, function(sibling) {
 236                                                         siblState = this.getCheckboxState(sibling);
 237                                                         if( siblState !== undefined && allChecked )
 238                                                                 allChecked = siblState;
 239                                                         return !(allChecked);
 240                                                 }, this );
 241                                                 if( allChecked ) {
 242                                                         this._setCheckboxState( parentItem, true );
 243                                                         this._updateParentCheckbox( parentItem, true );
 244                                                 }
 245                                         }),
 246                                         function(err) {
 247                                                 console.error(this, ": updating parent checkboxes: ", err);
 248                                         }
 249                                 );
 250                         } else {        // new state = false (unchecked)
 251                                 if( this._setCheckboxState( parentItem, false ) ) {
 252                                         this._updateParentCheckbox( parentItem, false );
 253                                 }
 254                         }
 255                 }, this );
 256         },
 257
 258         _getParentsItem: function(/*dojo.data.Item*/ storeItem ) {
 259                 // summary:
 260                 //              Get the parent(s) of a dojo.data item.
 261                 // description:
 262                 //              Get the parent(s) of a dojo.data item. The '_reverseRefMap' entry of the item is
 263                 //              used to identify the parent(s). A child will have a parent reference if the parent
 264                 //              specified the '_reference' attribute.
 265                 //              For example: children:[{_reference:'Mexico'}, {_reference:'Canada'}, ...
 266                 //      storeItem:
 267                 //              The dojo.data.item whos parent(s) will be returned.
 268                 //
 269                 var parents = [];
 270
 271                 if( storeItem != this.root ) {
 272                         var references = storeItem[this.store._reverseRefMap];
 273                         for(itemId in references ) {
 274                                 parents.push(this.store._itemsByIdentity[itemId]);
 275                         }
 276                         if (!parents.length) {
 277                                 parents.push(this.root);
 278                         }
 279                 }
 280                 return parents // parent(s) of a dojo.data.item (Array of dojo.data.items)
 281         },
 282
 283         validateData: function(/*dojo.data.Item*/ storeItem, /*thisObject*/ scope ) {
 284                 // summary:
 285                 //              Validate/normalize the parent(s) checkbox data in the dojo.data store.
 286                 // description:
 287                 //              Validate/normalize the parent-child checkbox relationship if the attribute
 288                 //              'checkboxStrict' is set to true. This function is called as part of the post
 289                 //              creation of the Tree instance. All parent checkboxes are set to the appropriate
 290                 //              state according to the actual state(s) of their children.
 291                 //              This will potentionally overwrite whatever was specified for the parent in the
 292                 //              dojo.data store. This will garantee the tree is in a consistent state after startup.
 293                 //      storeItem:
 294                 //              The element to start traversing the dojo.data.store, typically model.root
 295                 //      scope:
 296                 //              The scope to use when this method executes.
 297                 //      example:
 298                 //      | this.model.validateData(this.model.root, this.model);
 299                 //
 300                 if( !scope.checkboxStrict ) {
 301                         return;
 302                 }
 303                 scope.getChildren( storeItem, dojo.hitch( scope,
 304                         function(children) {
 305                                 var allChecked  = true;
 306                                 var childState;
 307                                 dojo.forEach( children, function( child ) {
 308                                         if( this.mayHaveChildren( child )) {
 309                                                 this.validateData( child, this );
 310                                         }
 311                                         childState = this.getCheckboxState( child );
 312                                         if( childState !== undefined && allChecked )
 313                                                 allChecked = childState;
 314                                 }, this);
 315
 316                                 if ( this._setCheckboxState( storeItem, allChecked) ) {
 317                                         this._updateParentCheckbox( storeItem, allChecked);
 318                                 }
 319                         }),
 320                         function(err) {
 321                                 console.error(this, ": validating checkbox data: ", err);
 322                         }
 323                 );
 324         },
 325
 326         onCheckboxChange: function(/*dojo.data.Item*/ storeItem ) {
 327                 // summary:
 328                 //              Callback whenever a checkbox state has changed state, so that
 329                 //              the Tree can update the checkbox.  This callback is generally
 330                 //              triggered by the '_setCheckboxState' function.
 331                 // tags:
 332                 //              callback
 333         }
 334
 335 });
 336
 337 dojo.declare( "lib._CheckBoxTreeNode", dijit._TreeNode,
 338 {
 339         // _checkbox: [protected] dojo.doc.element
 340         //              Local reference to the dojo.doc.element of type 'checkbox'
 341         _checkbox: null,
 342
 343         _createCheckbox: function() {
 344                 // summary:
 345                 //              Create a checkbox on the CheckBoxTreeNode
 346                 // description:
 347                 //              Create a checkbox on the CheckBoxTreeNode. The checkbox is ONLY created if a
 348                 //              valid reference was found in the dojo.data store or the attribute 'checkboxAll'
 349                 //              is set to true. If the current state is 'undefined' no reference was found and
 350                 //              'checkboxAll' is set to false.
 351                 //              Note: the attribute 'checkboxAll' is validated by the getCheckboxState function
 352                 //              therefore no need to do that here. (see getCheckboxState for details).
 353                 //
 354                 var     currState = this.tree.model.getCheckboxState( this.item );
 355                 if( currState !== undefined ) {
 356                         this._checkbox = new dijit.form.CheckBox();
 357                         //this._checkbox = dojo.doc.createElement('input');
 358                         this._checkbox.type    = 'checkbox';
 359                         this._checkbox.attr('checked', currState);
 360                         dojo.place(this._checkbox.domNode, this.expandoNode, 'after');
 361                 }
 362         },
 363
 364         postCreate: function() {
 365                 // summary:
 366                 //              Handle the creation of the checkbox after the CheckBoxTreeNode has been instanciated.
 367                 // description:
 368                 //              Handle the creation of the checkbox after the CheckBoxTreeNode has been instanciated.
 369                 this._createCheckbox();
 370                 this.inherited( arguments );
 371         }
 372
 373 });
 374
 375 dojo.declare( "lib.CheckBoxTree", dijit.Tree,
 376 {
 377
 378         onNodeChecked: function(/*dojo.data.Item*/ storeItem, /*treeNode*/ treeNode) {
 379                 // summary:
 380                 //              Callback when a checkbox tree node is checked
 381                 // tags:
 382                 //              callback
 383         },
 384
 385         onNodeUnchecked: function(/*dojo.data.Item*/ storeItem, /* treeNode */ treeNode) {
 386                 // summary:
 387                 //              Callback when a checkbox tree node is unchecked
 388                 // tags:
 389                 //              callback
 390         },
 391
 392         _onClick: function(/*TreeNode*/ nodeWidget, /*Event*/ e) {
 393                 // summary:
 394                 //              Translates click events into commands for the controller to process
 395                 // description:
 396                 //              the _onClick function is called whenever a 'click' is detected. This
 397                 //              instance of _onClick only handles the click events associated with
 398                 //              the checkbox whos DOM name is INPUT.
 399                 //
 400                 var domElement = e.target;
 401
 402                 // Only handle checkbox clicks here
 403                 if(domElement.type != 'checkbox') {
 404                         return this.inherited( arguments );
 405                 }
 406
 407                 this._publish("execute", { item: nodeWidget.item, node: nodeWidget} );
 408                 // Go tell the model to update the checkbox state
 409
 410                 this.model.updateCheckbox( nodeWidget.item, nodeWidget._checkbox.checked );
 411                 // Generate some additional events
 412                 //this.onClick( nodeWidget.item, nodeWidget, e );
 413                 if(nodeWidget._checkbox.checked) {
 414                         this.onNodeChecked( nodeWidget.item, nodeWidget);
 415                 } else {
 416                         this.onNodeUnchecked( nodeWidget.item, nodeWidget);
 417                 }
 418                 this.focusNode(nodeWidget);
 419         },
 420
 421         _onCheckboxChange: function(/*dojo.data.Item*/ storeItem ) {
 422                 // summary:
 423                 //              Processes notification of a change to a checkbox state (triggered by the model).
 424                 // description:
 425                 //              Whenever the model changes the state of a checkbox in the dojo.data.store it will
 426                 //              trigger the 'onCheckboxChange' event allowing the Tree to make the same changes
 427                 //              on the tree Node. There are several conditions why a tree node or checkbox does not
 428                 //              exists:
 429                 //              a)      The node has not been created yet (the user has not expanded the tree node yet).
 430                 //              b)      The checkbox may be null if condition (a) exists or no 'checkbox' attribute was
 431                 //                      specified for the associated dojo.data.item and the attribute 'checkboxAll' is
 432                 //                      set to false.
 433                 // tags:
 434                 //              callback
 435                 var model        = this.model,
 436                         identity = model.getIdentity(storeItem),
 437                         nodes    = this._itemNodesMap[identity];
 438
 439                 // As of dijit.Tree 1.4 multiple references (parents) are supported, therefore we may have
 440                 // to update multiple nodes which are all associated with the same dojo.data.item.
 441                 if( nodes ) {
 442                         dojo.forEach( nodes, function(node) {
 443                                 if( node._checkbox != null ) {
 444                                         node._checkbox.attr('checked', this.model.getCheckboxState( storeItem ));
 445                                 }
 446                         }, this );
 447                 }
 448         },
 449
 450         postCreate: function() {
 451                 // summary:
 452                 //              Handle any specifics related to the tree and model after the instanciation of the Tree.
 453                 // description:
 454                 //              Validate if we have a 'write' store first. Subscribe to the 'onCheckboxChange' event
 455                 //              (triggered by the model) and kickoff the initial checkbox data validation.
 456                 //
 457                 var store = this.model.store;
 458                 if(!store.getFeatures()['dojo.data.api.Write']){
 459                         throw new Error("lib.CheckboxTree: store must support dojo.data.Write");
 460                 }
 461                 this.connect(this.model, "onCheckboxChange", "_onCheckboxChange");
 462                 this.model.validateData( this.model.root, this.model );
 463                 this.inherited(arguments);
 464         },
 465
 466         _createTreeNode: function( args ) {
 467                 // summary:
 468                 //              Create a new CheckboxTreeNode instance.
 469                 // description:
 470                 //              Create a new CheckboxTreeNode instance.
 471                 return new lib._CheckBoxTreeNode(args);
 472         }
 473
 474 });