]>
Commit | Line | Data |
---|---|---|
a3e2f1a9 AD |
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 | define(["dojo/_base/declare", "dijit/tree/TreeStoreModel"], function (declare) { | |
13 | ||
14 | return declare( "lib.CheckBoxStoreModel", dijit.tree.TreeStoreModel, | |
15 | { | |
16 | // checkboxAll: Boolean | |
17 | // If true, every node in the tree will receive a checkbox regardless if the 'checkbox' attribute | |
18 | // is specified in the dojo.data. | |
19 | checkboxAll: true, | |
20 | ||
21 | // checkboxState: Boolean | |
22 | // The default state applied to every checkbox unless otherwise specified in the dojo.data. | |
23 | // (see also: checkboxIdent) | |
24 | checkboxState: false, | |
25 | ||
26 | // checkboxRoot: Boolean | |
27 | // If true, the root node will receive a checkbox eventhough it's not a true entry in the store. | |
28 | // This attribute is independent of the showRoot attribute of the tree itself. If the tree | |
29 | // attribute 'showRoot' is set to false to checkbox for the root will not show either. | |
30 | checkboxRoot: false, | |
31 | ||
32 | // checkboxStrict: Boolean | |
33 | // If true, a strict parent-child checkbox relation is maintained. For example, if all children | |
34 | // are checked the parent will automatically be checked or if any of the children are unchecked | |
35 | // the parent will be unchecked. | |
36 | checkboxStrict: true, | |
37 | ||
38 | // checkboxIdent: String | |
39 | // The attribute name (attribute of the dojo.data.item) that specifies that items checkbox initial | |
40 | // state. Example: { name:'Egypt', type:'country', checkbox: true } | |
41 | // If a dojo.data.item has no 'checkbox' attribute specified it will depend on the attribute | |
42 | // 'checkboxAll' if one will be created automatically and if so what the initial state will be as | |
43 | // specified by 'checkboxState'. | |
44 | checkboxIdent: "checkbox", | |
45 | ||
46 | updateCheckbox: function(/*dojo.data.Item*/ storeItem, /*Boolean*/ newState ) { | |
47 | // summary: | |
48 | // Update the checkbox state (true/false) for the item and the associated parent and | |
49 | // child checkboxes if any. | |
50 | // description: | |
51 | // Update a single checkbox state (true/false) for the item and the associated parent | |
52 | // and child checkboxes if any. This function is called from the tree if a user checked | |
53 | // or unchecked a checkbox on the tree. The parent and child tree nodes are updated to | |
54 | // maintain consistency if 'checkboxStrict' is set to true. | |
55 | // storeItem: | |
56 | // The item in the dojo.data.store whos checkbox state needs updating. | |
57 | // newState: | |
58 | // The new state of the checkbox: true or false | |
59 | // example: | |
60 | // | model.updateCheckboxState(item, true); | |
61 | // | |
62 | ||
63 | this._setCheckboxState( storeItem, newState ); | |
64 | //if( this.checkboxStrict ) { I don't need all this 1-1 stuff, only parent -> child (fox) | |
65 | this._updateChildCheckbox( storeItem, newState ); | |
66 | //this._updateParentCheckbox( storeItem, newState ); | |
67 | //} | |
68 | }, | |
69 | setAllChecked: function(checked) { | |
70 | var items = this.store._arrayOfAllItems; | |
71 | this.setCheckboxState(items, checked); | |
72 | }, | |
73 | setCheckboxState: function(items, checked) { | |
74 | for (var i = 0; i < items.length; i++) { | |
75 | this._setCheckboxState(items[i], checked); | |
76 | } | |
77 | }, | |
78 | getCheckedItems: function() { | |
79 | var items = this.store._arrayOfAllItems; | |
80 | var result = []; | |
81 | ||
82 | for (var i = 0; i < items.length; i++) { | |
83 | if (this.store.getValue(items[i], 'checkbox')) | |
84 | result.push(items[i]); | |
85 | } | |
86 | ||
87 | return result; | |
88 | }, | |
89 | ||
90 | getCheckboxState: function(/*dojo.data.Item*/ storeItem) { | |
91 | // summary: | |
92 | // Get the current checkbox state from the dojo.data.store. | |
93 | // description: | |
94 | // Get the current checkbox state from the dojo.data store. A checkbox can have three | |
95 | // different states: true, false or undefined. Undefined in this context means no | |
96 | // checkbox identifier (checkboxIdent) was found in the dojo.data store. Depending on | |
97 | // the checkbox attributes as specified above the following will take place: | |
98 | // a) If the current checkbox state is undefined and the checkbox attribute 'checkboxAll' or | |
99 | // 'checkboxRoot' is true one will be created and the default state 'checkboxState' will | |
100 | // be applied. | |
101 | // b) If the current state is undefined and 'checkboxAll' is false the state undefined remains | |
102 | // unchanged and is returned. This will prevent any tree node from creating a checkbox. | |
103 | // | |
104 | // storeItem: | |
105 | // The item in the dojo.data.store whos checkbox state is returned. | |
106 | // example: | |
107 | // | var currState = model.getCheckboxState(item); | |
108 | // | |
109 | var currState = undefined; | |
110 | ||
111 | // Special handling required for the 'fake' root entry (the root is NOT a dojo.data.item). | |
112 | // this stuff is only relevant for Forest store -fox | |
113 | /* if ( storeItem == this.root ) { | |
114 | if( typeof(storeItem.checkbox) == "undefined" ) { | |
115 | this.root.checkbox = undefined; // create a new checbox reference as undefined. | |
116 | if( this.checkboxRoot ) { | |
117 | currState = this.root.checkbox = this.checkboxState; | |
118 | } | |
119 | } else { | |
120 | currState = this.root.checkbox; | |
121 | } | |
122 | } else { // a valid dojo.store.item | |
123 | currState = this.store.getValue(storeItem, this.checkboxIdent); | |
124 | if( currState == undefined && this.checkboxAll) { | |
125 | this._setCheckboxState( storeItem, this.checkboxState ); | |
126 | currState = this.checkboxState; | |
127 | } | |
128 | } */ | |
129 | ||
130 | currState = this.store.getValue(storeItem, this.checkboxIdent); | |
131 | if( currState == undefined && this.checkboxAll) { | |
132 | this._setCheckboxState( storeItem, this.checkboxState ); | |
133 | currState = this.checkboxState; | |
134 | } | |
135 | ||
136 | return currState; // the current state of the checkbox (true/false or undefined) | |
137 | }, | |
138 | ||
139 | _setCheckboxState: function(/*dojo.data.Item*/ storeItem, /*Boolean*/ newState ) { | |
140 | // summary: | |
141 | // Set/update the checkbox state on the dojo.data store. | |
142 | // description: | |
143 | // Set/update the checkbox state on the dojo.data.store. Retreive the current | |
144 | // state of the checkbox and validate if an update is required, this will keep | |
145 | // update events to a minimum. On completion a 'onCheckboxChange' event is | |
146 | // triggered. | |
147 | // If the current state is undefined (ie: no checkbox attribute specified for | |
148 | // this dojo.data.item) the 'checkboxAll' attribute is checked to see if one | |
149 | // needs to be created. In case of the root the 'checkboxRoot' attribute is checked. | |
150 | // NOTE: the store.setValue function will create the 'checkbox' attribute for the | |
151 | // item if none exists. | |
152 | // storeItem: | |
153 | // The item in the dojo.data.store whos checkbox state is updated. | |
154 | // newState: | |
155 | // The new state of the checkbox: true or false | |
156 | // example: | |
157 | // | model.setCheckboxState(item, true); | |
158 | // | |
159 | var stateChanged = true; | |
160 | ||
161 | if( storeItem != this.root ) { | |
162 | var currState = this.store.getValue(storeItem, this.checkboxIdent); | |
163 | if( currState != newState && ( currState !== undefined || this.checkboxAll ) ) { | |
164 | this.store.setValue(storeItem, this.checkboxIdent, newState); | |
165 | } else { | |
166 | stateChanged = false; // No changes to the checkbox | |
167 | } | |
168 | } else { // Tree root instance | |
169 | if( this.root.checkbox != newState && ( this.root.checkbox !== undefined || this.checkboxRoot ) ) { | |
170 | this.root.checkbox = newState; | |
171 | } else { | |
172 | stateChanged = false; | |
173 | } | |
174 | } | |
175 | if( stateChanged ) { // In case of any changes trigger the update event. | |
176 | this.onCheckboxChange(storeItem); | |
177 | } | |
178 | return stateChanged; | |
179 | }, | |
180 | ||
181 | _updateChildCheckbox: function(/*dojo.data.Item*/ parentItem, /*Boolean*/ newState ) { | |
182 | // summary: | |
183 | // Set all child checkboxes to true/false depending on the parent checkbox state. | |
184 | // description: | |
185 | // If a parent checkbox changes state, all child and grandchild checkboxes will be | |
186 | // updated to reflect the change. For example, if the parent state is set to true, | |
187 | // all child and grandchild checkboxes will receive that same 'true' state. | |
188 | // If a child checkbox changes state and has multiple parent, all of its parents | |
189 | // need to be re-evaluated. | |
190 | // parentItem: | |
191 | // The parent dojo.data.item whos child/grandchild checkboxes require updating. | |
192 | // newState: | |
193 | // The new state of the checkbox: true or false | |
194 | // | |
195 | ||
196 | if( this.mayHaveChildren( parentItem )) { | |
197 | this.getChildren( parentItem, dojo.hitch( this, | |
198 | function( children ) { | |
199 | dojo.forEach( children, function(child) { | |
200 | if( this._setCheckboxState(child, newState) ) { | |
201 | var parents = this._getParentsItem(child); | |
202 | if( parents.length > 1 ) { | |
203 | this._updateParentCheckbox( child, newState ); | |
204 | } | |
205 | } | |
206 | if( this.mayHaveChildren( child )) { | |
207 | this._updateChildCheckbox( child, newState ); | |
208 | } | |
209 | }, this ); | |
210 | }), | |
211 | function(err) { | |
212 | console.error(this, ": updating child checkboxes: ", err); | |
213 | } | |
214 | ); | |
215 | } | |
216 | }, | |
217 | ||
218 | _updateParentCheckbox: function(/*dojo.data.Item*/ storeItem, /*Boolean*/ newState ) { | |
219 | // summary: | |
220 | // Update the parent checkbox state depending on the state of all child checkboxes. | |
221 | // description: | |
222 | // Update the parent checkbox state depending on the state of all child checkboxes. | |
223 | // The parent checkbox automatically changes state if ALL child checkboxes are true | |
224 | // or false. If, as a result, the parent checkbox changes state, we will check if | |
225 | // its parent needs to be updated as well all the way upto the root. | |
226 | // storeItem: | |
227 | // The dojo.data.item whos parent checkboxes require updating. | |
228 | // newState: | |
229 | // The new state of the checkbox: true or false | |
230 | // | |
231 | var parents = this._getParentsItem(storeItem); | |
232 | dojo.forEach( parents, function( parentItem ) { | |
233 | if( newState ) { // new state = true (checked) | |
234 | this.getChildren( parentItem, dojo.hitch( this, | |
235 | function(siblings) { | |
236 | var allChecked = true; | |
237 | dojo.some( siblings, function(sibling) { | |
238 | siblState = this.getCheckboxState(sibling); | |
239 | if( siblState !== undefined && allChecked ) | |
240 | allChecked = siblState; | |
241 | return !(allChecked); | |
242 | }, this ); | |
243 | if( allChecked ) { | |
244 | this._setCheckboxState( parentItem, true ); | |
245 | this._updateParentCheckbox( parentItem, true ); | |
246 | } | |
247 | }), | |
248 | function(err) { | |
249 | console.error(this, ": updating parent checkboxes: ", err); | |
250 | } | |
251 | ); | |
252 | } else { // new state = false (unchecked) | |
253 | if( this._setCheckboxState( parentItem, false ) ) { | |
254 | this._updateParentCheckbox( parentItem, false ); | |
255 | } | |
256 | } | |
257 | }, this ); | |
258 | }, | |
259 | ||
260 | _getParentsItem: function(/*dojo.data.Item*/ storeItem ) { | |
261 | // summary: | |
262 | // Get the parent(s) of a dojo.data item. | |
263 | // description: | |
264 | // Get the parent(s) of a dojo.data item. The '_reverseRefMap' entry of the item is | |
265 | // used to identify the parent(s). A child will have a parent reference if the parent | |
266 | // specified the '_reference' attribute. | |
267 | // For example: children:[{_reference:'Mexico'}, {_reference:'Canada'}, ... | |
268 | // storeItem: | |
269 | // The dojo.data.item whos parent(s) will be returned. | |
270 | // | |
271 | var parents = []; | |
272 | ||
273 | if( storeItem != this.root ) { | |
274 | var references = storeItem[this.store._reverseRefMap]; | |
275 | for(itemId in references ) { | |
276 | parents.push(this.store._itemsByIdentity[itemId]); | |
277 | } | |
278 | if (!parents.length) { | |
279 | parents.push(this.root); | |
280 | } | |
281 | } | |
282 | return parents; // parent(s) of a dojo.data.item (Array of dojo.data.items) | |
283 | }, | |
284 | ||
285 | validateData: function(/*dojo.data.Item*/ storeItem, /*thisObject*/ scope ) { | |
286 | // summary: | |
287 | // Validate/normalize the parent(s) checkbox data in the dojo.data store. | |
288 | // description: | |
289 | // Validate/normalize the parent-child checkbox relationship if the attribute | |
290 | // 'checkboxStrict' is set to true. This function is called as part of the post | |
291 | // creation of the Tree instance. All parent checkboxes are set to the appropriate | |
292 | // state according to the actual state(s) of their children. | |
293 | // This will potentionally overwrite whatever was specified for the parent in the | |
294 | // dojo.data store. This will garantee the tree is in a consistent state after startup. | |
295 | // storeItem: | |
296 | // The element to start traversing the dojo.data.store, typically model.root | |
297 | // scope: | |
298 | // The scope to use when this method executes. | |
299 | // example: | |
300 | // | this.model.validateData(this.model.root, this.model); | |
301 | // | |
302 | if( !scope.checkboxStrict ) { | |
303 | return; | |
304 | } | |
305 | scope.getChildren( storeItem, dojo.hitch( scope, | |
306 | function(children) { | |
307 | var allChecked = true; | |
308 | var childState; | |
309 | dojo.forEach( children, function( child ) { | |
310 | if( this.mayHaveChildren( child )) { | |
311 | this.validateData( child, this ); | |
312 | } | |
313 | childState = this.getCheckboxState( child ); | |
314 | if( childState !== undefined && allChecked ) | |
315 | allChecked = childState; | |
316 | }, this); | |
317 | ||
318 | if ( this._setCheckboxState( storeItem, allChecked) ) { | |
319 | this._updateParentCheckbox( storeItem, allChecked); | |
320 | } | |
321 | }), | |
322 | function(err) { | |
323 | console.error(this, ": validating checkbox data: ", err); | |
324 | } | |
325 | ); | |
326 | }, | |
327 | ||
328 | onCheckboxChange: function(/*dojo.data.Item*/ storeItem ) { | |
329 | // summary: | |
330 | // Callback whenever a checkbox state has changed state, so that | |
331 | // the Tree can update the checkbox. This callback is generally | |
332 | // triggered by the '_setCheckboxState' function. | |
333 | // tags: | |
334 | // callback | |
335 | } | |
336 | ||
337 | }); | |
338 | ||
339 | }); | |
340 | ||
341 |