]>
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 if ( storeItem
== this.root
) {
110 if( typeof(storeItem
.checkbox
) == "undefined" ) {
111 this.root
.checkbox
= undefined; // create a new checbox reference as undefined.
112 if( this.checkboxRoot
) {
113 currState
= this.root
.checkbox
= this.checkboxState
;
116 currState
= this.root
.checkbox
;
118 } else { // a valid dojo.store.item
119 currState
= this.store
.getValue(storeItem
, this.checkboxIdent
);
120 if( currState
== undefined && this.checkboxAll
) {
121 this._setCheckboxState( storeItem
, this.checkboxState
);
122 currState
= this.checkboxState
;
125 return currState
// the current state of the checkbox (true/false or undefined)
128 _setCheckboxState: function(/*dojo.data.Item*/ storeItem
, /*Boolean*/ newState
) {
130 // Set/update the checkbox state on the dojo.data store.
132 // Set/update the checkbox state on the dojo.data.store. Retreive the current
133 // state of the checkbox and validate if an update is required, this will keep
134 // update events to a minimum. On completion a 'onCheckboxChange' event is
136 // If the current state is undefined (ie: no checkbox attribute specified for
137 // this dojo.data.item) the 'checkboxAll' attribute is checked to see if one
138 // needs to be created. In case of the root the 'checkboxRoot' attribute is checked.
139 // NOTE: the store.setValue function will create the 'checkbox' attribute for the
140 // item if none exists.
142 // The item in the dojo.data.store whos checkbox state is updated.
144 // The new state of the checkbox: true or false
146 // | model.setCheckboxState(item, true);
148 var stateChanged
= true;
150 if( storeItem
!= this.root
) {
151 var currState
= this.store
.getValue(storeItem
, this.checkboxIdent
);
152 if( currState
!= newState
&& ( currState
!== undefined || this.checkboxAll
) ) {
153 this.store
.setValue(storeItem
, this.checkboxIdent
, newState
);
155 stateChanged
= false; // No changes to the checkbox
157 } else { // Tree root instance
158 if( this.root
.checkbox
!= newState
&& ( this.root
.checkbox
!== undefined || this.checkboxRoot
) ) {
159 this.root
.checkbox
= newState
;
161 stateChanged
= false;
164 if( stateChanged
) { // In case of any changes trigger the update event.
165 this.onCheckboxChange(storeItem
);
170 _updateChildCheckbox: function(/*dojo.data.Item*/ parentItem
, /*Boolean*/ newState
) {
172 // Set all child checkboxes to true/false depending on the parent checkbox state.
174 // If a parent checkbox changes state, all child and grandchild checkboxes will be
175 // updated to reflect the change. For example, if the parent state is set to true,
176 // all child and grandchild checkboxes will receive that same 'true' state.
177 // If a child checkbox changes state and has multiple parent, all of its parents
178 // need to be re-evaluated.
180 // The parent dojo.data.item whos child/grandchild checkboxes require updating.
182 // The new state of the checkbox: true or false
184 if( this.mayHaveChildren( parentItem
)) {
185 this.getChildren( parentItem
, dojo
.hitch( this,
186 function( children
) {
187 dojo
.forEach( children
, function(child
) {
188 if( this._setCheckboxState(child
, newState
) ) {
189 var parents
= this._getParentsItem(child
);
190 if( parents
.length
> 1 ) {
191 this._updateParentCheckbox( child
, newState
);
194 if( this.mayHaveChildren( child
)) {
195 this._updateChildCheckbox( child
, newState
);
200 console
.error(this, ": updating child checkboxes: ", err
);
206 _updateParentCheckbox: function(/*dojo.data.Item*/ storeItem
, /*Boolean*/ newState
) {
208 // Update the parent checkbox state depending on the state of all child checkboxes.
210 // Update the parent checkbox state depending on the state of all child checkboxes.
211 // The parent checkbox automatically changes state if ALL child checkboxes are true
212 // or false. If, as a result, the parent checkbox changes state, we will check if
213 // its parent needs to be updated as well all the way upto the root.
215 // The dojo.data.item whos parent checkboxes require updating.
217 // The new state of the checkbox: true or false
219 var parents
= this._getParentsItem(storeItem
);
220 dojo
.forEach( parents
, function( parentItem
) {
221 if( newState
) { // new state = true (checked)
222 this.getChildren( parentItem
, dojo
.hitch( this,
224 var allChecked
= true;
225 dojo
.some( siblings
, function(sibling
) {
226 siblState
= this.getCheckboxState(sibling
);
227 if( siblState
!== undefined && allChecked
)
228 allChecked
= siblState
;
229 return !(allChecked
);
232 this._setCheckboxState( parentItem
, true );
233 this._updateParentCheckbox( parentItem
, true );
237 console
.error(this, ": updating parent checkboxes: ", err
);
240 } else { // new state = false (unchecked)
241 if( this._setCheckboxState( parentItem
, false ) ) {
242 this._updateParentCheckbox( parentItem
, false );
248 _getParentsItem: function(/*dojo.data.Item*/ storeItem
) {
250 // Get the parent(s) of a dojo.data item.
252 // Get the parent(s) of a dojo.data item. The '_reverseRefMap' entry of the item is
253 // used to identify the parent(s). A child will have a parent reference if the parent
254 // specified the '_reference' attribute.
255 // For example: children:[{_reference:'Mexico'}, {_reference:'Canada'}, ...
257 // The dojo.data.item whos parent(s) will be returned.
261 if( storeItem
!= this.root
) {
262 var references
= storeItem
[this.store
._reverseRefMap
];
263 for(itemId
in references
) {
264 parents
.push(this.store
._itemsByIdentity
[itemId
]);
266 if (!parents
.length
) {
267 parents
.push(this.root
);
270 return parents
// parent(s) of a dojo.data.item (Array of dojo.data.items)
273 validateData: function(/*dojo.data.Item*/ storeItem
, /*thisObject*/ scope
) {
275 // Validate/normalize the parent(s) checkbox data in the dojo.data store.
277 // Validate/normalize the parent-child checkbox relationship if the attribute
278 // 'checkboxStrict' is set to true. This function is called as part of the post
279 // creation of the Tree instance. All parent checkboxes are set to the appropriate
280 // state according to the actual state(s) of their children.
281 // This will potentionally overwrite whatever was specified for the parent in the
282 // dojo.data store. This will garantee the tree is in a consistent state after startup.
284 // The element to start traversing the dojo.data.store, typically model.root
286 // The scope to use when this method executes.
288 // | this.model.validateData(this.model.root, this.model);
290 if( !scope
.checkboxStrict
) {
293 scope
.getChildren( storeItem
, dojo
.hitch( scope
,
295 var allChecked
= true;
297 dojo
.forEach( children
, function( child
) {
298 if( this.mayHaveChildren( child
)) {
299 this.validateData( child
, this );
301 childState
= this.getCheckboxState( child
);
302 if( childState
!== undefined && allChecked
)
303 allChecked
= childState
;
306 if ( this._setCheckboxState( storeItem
, allChecked
) ) {
307 this._updateParentCheckbox( storeItem
, allChecked
);
311 console
.error(this, ": validating checkbox data: ", err
);
316 onCheckboxChange: function(/*dojo.data.Item*/ storeItem
) {
318 // Callback whenever a checkbox state has changed state, so that
319 // the Tree can update the checkbox. This callback is generally
320 // triggered by the '_setCheckboxState' function.
327 dojo
.declare( "lib._CheckBoxTreeNode", dijit
._TreeNode
,
329 // _checkbox: [protected] dojo.doc.element
330 // Local reference to the dojo.doc.element of type 'checkbox'
333 _createCheckbox: function() {
335 // Create a checkbox on the CheckBoxTreeNode
337 // Create a checkbox on the CheckBoxTreeNode. The checkbox is ONLY created if a
338 // valid reference was found in the dojo.data store or the attribute 'checkboxAll'
339 // is set to true. If the current state is 'undefined' no reference was found and
340 // 'checkboxAll' is set to false.
341 // Note: the attribute 'checkboxAll' is validated by the getCheckboxState function
342 // therefore no need to do that here. (see getCheckboxState for details).
344 var currState
= this.tree
.model
.getCheckboxState( this.item
);
345 if( currState
!== undefined ) {
346 this._checkbox
= new dijit
.form
.CheckBox();
347 //this._checkbox = dojo.doc.createElement('input');
348 this._checkbox
.type
= 'checkbox';
349 this._checkbox
.attr('checked', currState
);
350 dojo
.place(this._checkbox
.domNode
, this.expandoNode
, 'after');
354 postCreate: function() {
356 // Handle the creation of the checkbox after the CheckBoxTreeNode has been instanciated.
358 // Handle the creation of the checkbox after the CheckBoxTreeNode has been instanciated.
359 this._createCheckbox();
360 this.inherited( arguments
);
365 dojo
.declare( "lib.CheckBoxTree", dijit
.Tree
,
368 onNodeChecked: function(/*dojo.data.Item*/ storeItem
, /*treeNode*/ treeNode
) {
370 // Callback when a checkbox tree node is checked
375 onNodeUnchecked: function(/*dojo.data.Item*/ storeItem
, /* treeNode */ treeNode
) {
377 // Callback when a checkbox tree node is unchecked
382 _onClick: function(/*TreeNode*/ nodeWidget
, /*Event*/ e
) {
384 // Translates click events into commands for the controller to process
386 // the _onClick function is called whenever a 'click' is detected. This
387 // instance of _onClick only handles the click events associated with
388 // the checkbox whos DOM name is INPUT.
390 var domElement
= e
.target
;
392 // Only handle checkbox clicks here
393 if(domElement
.type
!= 'checkbox') {
394 return this.inherited( arguments
);
397 this._publish("execute", { item
: nodeWidget
.item
, node
: nodeWidget
} );
398 // Go tell the model to update the checkbox state
400 this.model
.updateCheckbox( nodeWidget
.item
, nodeWidget
._checkbox
.checked
);
401 // Generate some additional events
402 //this.onClick( nodeWidget.item, nodeWidget, e );
403 if(nodeWidget
._checkbox
.checked
) {
404 this.onNodeChecked( nodeWidget
.item
, nodeWidget
);
406 this.onNodeUnchecked( nodeWidget
.item
, nodeWidget
);
408 this.focusNode(nodeWidget
);
411 _onCheckboxChange: function(/*dojo.data.Item*/ storeItem
) {
413 // Processes notification of a change to a checkbox state (triggered by the model).
415 // Whenever the model changes the state of a checkbox in the dojo.data.store it will
416 // trigger the 'onCheckboxChange' event allowing the Tree to make the same changes
417 // on the tree Node. There are several conditions why a tree node or checkbox does not
419 // a) The node has not been created yet (the user has not expanded the tree node yet).
420 // b) The checkbox may be null if condition (a) exists or no 'checkbox' attribute was
421 // specified for the associated dojo.data.item and the attribute 'checkboxAll' is
425 var model
= this.model
,
426 identity
= model
.getIdentity(storeItem
),
427 nodes
= this._itemNodesMap
[identity
];
429 // As of dijit.Tree 1.4 multiple references (parents) are supported, therefore we may have
430 // to update multiple nodes which are all associated with the same dojo.data.item.
432 dojo
.forEach( nodes
, function(node
) {
433 if( node
._checkbox
!= null ) {
434 node
._checkbox
.attr('checked', this.model
.getCheckboxState( storeItem
));
440 postCreate: function() {
442 // Handle any specifics related to the tree and model after the instanciation of the Tree.
444 // Validate if we have a 'write' store first. Subscribe to the 'onCheckboxChange' event
445 // (triggered by the model) and kickoff the initial checkbox data validation.
447 var store
= this.model
.store
;
448 if(!store
.getFeatures()['dojo.data.api.Write']){
449 throw new Error("lib.CheckboxTree: store must support dojo.data.Write");
451 this.connect(this.model
, "onCheckboxChange", "_onCheckboxChange");
452 this.model
.validateData( this.model
.root
, this.model
);
453 this.inherited(arguments
);
456 _createTreeNode: function( args
) {
458 // Create a new CheckboxTreeNode instance.
460 // Create a new CheckboxTreeNode instance.
461 return new lib
._CheckBoxTreeNode(args
);