Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 537 lines (382 sloc) 21.868 kb
fcc4fff Peter E Higgins monster commit from moinconverter, which is always done prior to the svn...
phiggins42 authored
1 .. _dijit/Tree:
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
2
f89feb8 Bill Keese regex change of level 1 headers to ====\nTEXT\n==== and level 2 headers ...
wkeese authored
3 ==========
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
4 dijit.Tree
5 ==========
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
6
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
7 :Authors: Bill Keese, Nikolai Onken, Marcus Reimann
8 :Developers: Bill Keese
9 :Available: since V0.9
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
10
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
11 .. contents::
12 :depth: 2
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
13
48e6bb0 Bill Keese break long lines
wkeese authored
14 The trees we see in User Interfaces help sort out long, hierarchical lists.
15 A file system is the classic example, with Windows using it in Explorer.
16 The Dijit tree widget is like that.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
17
48e6bb0 Bill Keese break long lines
wkeese authored
18 Dojo makes easy trees easy, and hard trees possible.
19 In particular, you can:
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
20
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
21 * Connect your tree to any dojo.data store implementing the Identity API, with or without a single root item, and with various ways to express parent/child relationships
22 * Nest items to an arbitrary depth ... each branch is independently expandable
23 * Apply different icons to different leaf or branch items
24 * Setup a global handler for when a user clicks or double clicks a particular nodes.
25 * Tree will automatically reflect changes made to the underlying data store (when connected to the data store through the :ref:`TreeStoreModel <dijit/tree/TreeStoreModel>` or :ref:`ForestStoreModel <dijit/tree/ForestStoreModel>`)
26 * Allow nodes to be dragged and dropped through the familiar Dojo DnD API.
27 * Drag and drop onto the tree, which updates the data store indirectly
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
28
29
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
30 Components Involved In A Tree
31 =============================
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
32
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
33 To understand how to use a Tree, you need to be aware of three components that feed each other:
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
34
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
35 Tree
36 ----
48e6bb0 Bill Keese break long lines
wkeese authored
37 The Tree widget itself is merely a view of the data.
38 It's in charge of displaying the data and handling user events only.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
39
48e6bb0 Bill Keese break long lines
wkeese authored
40 The Tree is a black-box in the sense that the developer generally won't be dealing with individual nodes of the Tree.
41 Rather, there are just onClick() etc.
42 notifications, which refer to the *item* that was clicked.
43 Item is usually an item in the dojo.data store that the tree is connected to.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
44
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
45 Note also that a Tree has an idea of a currently selected item, such as the currently opened folder in a mail program.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
46
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
47 Model
48 -----
48e6bb0 Bill Keese break long lines
wkeese authored
49 The real power comes in the :ref:`tree model <dijit/tree/Model>`, which represents the hierarchical data that the tree will display.
50 Tree can interface to any class implementing the model API,
51 but typically either the :ref:`TreeStoreModel <dijit/tree/TreeStoreModel>` or :ref:`ForestStoreModel <dijit/tree/ForestStoreModel>` are used,
52 both of which themselves interface with the powerful dojo.data API.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
53
48e6bb0 Bill Keese break long lines
wkeese authored
54 It's important to note that the tree is merely a '''view''' onto the model.
55 The model is in charge of tasks like connecting to the data source (often on the server), lazy loading, and notifying the tree of changes to the data.
56 It's also in charge of handle drop operations, when someone drags and drops an item onto the tree.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
57
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
58 To put it another way, you cannot "delete data from the tree" or "insert data into the tree" directly, but rather you must update the model.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
59
48e6bb0 Bill Keese break long lines
wkeese authored
60 Note also that each item in your Tree needs a different identifier (the value of the identifier has to be unique).
61 It's the same concept as a primary key in a database.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
62
63
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
64 Data Stores
65 -----------
66 Although not required, usually the model interfaces with a dojo.data store.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
67
48e6bb0 Bill Keese break long lines
wkeese authored
68 There can be many different types of stores, such as stores that work from XML vs.
69 stores that work from JSON, stores that execute on the client vs.
70 stores that pass through to the server, stores that load data as it's needed or stores that load all the data on initialization, etc.
71 All the stores, though, have the same API, so they can be connected to with either :ref:`TreeStoreModel <dijit/tree/TreeStoreModel>` or :ref:`ForestStoreModel <dijit/tree/ForestStoreModel>`,
72 depending on whether there is a single or multiple top level item in the store.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
73
cd9516d Bill Keese more line breaks
wkeese authored
74 One might wonder why Tree doesn't interface directly with a dojo.data store.
75 There are a number of reasons:
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
76
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
77 * The parent-child relationship of items in the store might not be expressed by a children attribute on the parent item. For relational databases it's the other way around, where the child points to the parent. The dijit.tree.Model code specifies how to trace parent-child relationships for a given data store.
78 * The interface of dojo.data to load children is rather cumbersome... must call _loadItem() on each item in the children[] array, which means that any item in the store needs to know the list of id's of it's children at any time. It's more efficient to not require that, and to lookup children only when they are needed (when the user clicks the expando icon to open the node).
79 * Sometimes developers might use a custom model that doesn't connect to a data store at all.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
80
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
81 Relationship
82 ------------
83 From the simplest point of view, the information flows like this:
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
84
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
85 Data Store --> Model --> Tree
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
86
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
87 That gets more complicated when we think about drag & drop, but we'll address that later.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
88
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
89 A Simple Tree Example
90 =====================
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
91
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
92 We can display a Tree on a page by creating a data store, a model, and the Tree widget itself.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
93
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
94 A programmatic tree
95 -------------------
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
96
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
97 Creating a programmatic tree is very simple:
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
98
1f9b928 Peter E Higgins bulk deprecated removal and normalization
phiggins42 authored
99 .. code-example ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
100
1f9b928 Peter E Higgins bulk deprecated removal and normalization
phiggins42 authored
101 .. js ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
102
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
103 <script type="text/javascript">
104 dojo.require("dojo.data.ItemFileReadStore");
105 dojo.require("dijit.Tree");
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
106
49acd5c Bill Keese change dojo.addOnLoad() --> dojo.ready(), except for:
wkeese authored
107 dojo.ready(function(){
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
108 var store = new dojo.data.ItemFileReadStore({
109 url: "{{dataUrl}}/dijit/tests/_data/countries.json"
110 });
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
111
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
112 var treeModel = new dijit.tree.ForestStoreModel({
113 store: store,
114 query: {"type": "continent"},
115 rootId: "root",
116 rootLabel: "Continents",
117 childrenAttrs: ["children"]
118 });
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
119
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
120 new dijit.Tree({
121 model: treeModel
122 }, "treeOne");
123 });
124 </script>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
125
1f9b928 Peter E Higgins bulk deprecated removal and normalization
phiggins42 authored
126 .. html ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
127
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
128 <div id="treeOne"></div>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
129
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
130 Note that the childrenAttrs parameter to TreeStoreModel/ForestStoreModel is an array since it can list multiple attributes in the store.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
131
132
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
133 A markup tree
134 -------------
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
135
1f9b928 Peter E Higgins bulk deprecated removal and normalization
phiggins42 authored
136 .. code-example ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
137
1f9b928 Peter E Higgins bulk deprecated removal and normalization
phiggins42 authored
138 .. js ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
139
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
140 <script type="text/javascript">
141 dojo.require("dojo.data.ItemFileReadStore");
142 dojo.require("dijit.Tree");
143 </script>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
144
1f9b928 Peter E Higgins bulk deprecated removal and normalization
phiggins42 authored
145 .. html ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
146
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
147 <div data-dojo-type="dojo.data.ItemFileReadStore" data-dojo-id="continentStore"
148 data-dojo-props="url:'{{dataUrl}}/dijit/tests/_data/countries.json'"></div>
149 <div data-dojo-type="dijit.tree.ForestStoreModel" data-dojo-id="continentModel"
150 data-dojo-props="store:continentStore, query:{type:'continent'},
151 rootId:'continentRoot', rootLabel:'Continents', childrenAttrs:'children'"></div>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
152
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
153 <div data-dojo-type="dijit.Tree" id="mytree"
154 data-dojo-props="model:continentModel, openOnClick:true">
155 <script type="dojo/method" data-dojo-event="onClick" data-dojo-args="item">
156 alert("Execute of node " + continentStore.getLabel(item)
157 +", population=" + continentStore.getValue(item, "population"));
158 </script>
159 </div>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
160
161
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
162 Icons
163 =====
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
164
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
165 Each node in the tree has an icon.
166 Like other dijits, the icon is expressed as a CSS class (which should load a background-image).
167 You specify the class per item by overriding dijit.Tree's getIconClass().
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
168
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
169 The default implementation of getIconClass() shows two types of icons: folders and leafs.
170 (Actually, it has separate icons for opened and closed folders, so that's three icons...)
171 It tries to guess if the node is a folder or not by whether or not it has a children attribute:
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
172
c49c87d Peter E Higgins normalization
phiggins42 authored
173 .. js ::
ffa767c Peter E Higgins removing :linenos: rather than reverting previous commit. revert both fo...
phiggins42 authored
174
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
175 getIconClass: function(/*dojo.data.Item*/ item, /*Boolean*/ opened){
176 return (!item || this.model.mayHaveChildren(item)) ? (opened ? "dijitFolderOpened" : "dijitFolderClosed") : "dijitLeaf"
177 },
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
178
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
179 Note that the !item check refers to the root node in the tree,
180 which may not have any associated item when using the old version of the Tree API,
181 connecting the Tree directly to a store instead of using a model.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
182
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
183 That works fairly well, but will fail if mayHaveChildren() returns false for items with no children.
184 The definition of mayHaveChildren() for "empty folders" is actually somewhat vague, so it's best not to depend on it.
185 A better getIconClass() method for a Tree connected (through a model) to a :ref:`dojox.data.FileStore <dojox/data/FileStore>`
186 would determine if the item was a folder or not based on whether or not the item had the "directory" attribute
187 (and it was set to true):
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
188
c49c87d Peter E Higgins normalization
phiggins42 authored
189 .. js ::
ffa767c Peter E Higgins removing :linenos: rather than reverting previous commit. revert both fo...
phiggins42 authored
190
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
191 getIconClass: function(/*dojo.data.Item*/ item, /*Boolean*/ opened){
192 return myStore.getValue(item, 'directory') ? (opened ? "dijitFolderOpened" : "dijitFolderClosed") : "dijitLeaf";
193 },
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
194
195
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
196 If you want to have different icon types depending on the type of items in the tree (for example,
197 separate icons for songs, movies, and TV shows), then you really need to override the method
198 to return a separate class name based on the type of item:
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
199
c49c87d Peter E Higgins normalization
phiggins42 authored
200 .. js ::
ffa767c Peter E Higgins removing :linenos: rather than reverting previous commit. revert both fo...
phiggins42 authored
201
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
202 <script type="dojo/method" data-dojo-event="getIconClass" data-dojo-args="item, opened">
67f7d9e Bill Keese Fix spacing for braces, function(), if(), while(), for(), else, etc. to ...
wkeese authored
203 if(item == this.model.root){
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
204 return (opened ? "customFolderOpenedIcon" : "customFolderClosedIcon");
67f7d9e Bill Keese Fix spacing for braces, function(), if(), while(), for(), else, etc. to ...
wkeese authored
205 }else{
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
206 return myStore.getValue(item, "type") + "Icon";
207 }
208 </script>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
209
210
211
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
212 Hiding a Tree's root node
213 =========================
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
214
48e6bb0 Bill Keese break long lines
wkeese authored
215 There's always a single root item for a Tree, returned by the model's getRoot() method.
216 It might be a real item from the store (such as a tree of employees, with the CEO as the root),
217 or it if there's no single root item in the store (like if the store lists continents but the top item, "the world", is implied, the model is responsible for fabricating such a root item (from the perspective of the tree).
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
218
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
219 Correspondingly, all trees have a root node, corresponding to the root "item" from the model.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
220
48e6bb0 Bill Keese break long lines
wkeese authored
221 Sometimes you don't want that "the world" top level node to show up,
222 especially if the Tree is inside a TitlePane/AccordionPane/etc. with the label "The World".
223 In that case you should set showRoot=false.
224 The item still exists in the model but it's hidden on the screen:
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
225
1f9b928 Peter E Higgins bulk deprecated removal and normalization
phiggins42 authored
226 .. code-example ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
227
1f9b928 Peter E Higgins bulk deprecated removal and normalization
phiggins42 authored
228 .. js ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
229
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
230 <script type="text/javascript">
231 dojo.require("dojo.data.ItemFileReadStore");
232 dojo.require("dijit.Tree");
233 </script>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
234
1f9b928 Peter E Higgins bulk deprecated removal and normalization
phiggins42 authored
235 .. html ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
236
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
237 <div data-dojo-type="dojo.data.ItemFileReadStore" data-dojo-id="continentStore"
238 data-dojo-props="url:'{{dataUrl}}/dijit/tests/_data/countries.json'"></div>
239 <div data-dojo-type="dijit.tree.ForestStoreModel" data-dojo-id="continentModel"
240 data-dojo-props="store:continentStore, query:{type:'continent'},
241 rootId:'continentRoot', rootLabel:'Continents', childrenAttrs:'children'"></div>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
242
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
243 <div data-dojo-type="dijit.Tree" id="mytree2"
244 data-dojo-props="model:continentModel, showRoot:false">
245 </div>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
246
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
247 Note that you can hide or show the root item regardless of whether that root item is fabricated or corresponds to a real item in the store.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
248
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
249 Updating a Tree
250 ===============
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
251
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
252 People often ask:
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
253
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
254 * how do I update a tree (adding or deleting items)?
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
255
48e6bb0 Bill Keese break long lines
wkeese authored
256 You can't update the tree directly, but rather you need to update the model.
257 Usually the model is connected to a data store and in that case you need to update the data store.
258 Thus, you need to use a data store that allows updates (through it's official API), like :ref:`dojo.data.ItemFileWriteStore <dojo/data/ItemFileWriteStore>`.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
259
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
260 * how do I refresh a Tree from the store?
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
261
48e6bb0 Bill Keese break long lines
wkeese authored
262 This isn't supported.
263 The store needs to notify the tree of any changes to the data.
264 Currently this is really only supported (out of the box) by :ref:`dojo.data.ItemFileWriteStore <dojo/data/ItemFileWriteStore>`,
265 as setting up a client-server dojo.data source where the server notifies the client whenever the data has changed is quite complicated, and beyond the scope of dojo, which is a client-only solution.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
266
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
267 Lazy Loading A Tree
268 ===================
48e6bb0 Bill Keese break long lines
wkeese authored
269 People often ask how to lazy-load a tree, but this question is really unrelated to the Tree itself.
270 If you use a data store that is lazy loading, such as :ref:`dojox.data.QueryReadStore <dojox/data/QueryReadStore>` or :ref:`dojox.data.JsonRestStore <dojox/data/JsonRestStore>`,
271 then the data will be loaded lazily.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
272
273
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
274 Drag And Drop
275 =============
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
276
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
277 Tree's support drag and drop, meaning that a user can:
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
278
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
279 * drop an item onto the tree
280 * drag an item from the tree
281 * move items within the tree
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
282
48e6bb0 Bill Keese break long lines
wkeese authored
283 In the first and last case (ie, when an item is dropped onto the tree), the drop is processed by the model, which in turn sends it to the data store (updating the underlying data).
284 Thus:
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
285
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
286 * the model must implement the pasteItem() method
287 * the store must implement the :ref:`dojo.data.api.Write <dojo/data/api/Write>` interface
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
288
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
289 In addition, to enable DnD on the Tree you must dojo.require("dijit.tree.dndSource"); and the dndController="dijit.tree.dndSource" parameter must be specified to the tree
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
290
291
1f9b928 Peter E Higgins bulk deprecated removal and normalization
phiggins42 authored
292 .. code-example ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
293
1f9b928 Peter E Higgins bulk deprecated removal and normalization
phiggins42 authored
294 .. js ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
295
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
296 <script type="text/javascript">
297 dojo.require("dojo.data.ItemFileWriteStore");
298 dojo.require("dijit.tree.ForestStoreModel");
299 dojo.require("dijit.tree.dndSource");
300 dojo.require("dijit.Tree");
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
301
49acd5c Bill Keese change dojo.addOnLoad() --> dojo.ready(), except for:
wkeese authored
302 dojo.ready(function(){
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
303 var store = new dojo.data.ItemFileWriteStore({
304 url: "{{dataUrl}}/dijit/tests/_data/countries.json"
305 });
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
306
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
307 var treeModel = new dijit.tree.ForestStoreModel({
308 store: store,
309 query: {"type": "continent"},
310 rootId: "root",
311 rootLabel: "Continents",
312 childrenAttrs: ["children"]
313 });
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
314
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
315 new dijit.Tree({
316 model: treeModel,
317 dndController: "dijit.tree.dndSource"
318 }, "treeThree");
319 });
320 </script>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
321
1f9b928 Peter E Higgins bulk deprecated removal and normalization
phiggins42 authored
322 .. html ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
323
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
324 <div id="treeThree"></div>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
325
326
cd9516d Bill Keese more line breaks
wkeese authored
327 You can also specify custom checkAcceptance() and checkItemAcceptance() to accept/reject items to the tree.
328 (The former function operates at the Tree level, and the latter operates per Tree node,
329 allowing things like rejecting dropping items onto leaf nodes.)
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
330
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
331 Further examples
332 ----------------
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
333
48e6bb0 Bill Keese break long lines
wkeese authored
334 If you are interested in further examples, please make sure you have glanced at the unit tests.
335 For the 1.5 release, you can find a good example here: http://download.dojotoolkit.org/release-1.5.0/dojo-release-1.5.0/dijit/tests/tree/test_Tree_DnD.html
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
336
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
337 betweenThreshold
338 ----------------
48e6bb0 Bill Keese break long lines
wkeese authored
339 If between threshold is set to a positive integer value like 5 (which represents 5 pixels), then when dragging within 5px of the top or bottom of a tree node, it's interpreted as trying to make the drag source the previous or next sibling of the drop target, rather than the child of the drop target.
340 This is useful for when a user can control the order of the children of the child nodes:
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
341
1f9b928 Peter E Higgins bulk deprecated removal and normalization
phiggins42 authored
342 .. code-example ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
343
1f9b928 Peter E Higgins bulk deprecated removal and normalization
phiggins42 authored
344 .. js ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
345
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
346 <script type="text/javascript">
347 dojo.require("dojo.data.ItemFileWriteStore");
348 dojo.require("dijit.tree.ForestStoreModel");
349 dojo.require("dijit.tree.dndSource");
350 dojo.require("dijit.Tree");
351 </script>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
352
1f9b928 Peter E Higgins bulk deprecated removal and normalization
phiggins42 authored
353 .. html ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
354
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
355 <div data-dojo-type="dojo.data.ItemFileWriteStore" data-dojo-id="continentStore5"
356 data-dojo-props="url:'{{dataUrl}}/dijit/tests/_data/countries.json'"></div>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
357
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
358 <div data-dojo-type="dijit.tree.ForestStoreModel" data-dojo-id="continentModel5"
359 data-dojo-props="store:continentStore5, query:{type:'continent'},
360 rootId:'continentRoot', rootLabel:'Continents', childrenAttrs:'children'"></div>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
361
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
362 <div data-dojo-type="dijit.Tree" id="mytree5"
363 data-dojo-props="dndController:'dijit.tree.dndSource', betweenThreshold:5, showRoot:false,
364 model:continentModel5, openOnClick:true">
365 </div>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
366
367
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
368 Behind the scenes
369 -----------------
48e6bb0 Bill Keese break long lines
wkeese authored
370 What happens when a user moves an item from one position in a tree to another?
371 It's actually quite complicated...
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
372
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
373 1. The Tree widget does not change it's display at all. Rather, it notifies the model of the paste operation.
374 2. The model updates the store.
375 3. The store notifies the model that the data has been changed.
376 4. The model notifies the tree of the change (presumably the children list of nodeA is one shorter, and the children list of nodeB has a new entry)
377 5. The Tree updates it's display.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
378
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
379 In this way, the Tree, Model, and data store are always in sync.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
380
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
381 Context Menu
382 ============
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
383
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
384 Tree has no built-in support for context menus, but you can use the Menu widget in conjunction with the Tree
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
385
1f9b928 Peter E Higgins bulk deprecated removal and normalization
phiggins42 authored
386 .. code-example ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
387
1f9b928 Peter E Higgins bulk deprecated removal and normalization
phiggins42 authored
388 .. js ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
389
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
390 <script>
391 dojo.require("dijit.Menu");
392 dojo.require("dijit.MenuItem");
393 dojo.require("dijit.tree.ForestStoreModel");
394 dojo.require("dojo.data.ItemFileReadStore");
395 dojo.require("dijit.Tree");
396 </script>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
397
1f9b928 Peter E Higgins bulk deprecated removal and normalization
phiggins42 authored
398 .. html ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
399
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
400 <ul data-dojo-type="dijit.Menu" id="tree_menu" style="display: none;">
401 <li data-dojo-type="dijit.MenuItem" data-dojo-props="onClick:function(){alert('Hello world');}">Item #1</li>
402 <li data-dojo-type="dijit.MenuItem">Item #2</li>
403 </ul>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
404
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
405 <div data-dojo-type="dojo.data.ItemFileReadStore" data-dojo-id="menuContinentStore"
406 data-dojo-props="url:'{{dataUrl}}/dijit/tests/_data/countries.json'"></div>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
407
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
408 <div data-dojo-type="dijit.tree.ForestStoreModel" data-dojo-id="menuContinentModel"
409 data-dojo-props="store:menuContinentStore, query:{type:'continent'},
410 rootId:'continentRoot', rootLabel:'Continents', childrenAttrs:'children'"></div>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
411
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
412 <div data-dojo-type="dijit.Tree" id="menuTree"
413 data-dojo-props="model:menuContinentModel, showRoot:false, openOnClick:true">
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
414
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
415 <script type="dojo/connect">
416 var menu = dijit.byId("tree_menu");
417 // when we right-click anywhere on the tree, make sure we open the menu
418 menu.bindDomNode(this.domNode);
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
419
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
420 dojo.connect(menu, "_openMyself", this, function(e){
421 // get a hold of, and log out, the tree node that was the source of this open event
422 var tn = dijit.getEnclosingWidget(e.target);
423 console.debug(tn);
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
424
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
425 // now inspect the data store item that backs the tree node:
426 console.debug(tn.item);
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
427
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
428 // contrived condition: if this tree node doesn't have any children, disable all of the menu items
82296e8 Bill Keese for widgets, attr() --> set() and get()
wkeese authored
429 menu.getChildren().forEach(function(i){ i.set('disabled', !tn.item.children); });
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
430
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
431 // IMPLEMENT CUSTOM MENU BEHAVIOR HERE
432 });
433 </script>
434 </div>
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
435
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
436 Styling
437 =======
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
438
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
439 Grid lines
440 ----------
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
441
48e6bb0 Bill Keese break long lines
wkeese authored
442 If you don't want to display the grid lines for a Tree then simply write CSS rules
443 to override the theme and hide the relevant background images.
444 The pertinent lines from tundra are:
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
445
c49c87d Peter E Higgins normalization
phiggins42 authored
446 .. css ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
447
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
448 .tundra .dijitTreeNode {
449 background-image : url('images/i.gif');
450 ...
451 }
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
452
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
453 /* left vertical line (grid) for all nodes */
454 .tundra .dijitTreeIsLast {
455 background: url('images/i_half.gif') no-repeat;
456 ...
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
457
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
458 .tundra .dijitTreeExpandoLeaf {
459 background-image:url(images/treeExpand_leaf.gif);
460 }
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
461
462
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
463 Hover effect
464 ------------
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
465
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
466 Due to implementation details, on the tundra, soria, and nihilo themes the hover effect for tree nodes is done with a near-transparent image:
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
467
c49c87d Peter E Higgins normalization
phiggins42 authored
468 .. css ::
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
469
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
470 .tundra .dijitTreeNodeHover {
471 /*background-color: #f6f9fa !important;*/
472 /* using a transparent png so that we can still see grid lines, which are (unfortunately) behind the dijitRowNode that we are hovering over */
473 background-image: url(images/treeHover.png);
474 background-repeat: repeat;
475 background-color: none !important;
476 }
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
477
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
478 So in order to change the hover effect you would need to create a new image (with for example 95% transparency), and write a CSS rule to override the one above.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
479
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
480 You can also remove the hover effect altogether by just writing a CSS rule that sets background-image to none, overriding the above rule.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
481
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
482 On the claro theme, the hover effect is done via a background-color (combined with a white gradient background image), so changing the hover effect just involves changing that background color.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
483
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
484 Miscellaneous
485 =============
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
486
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
487 Persistence
488 -----------
48e6bb0 Bill Keese break long lines
wkeese authored
489 By default, a Tree will remember which branches were opened/closed.
490 To use this feature you must specify an id for the Tree.
491 To disable the feature, set the "persist" parameter to false.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
492
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
493 More examples
494 =============
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
495
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
496 There are :ref:`more extensive examples <dijit/Tree-examples>` of using the tree
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
497
498
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
499 Accessibility
500 =============
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
501
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
502 Keyboard
503 --------
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
504
3171d1e Bill Keese fix tables
wkeese authored
505 =================================== ===============
506 Action Key
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
507 =================================== ===============
508 Navigate into tree* Tab
509 Navigate to the next sibling Down arrow
510 Navigate to the previous sibling Up arrow
511 Open a subtree Right arrow
512 Close a subtree Left arrow
513 Navigate to open subtree Right arrow
514 Navigate to parent Left arrow
515 Activate a tree item Enter
516 Navigate to first tree node Home
517 Navigate to last visible tree node End
518 =================================== ===============
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
519
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
520 * Note: The most recently focused tree item will be in the Tab order.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
521
522
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
523 Keyboard searching
524 ------------------
48e6bb0 Bill Keese break long lines
wkeese authored
525 Tree items can also be accessed by typing alphanumeric characters.
526 For example, typing "A" will navigate from the currently focused node to the next node that begins with the letter A (case insensitive).
527 Typing "Al" will navigate to the next node that starts with "Al".
528 Only the nodes that are visible are searched, not nodes that are hidden inside a closed node.
529 The nodes are searched in the order that they appear on the screen, from the focused node downwards and then looping back up to the top of the tree.
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
530
9dd52dc Peter E Higgins mondo whitespace change
phiggins42 authored
531 Known Issues
532 ------------
d608cc5 Peter E Higgins \r\n -> \n conversion.
phiggins42 authored
533
48e6bb0 Bill Keese break long lines
wkeese authored
534 Using JAWS 10 in Firefox 3 the properties of each tree item are spoken including the open/close state and the level information.
535 Using JAWS 10 with IE 8, the open/close state of each item is spoken but the level information is not spoken.
536 In both Firefox 3 and IE 8 the JAWS user should be in App mode or virtual pc cursor off mode for best performance (toggle the mode via the insert+z key).
Something went wrong with that request. Please try again.