Upgrade to ExtJS 4.0.1 - Released 05/18/2011
[extjs.git] / docs / source / ComponentLoader.html
1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5   <title>The source code</title>
6   <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../prettify/prettify.js"></script>
8   <style type="text/css">
9     .highlight { display: block; background-color: #ddd; }
10   </style>
11   <script type="text/javascript">
12     function highlight() {
13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
14     }
15   </script>
16 </head>
17 <body onload="prettyPrint(); highlight();">
18   <pre class="prettyprint lang-js"><span id='Ext-ComponentLoader'>/**
19 </span> * @class Ext.ComponentLoader
20  * @extends Ext.ElementLoader
21  * 
22  * This class is used to load content via Ajax into a {@link Ext.Component}. In general 
23  * this class will not be instanced directly, rather a loader configuration will be passed to the
24  * constructor of the {@link Ext.Component}.
25  * 
26  * ## HTML Renderer
27  * By default, the content loaded will be processed as raw html. The response text
28  * from the request is taken and added to the component. This can be used in
29  * conjunction with the {@link #scripts} option to execute any inline scripts in
30  * the resulting content. Using this renderer has the same effect as passing the
31  * {@link Ext.Component#html} configuration option.
32  * 
33  * ## Data Renderer
34  * This renderer allows content to be added by using JSON data and a {@link Ext.XTemplate}.
35  * The content received from the response is passed to the {@link Ext.Component#update} method.
36  * This content is run through the attached {@link Ext.Component#tpl} and the data is added to
37  * the Component. Using this renderer has the same effect as using the {@link Ext.Component#data}
38  * configuration in conjunction with a {@link Ext.Component#tpl}.
39  * 
40  * ## Component Renderer
41  * This renderer can only be used with a {@link Ext.Container} and subclasses. It allows for
42  * Components to be loaded remotely into a Container. The response is expected to be a single/series of
43  * {@link Ext.Component} configuration objects. When the response is received, the data is decoded
44  * and then passed to {@link Ext.Container#add}. Using this renderer has the same effect as specifying
45  * the {@link Ext.Container#items} configuration on a Container. 
46  * 
47  * ## Custom Renderer
48  * A custom function can be passed to handle any other special case, see the {@link #renderer} option.
49  * 
50  * ## Example Usage
51  *     new Ext.Component({
52  *         tpl: '{firstName} - {lastName}',
53  *         loader: {
54  *             url: 'myPage.php',
55  *             renderer: 'data',
56  *             params: {
57  *                 userId: 1
58  *             }
59  *         }
60  *     });
61  */
62 Ext.define('Ext.ComponentLoader', {
63
64     /* Begin Definitions */
65     
66     extend: 'Ext.ElementLoader',
67
68     statics: {
69         Renderer: {
70             Data: function(loader, response, active){
71                 var success = true;
72                 try {
73                     loader.getTarget().update(Ext.decode(response.responseText));
74                 } catch (e) {
75                     success = false;
76                 }
77                 return success;
78             },
79
80             Component: function(loader, response, active){
81                 var success = true,
82                     target = loader.getTarget(),
83                     items = [];
84
85                 //&lt;debug&gt;
86                 if (!target.isContainer) {
87                     Ext.Error.raise({
88                         target: target,
89                         msg: 'Components can only be loaded into a container'
90                     });
91                 }
92                 //&lt;/debug&gt;
93
94                 try {
95                     items = Ext.decode(response.responseText);
96                 } catch (e) {
97                     success = false;
98                 }
99
100                 if (success) {
101                     if (active.removeAll) {
102                         target.removeAll();
103                     }
104                     target.add(items);
105                 }
106                 return success;
107             }
108         }
109     },
110
111     /* End Definitions */
112
113 <span id='Ext-ComponentLoader-cfg-target'>    /**
114 </span>     * @cfg {Ext.Component/String} target The target {@link Ext.Component} for the loader. Defaults to &lt;tt&gt;null&lt;/tt&gt;.
115      * If a string is passed it will be looked up via the id.
116      */
117     target: null,
118
119 <span id='Ext-ComponentLoader-cfg-loadMask'>    /**
120 </span>     * @cfg {Mixed} loadMask True or a {@link Ext.LoadMask} configuration to enable masking during loading. Defaults to &lt;tt&gt;false&lt;/tt&gt;.
121      */
122     loadMask: false,
123     
124 <span id='Ext-ComponentLoader-cfg-scripts'>    /**
125 </span>     * @cfg {Boolean} scripts True to parse any inline script tags in the response. This only used when using the html
126      * {@link #renderer}.
127      */
128
129 <span id='Ext-ComponentLoader-cfg-renderer'>    /**
130 </span>     * @cfg {String/Function} renderer
131
132 The type of content that is to be loaded into, which can be one of 3 types:
133
134 + **html** : Loads raw html content, see {@link Ext.Component#html}
135 + **data** : Loads raw html content, see {@link Ext.Component#data}
136 + **component** : Loads child {Ext.Component} instances. This option is only valid when used with a Container.
137
138 Defaults to `html`.
139
140 Alternatively, you can pass a function which is called with the following parameters.
141
142 + loader - Loader instance
143 + response - The server response
144 + active - The active request
145
146 The function must return false is loading is not successful. Below is a sample of using a custom renderer:
147
148     new Ext.Component({
149         loader: {
150             url: 'myPage.php',
151             renderer: function(loader, response, active) {
152                 var text = response.responseText;
153                 loader.getTarget().update('The response is ' + text);
154                 return true;
155             }
156         }
157     });
158      * @markdown
159      */
160     renderer: 'html',
161
162 <span id='Ext-ComponentLoader-method-setTarget'>    /**
163 </span>     * Set a {Ext.Component} as the target of this loader. Note that if the target is changed,
164      * any active requests will be aborted.
165      * @param {String/Ext.Component} target The component to be the target of this loader. If a string is passed
166      * it will be looked up via its id.
167      */
168     setTarget: function(target){
169         var me = this;
170         
171         if (Ext.isString(target)) {
172             target = Ext.getCmp(target);
173         }
174
175         if (me.target &amp;&amp; me.target != target) {
176             me.abort();
177         }
178         me.target = target;
179     },
180     
181     // inherit docs
182     removeMask: function(){
183         this.target.setLoading(false);
184     },
185     
186 <span id='Ext-ComponentLoader-method-addMask'>    /**
187 </span>     * Add the mask on the target
188      * @private
189      * @param {Mixed} mask The mask configuration
190      */
191     addMask: function(mask){
192         this.target.setLoading(mask);
193     },
194
195 <span id='Ext-ComponentLoader-method-setOptions'>    /**
196 </span>     * Get the target of this loader.
197      * @return {Ext.Component} target The target, null if none exists.
198      */
199     
200     setOptions: function(active, options){
201         active.removeAll = Ext.isDefined(options.removeAll) ? options.removeAll : this.removeAll;
202     },
203
204 <span id='Ext-ComponentLoader-method-getRenderer'>    /**
205 </span>     * Gets the renderer to use
206      * @private
207      * @param {String/Function} renderer The renderer to use
208      * @return {Function} A rendering function to use.
209      */
210     getRenderer: function(renderer){
211         if (Ext.isFunction(renderer)) {
212             return renderer;
213         }
214
215         var renderers = this.statics().Renderer;
216         switch (renderer) {
217             case 'component':
218                 return renderers.Component;
219             case 'data':
220                 return renderers.Data;
221             default:
222                 return Ext.ElementLoader.Renderer.Html;
223         }
224     }
225 });
226 </pre>
227 </body>
228 </html>