Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Controller.html
index 045a0d2..acc7a7e 100644 (file)
@@ -1,30 +1,46 @@
-<!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-app.Controller-method-constructor'><span id='Ext-app.Controller'>/**
-</span></span> * @class Ext.app.Controller
- * @constructor
- * 
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <title>The source code</title>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <style type="text/css">
+    .highlight { display: block; background-color: #ddd; }
+  </style>
+  <script type="text/javascript">
+    function highlight() {
+      document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
+    }
+  </script>
+</head>
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js"><span id='Ext-app-Controller'>/**
+</span> * @class Ext.app.Controller
+ *
  * Controllers are the glue that binds an application together. All they really do is listen for events (usually from
  * views) and take some action. Here's how we might create a Controller to manage Users:
- * 
+ *
  *     Ext.define('MyApp.controller.Users', {
  *         extend: 'Ext.app.Controller',
- * 
+ *
  *         init: function() {
  *             console.log('Initialized Users! This happens before the Application launch function is called');
  *         }
  *     });
- * 
- * The init function is a special method that is called when your application boots. It is called before the 
+ *
+ * The init function is a special method that is called when your application boots. It is called before the
  * {@link Ext.app.Application Application}'s launch function is executed so gives a hook point to run any code before
  * your Viewport is created.
- * 
- * The init function is a great place to set up how your controller interacts with the view, and is usually used in 
- * conjunction with another Controller function - {@link Ext.app.Controller#control control}. The control function 
+ *
+ * The init function is a great place to set up how your controller interacts with the view, and is usually used in
+ * conjunction with another Controller function - {@link Ext.app.Controller#control control}. The control function
  * makes it easy to listen to events on your view classes and take some action with a handler function. Let's update
  * our Users controller to tell us when the panel is rendered:
- * 
+ *
  *     Ext.define('MyApp.controller.Users', {
  *         extend: 'Ext.app.Controller',
- * 
+ *
  *         init: function() {
  *             this.control({
  *                 'viewport &gt; panel': {
  *                 }
  *             });
  *         },
- * 
+ *
  *         onPanelRendered: function() {
  *             console.log('The panel was rendered');
  *         }
  *     });
- * 
+ *
  * We've updated the init function to use this.control to set up listeners on views in our application. The control
  * function uses the new ComponentQuery engine to quickly and easily get references to components on the page. If you
- * are not familiar with ComponentQuery yet, be sure to check out THIS GUIDE for a full explanation. In brief though,
+ * are not familiar with ComponentQuery yet, be sure to check out the {@link Ext.ComponentQuery documentation}. In brief though,
  * it allows us to pass a CSS-like selector that will find every matching component on the page.
- * 
+ *
  * In our init function above we supplied 'viewport &gt; panel', which translates to &quot;find me every Panel that is a direct
- * child of a Viewport&quot;. We then supplied an object that maps event names (just 'render' in this case) to handler 
- * functions. The overall effect is that whenever any component that matches our selector fires a 'render' event, our 
+ * child of a Viewport&quot;. We then supplied an object that maps event names (just 'render' in this case) to handler
+ * functions. The overall effect is that whenever any component that matches our selector fires a 'render' event, our
  * onPanelRendered function is called.
- * 
+ *
  * &lt;u&gt;Using refs&lt;/u&gt;
- * 
+ *
  * One of the most useful parts of Controllers is the new ref system. These use the new {@link Ext.ComponentQuery} to
  * make it really easy to get references to Views on your page. Let's look at an example of this now:
- * 
- * Ext.define('MyApp.controller.Users', {
-     extend: 'Ext.app.Controller',
-
-     refs: [
-         {
-             ref: 'list',
-             selector: 'grid'
-         }
-     ],
-
-     init: function() {
-         this.control({
-             'button': {
-                 click: this.refreshGrid
-             }
-         });
-     },
-
-     refreshGrid: function() {
-         this.getList().store.load();
-     }
- });
- * 
- * This example assumes the existence of a {@link Ext.grid.Panel Grid} on the page, which contains a single button to 
- * refresh the Grid when clicked. In our refs array, we set up a reference to the grid. There are two parts to this - 
+ *
+ *     Ext.define('MyApp.controller.Users', {
*         extend: 'Ext.app.Controller',
+ *
*         refs: [
*             {
*                 ref: 'list',
*                 selector: 'grid'
*             }
*         ],
+ *
*         init: function() {
*             this.control({
*                 'button': {
*                     click: this.refreshGrid
*                 }
*             });
*         },
+ *
*         refreshGrid: function() {
*             this.getList().store.load();
*         }
*     });
+ *
+ * This example assumes the existence of a {@link Ext.grid.Panel Grid} on the page, which contains a single button to
+ * refresh the Grid when clicked. In our refs array, we set up a reference to the grid. There are two parts to this -
  * the 'selector', which is a {@link Ext.ComponentQuery ComponentQuery} selector which finds any grid on the page and
  * assigns it to the reference 'list'.
- * 
+ *
  * By giving the reference a name, we get a number of things for free. The first is the getList function that we use in
- * the refreshGrid method above. This is generated automatically by the Controller based on the name of our ref, which 
+ * the refreshGrid method above. This is generated automatically by the Controller based on the name of our ref, which
  * was capitalized and prepended with get to go from 'list' to 'getList'.
- * 
+ *
  * The way this works is that the first time getList is called by your code, the ComponentQuery selector is run and the
- * first component that matches the selector ('grid' in this case) will be returned. All future calls to getList will 
+ * first component that matches the selector ('grid' in this case) will be returned. All future calls to getList will
  * use a cached reference to that grid. Usually it is advised to use a specific ComponentQuery selector that will only
  * match a single View in your application (in the case above our selector will match any grid on the page).
- * 
+ *
  * Bringing it all together, our init function is called when the application boots, at which time we call this.control
- * to listen to any click on a {@link Ext.button.Button button} and call our refreshGrid function (again, this will 
+ * to listen to any click on a {@link Ext.button.Button button} and call our refreshGrid function (again, this will
  * match any button on the page so we advise a more specific selector than just 'button', but have left it this way for
  * simplicity). When the button is clicked we use out getList function to refresh the grid.
- * 
- * You can create any number of refs and control any number of components this way, simply adding more functions to 
- * your Controller as you go. For an example of real-world usage of Controllers see the Feed Viewer example in the 
+ *
+ * You can create any number of refs and control any number of components this way, simply adding more functions to
+ * your Controller as you go. For an example of real-world usage of Controllers see the Feed Viewer example in the
  * examples/app/feed-viewer folder in the SDK download.
- * 
+ *
  * &lt;u&gt;Generated getter methods&lt;/u&gt;
- * 
- * Refs aren't the only thing that generate convenient getter methods. Controllers often have to deal with Models and 
+ *
+ * Refs aren't the only thing that generate convenient getter methods. Controllers often have to deal with Models and
  * Stores so the framework offers a couple of easy ways to get access to those too. Let's look at another example:
- * 
- * Ext.define('MyApp.controller.Users', {
-     extend: 'Ext.app.Controller',
-
-     models: ['User'],
-     stores: ['AllUsers', 'AdminUsers'],
-
-     init: function() {
-         var User = this.getUserModel(),
-             allUsers = this.getAllUsersStore();
-
-         var ed = new User({name: 'Ed'});
-         allUsers.add(ed);
-     }
- });
- * 
+ *
+ *     Ext.define('MyApp.controller.Users', {
*         extend: 'Ext.app.Controller',
+ *
*         models: ['User'],
*         stores: ['AllUsers', 'AdminUsers'],
+ *
*         init: function() {
*             var User = this.getUserModel(),
*                 allUsers = this.getAllUsersStore();
+ *
*             var ed = new User({name: 'Ed'});
*             allUsers.add(ed);
*         }
*     });
+ *
  * By specifying Models and Stores that the Controller cares about, it again dynamically loads them from the appropriate
- * locations (app/model/User.js, app/store/AllUsers.js and app/store/AdminUsers.js in this case) and creates getter 
+ * locations (app/model/User.js, app/store/AllUsers.js and app/store/AdminUsers.js in this case) and creates getter
  * functions for them all. The example above will create a new User model instance and add it to the AllUsers Store.
- * Of course, you could do anything in this function but in this case we just did something simple to demonstrate the 
+ * Of course, you could do anything in this function but in this case we just did something simple to demonstrate the
  * functionality.
- * 
+ *
  * &lt;u&gt;Further Reading&lt;/u&gt;
- * 
- * For more information about writing Ext JS 4 applications, please see the &lt;a href=&quot;../guide/application_architecture&quot;&gt;
- * application architecture guide&lt;/a&gt;. Also see the {@link Ext.app.Application} documentation.
- * 
- * @markdown
+ *
+ * For more information about writing Ext JS 4 applications, please see the
+ * [application architecture guide](#/guide/application_architecture). Also see the {@link Ext.app.Application} documentation.
+ *
  * @docauthor Ed Spencer
- */  
+ */
 Ext.define('Ext.app.Controller', {
-<span id='Ext-app.Controller-cfg-id'>    /**
-</span>     * @cfg {Object} id The id of this controller. You can use this id when dispatching.
-     */
 
     mixins: {
         observable: 'Ext.util.Observable'
     },
 
+<span id='Ext-app-Controller-cfg-id'>    /**
+</span>     * @cfg {String} id The id of this controller. You can use this id when dispatching.
+     */
+    
+<span id='Ext-app-Controller-cfg-models'>    /**
+</span>     * @cfg {String[]} models
+     * Array of models to require from AppName.model namespace. For example:
+     * 
+     *     Ext.define(&quot;MyApp.controller.Foo&quot;, {
+     *         extend: &quot;Ext.app.Controller&quot;,
+     *         models: ['User', 'Vehicle']
+     *     });
+     * 
+     * This is equivalent of:
+     * 
+     *     Ext.define(&quot;MyApp.controller.Foo&quot;, {
+     *         extend: &quot;Ext.app.Controller&quot;,
+     *         requires: ['MyApp.model.User', 'MyApp.model.Vehicle']
+     *     });
+     * 
+     */
+
+<span id='Ext-app-Controller-cfg-views'>    /**
+</span>     * @cfg {String[]} views
+     * Array of views to require from AppName.view namespace. For example:
+     * 
+     *     Ext.define(&quot;MyApp.controller.Foo&quot;, {
+     *         extend: &quot;Ext.app.Controller&quot;,
+     *         views: ['List', 'Detail']
+     *     });
+     * 
+     * This is equivalent of:
+     * 
+     *     Ext.define(&quot;MyApp.controller.Foo&quot;, {
+     *         extend: &quot;Ext.app.Controller&quot;,
+     *         requires: ['MyApp.view.List', 'MyApp.view.Detail']
+     *     });
+     * 
+     */
+
+<span id='Ext-app-Controller-cfg-stores'>    /**
+</span>     * @cfg {String[]} stores
+     * Array of stores to require from AppName.store namespace. For example:
+     * 
+     *     Ext.define(&quot;MyApp.controller.Foo&quot;, {
+     *         extend: &quot;Ext.app.Controller&quot;,
+     *         stores: ['Users', 'Vehicles']
+     *     });
+     * 
+     * This is equivalent of:
+     * 
+     *     Ext.define(&quot;MyApp.controller.Foo&quot;, {
+     *         extend: &quot;Ext.app.Controller&quot;,
+     *         requires: ['MyApp.store.Users', 'MyApp.store.Vehicles']
+     *     });
+     * 
+     */
+
     onClassExtended: function(cls, data) {
         var className = Ext.getClassName(cls),
             match = className.match(/^(.*)\.controller\./);
@@ -181,6 +251,10 @@ Ext.define('Ext.app.Controller', {
         }
     },
 
+<span id='Ext-app-Controller-method-constructor'>    /**
+</span>     * Creates new Controller.
+     * @param {Object} config (optional) Config object.
+     */
     constructor: function(config) {
         this.mixins.observable.constructor.call(this, config);
 
@@ -195,9 +269,23 @@ Ext.define('Ext.app.Controller', {
         }
     },
 
-    // Template method
+<span id='Ext-app-Controller-method-init'>    /**
+</span>     * A template method that is called when your application boots. It is called before the
+     * {@link Ext.app.Application Application}'s launch function is executed so gives a hook point to run any code before
+     * your Viewport is created.
+     * 
+     * @param {Ext.app.Application} application
+     * @template
+     */
     init: function(application) {},
-    // Template method
+
+<span id='Ext-app-Controller-method-onLaunch'>    /**
+</span>     * A template method like {@link #init}, but called after the viewport is created.
+     * This is called after the {@link Ext.app.Application#launch launch} method of Application is executed.
+     * 
+     * @param {Ext.app.Application} application
+     * @template
+     */
     onLaunch: function(application) {},
 
     createGetters: function(type, refs) {
@@ -263,24 +351,80 @@ Ext.define('Ext.app.Controller', {
         return cached;
     },
 
+<span id='Ext-app-Controller-method-control'>    /**
+</span>     * Adds listeners to components selected via {@link Ext.ComponentQuery}. Accepts an
+     * object containing component paths mapped to a hash of listener functions.
+     *
+     * In the following example the `updateUser` function is mapped to to the `click`
+     * event on a button component, which is a child of the `useredit` component.
+     *
+     *     Ext.define('AM.controller.Users', {
+     *         init: function() {
+     *             this.control({
+     *                 'useredit button[action=save]': {
+     *                     click: this.updateUser
+     *                 }
+     *             });
+     *         },
+     *
+     *         updateUser: function(button) {
+     *             console.log('clicked the Save button');
+     *         }
+     *     });
+     *
+     * See {@link Ext.ComponentQuery} for more information on component selectors.
+     *
+     * @param {String/Object} selectors If a String, the second argument is used as the
+     * listeners, otherwise an object of selectors -&gt; listeners is assumed
+     * @param {Object} listeners
+     */
     control: function(selectors, listeners) {
         this.application.control(selectors, listeners, this);
     },
 
+<span id='Ext-app-Controller-method-getController'>    /**
+</span>     * Returns instance of a {@link Ext.app.Controller controller} with the given name.
+     * When controller doesn't exist yet, it's created.
+     * @param {String} name
+     * @return {Ext.app.Controller} a controller instance.
+     */
     getController: function(name) {
         return this.application.getController(name);
     },
 
+<span id='Ext-app-Controller-method-getStore'>    /**
+</span>     * Returns instance of a {@link Ext.data.Store Store} with the given name.
+     * When store doesn't exist yet, it's created.
+     * @param {String} name
+     * @return {Ext.data.Store} a store instance.
+     */
     getStore: function(name) {
         return this.application.getStore(name);
     },
 
+<span id='Ext-app-Controller-method-getModel'>    /**
+</span>     * Returns a {@link Ext.data.Model Model} class with the given name.
+     * A shorthand for using {@link Ext.ModelManager#getModel}.
+     * @param {String} name
+     * @return {Ext.data.Model} a model class.
+     */
     getModel: function(model) {
         return this.application.getModel(model);
     },
 
+<span id='Ext-app-Controller-method-getView'>    /**
+</span>     * Returns a View class with the given name.  To create an instance of the view,
+     * you can use it like it's used by Application to create the Viewport:
+     * 
+     *     this.getView('Viewport').create();
+     * 
+     * @param {String} name
+     * @return {Ext.Base} a view class.
+     */
     getView: function(view) {
         return this.application.getView(view);
     }
 });
-</pre></pre></body></html>
\ No newline at end of file
+</pre>
+</body>
+</html>