Upgrade to ExtJS 3.1.0 - Released 12/16/2009
[extjs.git] / docs / source / TreeLoader.html
1 <html>\r
2 <head>\r
3   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
4   <title>The source code</title>\r
5     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
6     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
7 </head>\r
8 <body  onload="prettyPrint();">\r
9     <pre class="prettyprint lang-js"><div id="cls-Ext.tree.TreeLoader"></div>/**\r
10  * @class Ext.tree.TreeLoader\r
11  * @extends Ext.util.Observable\r
12  * A TreeLoader provides for lazy loading of an {@link Ext.tree.TreeNode}'s child\r
13  * nodes from a specified URL. The response must be a JavaScript Array definition\r
14  * whose elements are node definition objects. e.g.:\r
15  * <pre><code>\r
16     [{\r
17         id: 1,\r
18         text: 'A leaf Node',\r
19         leaf: true\r
20     },{\r
21         id: 2,\r
22         text: 'A folder Node',\r
23         children: [{\r
24             id: 3,\r
25             text: 'A child Node',\r
26             leaf: true\r
27         }]\r
28    }]\r
29 </code></pre>\r
30  * <br><br>\r
31  * A server request is sent, and child nodes are loaded only when a node is expanded.\r
32  * The loading node's id is passed to the server under the parameter name "node" to\r
33  * enable the server to produce the correct child nodes.\r
34  * <br><br>\r
35  * To pass extra parameters, an event handler may be attached to the "beforeload"\r
36  * event, and the parameters specified in the TreeLoader's baseParams property:\r
37  * <pre><code>\r
38     myTreeLoader.on("beforeload", function(treeLoader, node) {\r
39         this.baseParams.category = node.attributes.category;\r
40     }, this);\r
41 </code></pre>\r
42  * This would pass an HTTP parameter called "category" to the server containing\r
43  * the value of the Node's "category" attribute.\r
44  * @constructor\r
45  * Creates a new Treeloader.\r
46  * @param {Object} config A config object containing config properties.\r
47  */\r
48 Ext.tree.TreeLoader = function(config){\r
49     this.baseParams = {};\r
50     Ext.apply(this, config);\r
51 \r
52     this.addEvents(\r
53         <div id="event-Ext.tree.TreeLoader-beforeload"></div>/**\r
54          * @event beforeload\r
55          * Fires before a network request is made to retrieve the Json text which specifies a node's children.\r
56          * @param {Object} This TreeLoader object.\r
57          * @param {Object} node The {@link Ext.tree.TreeNode} object being loaded.\r
58          * @param {Object} callback The callback function specified in the {@link #load} call.\r
59          */\r
60         "beforeload",\r
61         <div id="event-Ext.tree.TreeLoader-load"></div>/**\r
62          * @event load\r
63          * Fires when the node has been successfuly loaded.\r
64          * @param {Object} This TreeLoader object.\r
65          * @param {Object} node The {@link Ext.tree.TreeNode} object being loaded.\r
66          * @param {Object} response The response object containing the data from the server.\r
67          */\r
68         "load",\r
69         <div id="event-Ext.tree.TreeLoader-loadexception"></div>/**\r
70          * @event loadexception\r
71          * Fires if the network request failed.\r
72          * @param {Object} This TreeLoader object.\r
73          * @param {Object} node The {@link Ext.tree.TreeNode} object being loaded.\r
74          * @param {Object} response The response object containing the data from the server.\r
75          */\r
76         "loadexception"\r
77     );\r
78     Ext.tree.TreeLoader.superclass.constructor.call(this);\r
79     if(Ext.isString(this.paramOrder)){\r
80         this.paramOrder = this.paramOrder.split(/[\s,|]/);\r
81     }\r
82 };\r
83 \r
84 Ext.extend(Ext.tree.TreeLoader, Ext.util.Observable, {\r
85     <div id="cfg-Ext.tree.TreeLoader-dataUrl"></div>/**\r
86     * @cfg {String} dataUrl The URL from which to request a Json string which\r
87     * specifies an array of node definition objects representing the child nodes\r
88     * to be loaded.\r
89     */\r
90     <div id="cfg-Ext.tree.TreeLoader-requestMethod"></div>/**\r
91      * @cfg {String} requestMethod The HTTP request method for loading data (defaults to the value of {@link Ext.Ajax#method}).\r
92      */\r
93     <div id="cfg-Ext.tree.TreeLoader-url"></div>/**\r
94      * @cfg {String} url Equivalent to {@link #dataUrl}.\r
95      */\r
96     <div id="cfg-Ext.tree.TreeLoader-preloadChildren"></div>/**\r
97      * @cfg {Boolean} preloadChildren If set to true, the loader recursively loads "children" attributes when doing the first load on nodes.\r
98      */\r
99     <div id="cfg-Ext.tree.TreeLoader-baseParams"></div>/**\r
100     * @cfg {Object} baseParams (optional) An object containing properties which\r
101     * specify HTTP parameters to be passed to each request for child nodes.\r
102     */\r
103     <div id="cfg-Ext.tree.TreeLoader-baseAttrs"></div>/**\r
104     * @cfg {Object} baseAttrs (optional) An object containing attributes to be added to all nodes\r
105     * created by this loader. If the attributes sent by the server have an attribute in this object,\r
106     * they take priority.\r
107     */\r
108     <div id="cfg-Ext.tree.TreeLoader-uiProviders"></div>/**\r
109     * @cfg {Object} uiProviders (optional) An object containing properties which\r
110     * specify custom {@link Ext.tree.TreeNodeUI} implementations. If the optional\r
111     * <i>uiProvider</i> attribute of a returned child node is a string rather\r
112     * than a reference to a TreeNodeUI implementation, then that string value\r
113     * is used as a property name in the uiProviders object.\r
114     */\r
115     uiProviders : {},\r
116 \r
117     <div id="cfg-Ext.tree.TreeLoader-clearOnLoad"></div>/**\r
118     * @cfg {Boolean} clearOnLoad (optional) Default to true. Remove previously existing\r
119     * child nodes before loading.\r
120     */\r
121     clearOnLoad : true,\r
122 \r
123     <div id="cfg-Ext.tree.TreeLoader-paramOrder"></div>/**\r
124      * @cfg {Array/String} paramOrder Defaults to <tt>undefined</tt>. Only used when using directFn.\r
125      * A list of params to be executed\r
126      * server side.  Specify the params in the order in which they must be executed on the server-side\r
127      * as either (1) an Array of String values, or (2) a String of params delimited by either whitespace,\r
128      * comma, or pipe. For example,\r
129      * any of the following would be acceptable:<pre><code>\r
130 paramOrder: ['param1','param2','param3']\r
131 paramOrder: 'param1 param2 param3'\r
132 paramOrder: 'param1,param2,param3'\r
133 paramOrder: 'param1|param2|param'\r
134      </code></pre>\r
135      */\r
136     paramOrder: undefined,\r
137 \r
138     <div id="cfg-Ext.tree.TreeLoader-paramsAsHash"></div>/**\r
139      * @cfg {Boolean} paramsAsHash Only used when using directFn.\r
140      * Send parameters as a collection of named arguments (defaults to <tt>false</tt>). Providing a\r
141      * <tt>{@link #paramOrder}</tt> nullifies this configuration.\r
142      */\r
143     paramsAsHash: false,\r
144     \r
145     <div id="cfg-Ext.tree.TreeLoader-nodeParameter"></div>/**\r
146      * @cfg {String} nodeParameter The name of the parameter sent to the server which contains\r
147      * the identifier of the node. Defaults to <tt>'node'</tt>.\r
148      */\r
149     nodeParameter: 'node',\r
150 \r
151     <div id="cfg-Ext.tree.TreeLoader-directFn"></div>/**\r
152      * @cfg {Function} directFn\r
153      * Function to call when executing a request.\r
154      */\r
155     directFn : undefined,\r
156 \r
157     <div id="method-Ext.tree.TreeLoader-load"></div>/**\r
158      * Load an {@link Ext.tree.TreeNode} from the URL specified in the constructor.\r
159      * This is called automatically when a node is expanded, but may be used to reload\r
160      * a node (or append new children if the {@link #clearOnLoad} option is false.)\r
161      * @param {Ext.tree.TreeNode} node\r
162      * @param {Function} callback Function to call after the node has been loaded. The \r
163      * function is passed the TreeNode which was requested to be loaded.\r
164      * @param (Object) scope The cope (<code>this</code> reference) in which the callback is executed.\r
165      * defaults to the loaded TreeNode.\r
166      */\r
167     load : function(node, callback, scope){\r
168         if(this.clearOnLoad){\r
169             while(node.firstChild){\r
170                 node.removeChild(node.firstChild);\r
171             }\r
172         }\r
173         if(this.doPreload(node)){ // preloaded json children\r
174             this.runCallback(callback, scope || node, [node]);\r
175         }else if(this.directFn || this.dataUrl || this.url){\r
176             this.requestData(node, callback, scope || node);\r
177         }\r
178     },\r
179 \r
180     doPreload : function(node){\r
181         if(node.attributes.children){\r
182             if(node.childNodes.length < 1){ // preloaded?\r
183                 var cs = node.attributes.children;\r
184                 node.beginUpdate();\r
185                 for(var i = 0, len = cs.length; i < len; i++){\r
186                     var cn = node.appendChild(this.createNode(cs[i]));\r
187                     if(this.preloadChildren){\r
188                         this.doPreload(cn);\r
189                     }\r
190                 }\r
191                 node.endUpdate();\r
192             }\r
193             return true;\r
194         }\r
195         return false;\r
196     },\r
197 \r
198     getParams: function(node){\r
199         var buf = [], bp = this.baseParams;\r
200         if(this.directFn){\r
201             buf.push(node.id);\r
202             if(bp){\r
203                 if(this.paramOrder){\r
204                     for(var i = 0, len = this.paramOrder.length; i < len; i++){\r
205                         buf.push(bp[this.paramOrder[i]]);\r
206                     }\r
207                 }else if(this.paramsAsHash){\r
208                     buf.push(bp);\r
209                 }\r
210             }\r
211             return buf;\r
212         }else{\r
213             var o = Ext.apply({}, bp);\r
214             o[this.nodeParameter] = node.id;\r
215             return o;\r
216         }\r
217     },\r
218 \r
219     requestData : function(node, callback, scope){\r
220         if(this.fireEvent("beforeload", this, node, callback) !== false){\r
221             if(this.directFn){\r
222                 var args = this.getParams(node);\r
223                 args.push(this.processDirectResponse.createDelegate(this, [{callback: callback, node: node, scope: scope}], true));\r
224                 this.directFn.apply(window, args);\r
225             }else{\r
226                 this.transId = Ext.Ajax.request({\r
227                     method:this.requestMethod,\r
228                     url: this.dataUrl||this.url,\r
229                     success: this.handleResponse,\r
230                     failure: this.handleFailure,\r
231                     scope: this,\r
232                     argument: {callback: callback, node: node, scope: scope},\r
233                     params: this.getParams(node)\r
234                 });\r
235             }\r
236         }else{\r
237             // if the load is cancelled, make sure we notify\r
238             // the node that we are done\r
239             this.runCallback(callback, scope || node, []);\r
240         }\r
241     },\r
242 \r
243     processDirectResponse: function(result, response, args){\r
244         if(response.status){\r
245             this.handleResponse({\r
246                 responseData: Ext.isArray(result) ? result : null,\r
247                 responseText: result,\r
248                 argument: args\r
249             });\r
250         }else{\r
251             this.handleFailure({\r
252                 argument: args\r
253             });\r
254         }\r
255     },\r
256 \r
257     // private\r
258     runCallback: function(cb, scope, args){\r
259         if(Ext.isFunction(cb)){\r
260             cb.apply(scope, args);\r
261         }\r
262     },\r
263 \r
264     isLoading : function(){\r
265         return !!this.transId;\r
266     },\r
267 \r
268     abort : function(){\r
269         if(this.isLoading()){\r
270             Ext.Ajax.abort(this.transId);\r
271         }\r
272     },\r
273 \r
274     <div id="method-Ext.tree.TreeLoader-createNode"></div>/**\r
275     * <p>Override this function for custom TreeNode node implementation, or to\r
276     * modify the attributes at creation time.</p>\r
277     * Example:<pre><code>\r
278 new Ext.tree.TreePanel({\r
279     ...\r
280     loader: new Ext.tree.TreeLoader({\r
281         url: 'dataUrl',\r
282         createNode: function(attr) {\r
283 //          Allow consolidation consignments to have\r
284 //          consignments dropped into them.\r
285             if (attr.isConsolidation) {\r
286                 attr.iconCls = 'x-consol',\r
287                 attr.allowDrop = true;\r
288             }\r
289             return Ext.tree.TreeLoader.prototype.createNode.call(this, attr);\r
290         }\r
291     }),\r
292     ...\r
293 });\r
294 </code></pre>\r
295     * @param attr {Object} The attributes from which to create the new node.\r
296     */\r
297     createNode : function(attr){\r
298         // apply baseAttrs, nice idea Corey!\r
299         if(this.baseAttrs){\r
300             Ext.applyIf(attr, this.baseAttrs);\r
301         }\r
302         if(this.applyLoader !== false && !attr.loader){\r
303             attr.loader = this;\r
304         }\r
305         if(Ext.isString(attr.uiProvider)){\r
306            attr.uiProvider = this.uiProviders[attr.uiProvider] || eval(attr.uiProvider);\r
307         }\r
308         if(attr.nodeType){\r
309             return new Ext.tree.TreePanel.nodeTypes[attr.nodeType](attr);\r
310         }else{\r
311             return attr.leaf ?\r
312                         new Ext.tree.TreeNode(attr) :\r
313                         new Ext.tree.AsyncTreeNode(attr);\r
314         }\r
315     },\r
316 \r
317     processResponse : function(response, node, callback, scope){\r
318         var json = response.responseText;\r
319         try {\r
320             var o = response.responseData || Ext.decode(json);\r
321             node.beginUpdate();\r
322             for(var i = 0, len = o.length; i < len; i++){\r
323                 var n = this.createNode(o[i]);\r
324                 if(n){\r
325                     node.appendChild(n);\r
326                 }\r
327             }\r
328             node.endUpdate();\r
329             this.runCallback(callback, scope || node, [node]);\r
330         }catch(e){\r
331             this.handleFailure(response);\r
332         }\r
333     },\r
334 \r
335     handleResponse : function(response){\r
336         this.transId = false;\r
337         var a = response.argument;\r
338         this.processResponse(response, a.node, a.callback, a.scope);\r
339         this.fireEvent("load", this, a.node, response);\r
340     },\r
341 \r
342     handleFailure : function(response){\r
343         this.transId = false;\r
344         var a = response.argument;\r
345         this.fireEvent("loadexception", this, a.node, response);\r
346         this.runCallback(a.callback, a.scope || a.node, [a.node]);\r
347     },\r
348     \r
349     destroy : function(){\r
350         this.purgeListeners();\r
351     }\r
352 });</pre>    \r
353 </body>\r
354 </html>