Upgrade to ExtJS 4.0.2 - Released 06/09/2011
[extjs.git] / docs / source / Controller.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-app-Controller'>/**
19 </span> * @class Ext.app.Controller
20  * 
21  * Controllers are the glue that binds an application together. All they really do is listen for events (usually from
22  * views) and take some action. Here's how we might create a Controller to manage Users:
23  * 
24  *     Ext.define('MyApp.controller.Users', {
25  *         extend: 'Ext.app.Controller',
26  * 
27  *         init: function() {
28  *             console.log('Initialized Users! This happens before the Application launch function is called');
29  *         }
30  *     });
31  * 
32  * The init function is a special method that is called when your application boots. It is called before the 
33  * {@link Ext.app.Application Application}'s launch function is executed so gives a hook point to run any code before
34  * your Viewport is created.
35  * 
36  * The init function is a great place to set up how your controller interacts with the view, and is usually used in 
37  * conjunction with another Controller function - {@link Ext.app.Controller#control control}. The control function 
38  * makes it easy to listen to events on your view classes and take some action with a handler function. Let's update
39  * our Users controller to tell us when the panel is rendered:
40  * 
41  *     Ext.define('MyApp.controller.Users', {
42  *         extend: 'Ext.app.Controller',
43  * 
44  *         init: function() {
45  *             this.control({
46  *                 'viewport &gt; panel': {
47  *                     render: this.onPanelRendered
48  *                 }
49  *             });
50  *         },
51  * 
52  *         onPanelRendered: function() {
53  *             console.log('The panel was rendered');
54  *         }
55  *     });
56  * 
57  * We've updated the init function to use this.control to set up listeners on views in our application. The control
58  * function uses the new ComponentQuery engine to quickly and easily get references to components on the page. If you
59  * are not familiar with ComponentQuery yet, be sure to check out THIS GUIDE for a full explanation. In brief though,
60  * it allows us to pass a CSS-like selector that will find every matching component on the page.
61  * 
62  * In our init function above we supplied 'viewport &gt; panel', which translates to &quot;find me every Panel that is a direct
63  * child of a Viewport&quot;. We then supplied an object that maps event names (just 'render' in this case) to handler 
64  * functions. The overall effect is that whenever any component that matches our selector fires a 'render' event, our 
65  * onPanelRendered function is called.
66  * 
67  * &lt;u&gt;Using refs&lt;/u&gt;
68  * 
69  * One of the most useful parts of Controllers is the new ref system. These use the new {@link Ext.ComponentQuery} to
70  * make it really easy to get references to Views on your page. Let's look at an example of this now:
71  * 
72  *     Ext.define('MyApp.controller.Users', {
73  *         extend: 'Ext.app.Controller',
74  *     
75  *         refs: [
76  *             {
77  *                 ref: 'list',
78  *                 selector: 'grid'
79  *             }
80  *         ],
81  *     
82  *         init: function() {
83  *             this.control({
84  *                 'button': {
85  *                     click: this.refreshGrid
86  *                 }
87  *             });
88  *         },
89  *     
90  *         refreshGrid: function() {
91  *             this.getList().store.load();
92  *         }
93  *     });
94  * 
95  * This example assumes the existence of a {@link Ext.grid.Panel Grid} on the page, which contains a single button to 
96  * refresh the Grid when clicked. In our refs array, we set up a reference to the grid. There are two parts to this - 
97  * the 'selector', which is a {@link Ext.ComponentQuery ComponentQuery} selector which finds any grid on the page and
98  * assigns it to the reference 'list'.
99  * 
100  * By giving the reference a name, we get a number of things for free. The first is the getList function that we use in
101  * the refreshGrid method above. This is generated automatically by the Controller based on the name of our ref, which 
102  * was capitalized and prepended with get to go from 'list' to 'getList'.
103  * 
104  * The way this works is that the first time getList is called by your code, the ComponentQuery selector is run and the
105  * first component that matches the selector ('grid' in this case) will be returned. All future calls to getList will 
106  * use a cached reference to that grid. Usually it is advised to use a specific ComponentQuery selector that will only
107  * match a single View in your application (in the case above our selector will match any grid on the page).
108  * 
109  * Bringing it all together, our init function is called when the application boots, at which time we call this.control
110  * to listen to any click on a {@link Ext.button.Button button} and call our refreshGrid function (again, this will 
111  * match any button on the page so we advise a more specific selector than just 'button', but have left it this way for
112  * simplicity). When the button is clicked we use out getList function to refresh the grid.
113  * 
114  * You can create any number of refs and control any number of components this way, simply adding more functions to 
115  * your Controller as you go. For an example of real-world usage of Controllers see the Feed Viewer example in the 
116  * examples/app/feed-viewer folder in the SDK download.
117  * 
118  * &lt;u&gt;Generated getter methods&lt;/u&gt;
119  * 
120  * Refs aren't the only thing that generate convenient getter methods. Controllers often have to deal with Models and 
121  * Stores so the framework offers a couple of easy ways to get access to those too. Let's look at another example:
122  * 
123  *     Ext.define('MyApp.controller.Users', {
124  *         extend: 'Ext.app.Controller',
125  *     
126  *         models: ['User'],
127  *         stores: ['AllUsers', 'AdminUsers'],
128  *     
129  *         init: function() {
130  *             var User = this.getUserModel(),
131  *                 allUsers = this.getAllUsersStore();
132  *     
133  *             var ed = new User({name: 'Ed'});
134  *             allUsers.add(ed);
135  *         }
136  *     });
137  * 
138  * By specifying Models and Stores that the Controller cares about, it again dynamically loads them from the appropriate
139  * locations (app/model/User.js, app/store/AllUsers.js and app/store/AdminUsers.js in this case) and creates getter 
140  * functions for them all. The example above will create a new User model instance and add it to the AllUsers Store.
141  * Of course, you could do anything in this function but in this case we just did something simple to demonstrate the 
142  * functionality.
143  * 
144  * &lt;u&gt;Further Reading&lt;/u&gt;
145  * 
146  * For more information about writing Ext JS 4 applications, please see the
147  * [application architecture guide](#/guide/application_architecture). Also see the {@link Ext.app.Application} documentation.
148  * 
149  * @docauthor Ed Spencer
150  */  
151 Ext.define('Ext.app.Controller', {
152
153     mixins: {
154         observable: 'Ext.util.Observable'
155     },
156
157 <span id='Ext-app-Controller-cfg-id'>    /**
158 </span>     * @cfg {String} id The id of this controller. You can use this id when dispatching.
159      */
160
161     onClassExtended: function(cls, data) {
162         var className = Ext.getClassName(cls),
163             match = className.match(/^(.*)\.controller\./);
164
165         if (match !== null) {
166             var namespace = Ext.Loader.getPrefix(className) || match[1],
167                 onBeforeClassCreated = data.onBeforeClassCreated,
168                 requires = [],
169                 modules = ['model', 'view', 'store'],
170                 prefix;
171
172             data.onBeforeClassCreated = function(cls, data) {
173                 var i, ln, module,
174                     items, j, subLn, item;
175
176                 for (i = 0,ln = modules.length; i &lt; ln; i++) {
177                     module = modules[i];
178
179                     items = Ext.Array.from(data[module + 's']);
180
181                     for (j = 0,subLn = items.length; j &lt; subLn; j++) {
182                         item = items[j];
183
184                         prefix = Ext.Loader.getPrefix(item);
185
186                         if (prefix === '' || prefix === item) {
187                             requires.push(namespace + '.' + module + '.' + item);
188                         }
189                         else {
190                             requires.push(item);
191                         }
192                     }
193                 }
194
195                 Ext.require(requires, Ext.Function.pass(onBeforeClassCreated, arguments, this));
196             };
197         }
198     },
199
200 <span id='Ext-app-Controller-method-constructor'>    /**
201 </span>     * Creates new Controller.
202      * @param {Object} config (optional) Config object.
203      */
204     constructor: function(config) {
205         this.mixins.observable.constructor.call(this, config);
206
207         Ext.apply(this, config || {});
208
209         this.createGetters('model', this.models);
210         this.createGetters('store', this.stores);
211         this.createGetters('view', this.views);
212
213         if (this.refs) {
214             this.ref(this.refs);
215         }
216     },
217
218     // Template method
219     init: function(application) {},
220     // Template method
221     onLaunch: function(application) {},
222
223     createGetters: function(type, refs) {
224         type = Ext.String.capitalize(type);
225         Ext.Array.each(refs, function(ref) {
226             var fn = 'get',
227                 parts = ref.split('.');
228
229             // Handle namespaced class names. E.g. feed.Add becomes getFeedAddView etc.
230             Ext.Array.each(parts, function(part) {
231                 fn += Ext.String.capitalize(part);
232             });
233             fn += type;
234
235             if (!this[fn]) {
236                 this[fn] = Ext.Function.pass(this['get' + type], [ref], this);
237             }
238             // Execute it right away
239             this[fn](ref);
240         },
241         this);
242     },
243
244     ref: function(refs) {
245         var me = this;
246         refs = Ext.Array.from(refs);
247         Ext.Array.each(refs, function(info) {
248             var ref = info.ref,
249                 fn = 'get' + Ext.String.capitalize(ref);
250             if (!me[fn]) {
251                 me[fn] = Ext.Function.pass(me.getRef, [ref, info], me);
252             }
253         });
254     },
255
256     getRef: function(ref, info, config) {
257         this.refCache = this.refCache || {};
258         info = info || {};
259         config = config || {};
260
261         Ext.apply(info, config);
262
263         if (info.forceCreate) {
264             return Ext.ComponentManager.create(info, 'component');
265         }
266
267         var me = this,
268             selector = info.selector,
269             cached = me.refCache[ref];
270
271         if (!cached) {
272             me.refCache[ref] = cached = Ext.ComponentQuery.query(info.selector)[0];
273             if (!cached &amp;&amp; info.autoCreate) {
274                 me.refCache[ref] = cached = Ext.ComponentManager.create(info, 'component');
275             }
276             if (cached) {
277                 cached.on('beforedestroy', function() {
278                     me.refCache[ref] = null;
279                 });
280             }
281         }
282
283         return cached;
284     },
285
286 <span id='Ext-app-Controller-method-control'>    /**
287 </span>     * Adds listeners to components selected via {@link Ext.ComponentQuery}. Accepts an 
288      * object containing component paths mapped to a hash of listener functions. 
289      *
290      * In the following example the `updateUser` function is mapped to to the `click` 
291      * event on a button component, which is a child of the `useredit` component.
292      *
293      *     Ext.define('AM.controller.Users', {
294      *         init: function() {
295      *             this.control({
296      *                 'useredit button[action=save]': {
297      *                     click: this.updateUser
298      *                 }
299      *             });
300      *         },
301      *     
302      *         updateUser: function(button) {
303      *             console.log('clicked the Save button');
304      *         }
305      *     });
306      *
307      * See {@link Ext.ComponentQuery} for more information on component selectors.
308      *
309      * @param {String|Object} selectors If a String, the second argument is used as the 
310      * listeners, otherwise an object of selectors -&gt; listeners is assumed
311      * @param {Object} listeners
312      */
313     control: function(selectors, listeners) {
314         this.application.control(selectors, listeners, this);
315     },
316
317 <span id='Ext-app-Controller-method-getController'>    /**
318 </span>     * Returns a reference to a {@link Ext.app.Controller controller} with the given name
319      * @param name {String}
320      */
321     getController: function(name) {
322         return this.application.getController(name);
323     },
324
325 <span id='Ext-app-Controller-method-getStore'>    /**
326 </span>     * Returns a reference to a {@link Ext.data.Store store} with the given name
327      * @param name {String}
328      */
329     getStore: function(name) {
330         return this.application.getStore(name);
331     },
332
333 <span id='Ext-app-Controller-method-getModel'>    /**
334 </span>     * Returns a reference to a {@link Ext.data.Model Model} with the given name
335      * @param name {String}
336      */
337     getModel: function(model) {
338         return this.application.getModel(model);
339     },
340
341 <span id='Ext-app-Controller-method-getView'>    /**
342 </span>     * Returns a reference to a view with the given name
343      * @param name {String}
344      */
345     getView: function(view) {
346         return this.application.getView(view);
347     }
348 });
349 </pre>
350 </body>
351 </html>