]>
git.wh0rd.org - tt-rss.git/blob - lib/CheckBoxTree.js
1 dojo
.provide("lib.CheckBoxTree");
2 dojo
.provide("lib.CheckBoxStoreModel");
4 // THIS WIDGET IS BASED ON DOJO/DIJIT 1.4.0 AND WILL NOT WORK WITH PREVIOUS VERSIONS
6 // Release date: 02/05/2010
9 dojo
.require("dijit.Tree");
10 dojo
.require("dijit.form.CheckBox");
12 dojo
.declare( "lib.CheckBoxStoreModel", dijit
.tree
.TreeStoreModel
,
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.
19 // checkboxState: Boolean
20 // The default state applied to every checkbox unless otherwise specified in the dojo.data.
21 // (see also: checkboxIdent)
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.
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.
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",
44 updateCheckbox: function(/*dojo.data.Item*/ storeItem
, /*Boolean*/ newState
) {
46 // Update the checkbox state (true/false) for the item and the associated parent and
47 // child checkboxes if any.
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.
54 // The item in the dojo.data.store whos checkbox state needs updating.
56 // The new state of the checkbox: true or false
58 // | model.updateCheckboxState(item, true);
60 this._setCheckboxState( storeItem
, newState
);
61 if( this.checkboxStrict
) {
62 this._updateChildCheckbox( storeItem
, newState
);
63 this._updateParentCheckbox( storeItem
, newState
);
66 setAllChecked: function(checked
) {
67 var items
= this.store
._arrayOfAllItems
;
68 this.setCheckboxState(items
, checked
);
70 setCheckboxState: function(items
, checked
) {
71 for (var i
= 0; i
< items
.length
; i
++) {
72 this._setCheckboxState(items
[i
], checked
);
75 getCheckedItems: function() {
76 var items
= this.store
._arrayOfAllItems
;
79 for (var i
= 0; i
< items
.length
; i
++) {
80 if (this.store
.getValue(items
[i
], 'checkbox'))
81 result
.push(items
[i
]);
87 getCheckboxState: function(/*dojo.data.Item*/ storeItem
) {
89 // Get the current checkbox state from the dojo.data.store.
91 // Get the current checkbox state from the dojo.data store. A checkbox can have three
92 // different states: true, false or undefined. Undefined in this context means no
93 // checkbox identifier (checkboxIdent) was found in the dojo.data store. Depending on
94 // the checkbox attributes as specified above the following will take place:
95 // a) If the current checkbox state is undefined and the checkbox attribute 'checkboxAll' or
96 // 'checkboxRoot' is true one will be created and the default state 'checkboxState' will
98 // b) If the current state is undefined and 'checkboxAll' is false the state undefined remains
99 // unchanged and is returned. This will prevent any tree node from creating a checkbox.
102 // The item in the dojo.data.store whos checkbox state is returned.
104 // | var currState = model.getCheckboxState(item);
106 var currState
= undefined;
108 // Special handling required for the 'fake' root entry (the root is NOT a dojo.data.item).
109 // this stuff is only relevant for Forest store -fox
110 /* if ( storeItem == this.root ) {
111 if( typeof(storeItem.checkbox) == "undefined" ) {
112 this.root.checkbox = undefined; // create a new checbox reference as undefined.
113 if( this.checkboxRoot ) {
114 currState = this.root.checkbox = this.checkboxState;
117 currState = this.root.checkbox;
119 } else { // a valid dojo.store.item
120 currState = this.store.getValue(storeItem, this.checkboxIdent);
121 if( currState == undefined && this.checkboxAll) {
122 this._setCheckboxState( storeItem, this.checkboxState );
123 currState = this.checkboxState;
127 currState
= this.store
.getValue(storeItem
, this.checkboxIdent
);
128 if( currState
== undefined && this.checkboxAll
) {
129 this._setCheckboxState( storeItem
, this.checkboxState
);
130 currState
= this.checkboxState
;
133 return currState
// the current state of the checkbox (true/false or undefined)
136 _setCheckboxState: function(/*dojo.data.Item*/ storeItem
, /*Boolean*/ newState
) {
138 // Set/update the checkbox state on the dojo.data store.
140 // Set/update the checkbox state on the dojo.data.store. Retreive the current
141 // state of the checkbox and validate if an update is required, this will keep
142 // update events to a minimum. On completion a 'onCheckboxChange' event is
144 // If the current state is undefined (ie: no checkbox attribute specified for
145 // this dojo.data.item) the 'checkboxAll' attribute is checked to see if one
146 // needs to be created. In case of the root the 'checkboxRoot' attribute is checked.
147 // NOTE: the store.setValue function will create the 'checkbox' attribute for the
148 // item if none exists.
150 // The item in the dojo.data.store whos checkbox state is updated.
152 // The new state of the checkbox: true or false
154 // | model.setCheckboxState(item, true);
156 var stateChanged
= true;
158 if( storeItem
!= this.root
) {
159 var currState
= this.store
.getValue(storeItem
, this.checkboxIdent
);
160 if( currState
!= newState
&& ( currState
!== undefined || this.checkboxAll
) ) {
161 this.store
.setValue(storeItem
, this.checkboxIdent
, newState
);
163 stateChanged
= false; // No changes to the checkbox
165 } else { // Tree root instance
166 if( this.root
.checkbox
!= newState
&& ( this.root
.checkbox
!== undefined || this.checkboxRoot
) ) {
167 this.root
.checkbox
= newState
;
169 stateChanged
= false;
172 if( stateChanged
) { // In case of any changes trigger the update event.
173 this.onCheckboxChange(storeItem
);
178 _updateChildCheckbox: function(/*dojo.data.Item*/ parentItem
, /*Boolean*/ newState
) {
180 // Set all child checkboxes to true/false depending on the parent checkbox state.
182 // If a parent checkbox changes state, all child and grandchild checkboxes will be
183 // updated to reflect the change. For example, if the parent state is set to true,
184 // all child and grandchild checkboxes will receive that same 'true' state.
185 // If a child checkbox changes state and has multiple parent, all of its parents
186 // need to be re-evaluated.
188 // The parent dojo.data.item whos child/grandchild checkboxes require updating.
190 // The new state of the checkbox: true or false
192 if( this.mayHaveChildren( parentItem
)) {
193 this.getChildren( parentItem
, dojo
.hitch( this,
194 function( children
) {
195 dojo
.forEach( children
, function(child
) {
196 if( this._setCheckboxState(child
, newState
) ) {
197 var parents
= this._getParentsItem(child
);
198 if( parents
.length
> 1 ) {
199 this._updateParentCheckbox( child
, newState
);
202 if( this.mayHaveChildren( child
)) {
203 this._updateChildCheckbox( child
, newState
);
208 console
.error(this, ": updating child checkboxes: ", err
);
214 _updateParentCheckbox: function(/*dojo.data.Item*/ storeItem
, /*Boolean*/ newState
) {
216 // Update the parent checkbox state depending on the state of all child checkboxes.
218 // Update the parent checkbox state depending on the state of all child checkboxes.
219 // The parent checkbox automatically changes state if ALL child checkboxes are true
220 // or false. If, as a result, the parent checkbox changes state, we will check if
221 // its parent needs to be updated as well all the way upto the root.
223 // The dojo.data.item whos parent checkboxes require updating.
225 // The new state of the checkbox: true or false
227 var parents
= this._getParentsItem(storeItem
);
228 dojo
.forEach( parents
, function( parentItem
) {
229 if( newState
) { // new state = true (checked)
230 this.getChildren( parentItem
, dojo
.hitch( this,
232 var allChecked
= true;
233 dojo
.some( siblings
, function(sibling
) {
234 siblState
= this.getCheckboxState(sibling
);
235 if( siblState
!== undefined && allChecked
)
236 allChecked
= siblState
;
237 return !(allChecked
);
240 this._setCheckboxState( parentItem
, true );
241 this._updateParentCheckbox( parentItem
, true );
245 console
.error(this, ": updating parent checkboxes: ", err
);
248 } else { // new state = false (unchecked)
249 if( this._setCheckboxState( parentItem
, false ) ) {
250 this._updateParentCheckbox( parentItem
, false );
256 _getParentsItem: function(/*dojo.data.Item*/ storeItem
) {
258 // Get the parent(s) of a dojo.data item.
260 // Get the parent(s) of a dojo.data item. The '_reverseRefMap' entry of the item is
261 // used to identify the parent(s). A child will have a parent reference if the parent
262 // specified the '_reference' attribute.
263 // For example: children:[{_reference:'Mexico'}, {_reference:'Canada'}, ...
265 // The dojo.data.item whos parent(s) will be returned.
269 if( storeItem
!= this.root
) {
270 var references
= storeItem
[this.store
._reverseRefMap
];
271 for(itemId
in references
) {
272 parents
.push(this.store
._itemsByIdentity
[itemId
]);
274 if (!parents
.length
) {
275 parents
.push(this.root
);
278 return parents
// parent(s) of a dojo.data.item (Array of dojo.data.items)
281 validateData: function(/*dojo.data.Item*/ storeItem
, /*thisObject*/ scope
) {
283 // Validate/normalize the parent(s) checkbox data in the dojo.data store.
285 // Validate/normalize the parent-child checkbox relationship if the attribute
286 // 'checkboxStrict' is set to true. This function is called as part of the post
287 // creation of the Tree instance. All parent checkboxes are set to the appropriate
288 // state according to the actual state(s) of their children.
289 // This will potentionally overwrite whatever was specified for the parent in the
290 // dojo.data store. This will garantee the tree is in a consistent state after startup.
292 // The element to start traversing the dojo.data.store, typically model.root
294 // The scope to use when this method executes.
296 // | this.model.validateData(this.model.root, this.model);
298 if( !scope
.checkboxStrict
) {
301 scope
.getChildren( storeItem
, dojo
.hitch( scope
,
303 var allChecked
= true;
305 dojo
.forEach( children
, function( child
) {
306 if( this.mayHaveChildren( child
)) {
307 this.validateData( child
, this );
309 childState
= this.getCheckboxState( child
);
310 if( childState
!== undefined && allChecked
)
311 allChecked
= childState
;
314 if ( this._setCheckboxState( storeItem
, allChecked
) ) {
315 this._updateParentCheckbox( storeItem
, allChecked
);
319 console
.error(this, ": validating checkbox data: ", err
);
324 onCheckboxChange: function(/*dojo.data.Item*/ storeItem
) {
326 // Callback whenever a checkbox state has changed state, so that
327 // the Tree can update the checkbox. This callback is generally
328 // triggered by the '_setCheckboxState' function.
335 dojo
.declare( "lib._CheckBoxTreeNode", dijit
._TreeNode
,
337 // _checkbox: [protected] dojo.doc.element
338 // Local reference to the dojo.doc.element of type 'checkbox'
341 _createCheckbox: function() {
343 // Create a checkbox on the CheckBoxTreeNode
345 // Create a checkbox on the CheckBoxTreeNode. The checkbox is ONLY created if a
346 // valid reference was found in the dojo.data store or the attribute 'checkboxAll'
347 // is set to true. If the current state is 'undefined' no reference was found and
348 // 'checkboxAll' is set to false.
349 // Note: the attribute 'checkboxAll' is validated by the getCheckboxState function
350 // therefore no need to do that here. (see getCheckboxState for details).
352 var currState
= this.tree
.model
.getCheckboxState( this.item
);
353 if( currState
!== undefined ) {
354 this._checkbox
= new dijit
.form
.CheckBox();
355 //this._checkbox = dojo.doc.createElement('input');
356 this._checkbox
.type
= 'checkbox';
357 this._checkbox
.attr('checked', currState
);
358 dojo
.place(this._checkbox
.domNode
, this.expandoNode
, 'after');
362 postCreate: function() {
364 // Handle the creation of the checkbox after the CheckBoxTreeNode has been instanciated.
366 // Handle the creation of the checkbox after the CheckBoxTreeNode has been instanciated.
367 this._createCheckbox();
368 this.inherited( arguments
);
373 dojo
.declare( "lib.CheckBoxTree", dijit
.Tree
,
376 onNodeChecked: function(/*dojo.data.Item*/ storeItem
, /*treeNode*/ treeNode
) {
378 // Callback when a checkbox tree node is checked
383 onNodeUnchecked: function(/*dojo.data.Item*/ storeItem
, /* treeNode */ treeNode
) {
385 // Callback when a checkbox tree node is unchecked
390 _onClick: function(/*TreeNode*/ nodeWidget
, /*Event*/ e
) {
392 // Translates click events into commands for the controller to process
394 // the _onClick function is called whenever a 'click' is detected. This
395 // instance of _onClick only handles the click events associated with
396 // the checkbox whos DOM name is INPUT.
398 var domElement
= e
.target
;
400 // Only handle checkbox clicks here
401 if(domElement
.type
!= 'checkbox') {
402 return this.inherited( arguments
);
405 this._publish("execute", { item
: nodeWidget
.item
, node
: nodeWidget
} );
406 // Go tell the model to update the checkbox state
408 this.model
.updateCheckbox( nodeWidget
.item
, nodeWidget
._checkbox
.checked
);
409 // Generate some additional events
410 //this.onClick( nodeWidget.item, nodeWidget, e );
411 if(nodeWidget
._checkbox
.checked
) {
412 this.onNodeChecked( nodeWidget
.item
, nodeWidget
);
414 this.onNodeUnchecked( nodeWidget
.item
, nodeWidget
);
416 this.focusNode(nodeWidget
);
419 _onCheckboxChange: function(/*dojo.data.Item*/ storeItem
) {
421 // Processes notification of a change to a checkbox state (triggered by the model).
423 // Whenever the model changes the state of a checkbox in the dojo.data.store it will
424 // trigger the 'onCheckboxChange' event allowing the Tree to make the same changes
425 // on the tree Node. There are several conditions why a tree node or checkbox does not
427 // a) The node has not been created yet (the user has not expanded the tree node yet).
428 // b) The checkbox may be null if condition (a) exists or no 'checkbox' attribute was
429 // specified for the associated dojo.data.item and the attribute 'checkboxAll' is
433 var model
= this.model
,
434 identity
= model
.getIdentity(storeItem
),
435 nodes
= this._itemNodesMap
[identity
];
437 // As of dijit.Tree 1.4 multiple references (parents) are supported, therefore we may have
438 // to update multiple nodes which are all associated with the same dojo.data.item.
440 dojo
.forEach( nodes
, function(node
) {
441 if( node
._checkbox
!= null ) {
442 node
._checkbox
.attr('checked', this.model
.getCheckboxState( storeItem
));
448 postCreate: function() {
450 // Handle any specifics related to the tree and model after the instanciation of the Tree.
452 // Validate if we have a 'write' store first. Subscribe to the 'onCheckboxChange' event
453 // (triggered by the model) and kickoff the initial checkbox data validation.
455 var store
= this.model
.store
;
456 if(!store
.getFeatures()['dojo.data.api.Write']){
457 throw new Error("lib.CheckboxTree: store must support dojo.data.Write");
459 this.connect(this.model
, "onCheckboxChange", "_onCheckboxChange");
460 this.model
.validateData( this.model
.root
, this.model
);
461 this.inherited(arguments
);
464 _createTreeNode: function( args
) {
466 // Create a new CheckboxTreeNode instance.
468 // Create a new CheckboxTreeNode instance.
469 return new lib
._CheckBoxTreeNode(args
);