docs/api/Ext.app.Controller.html

   1 <!DOCTYPE html><html><head><title>Ext.app.Controller | Ext JS 4.0 Documentation</title><script type="text/javascript" src="../ext-all.js"></script><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../scrollbars.css" type="text/css"><link rel="stylesheet" href="../docs.css" type="text/css"><link id="styleCss" rel="stylesheet" href="../style.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script><link rel="stylesheet" href="../prettify.css" type="text/css"><!-- link(rel: 'stylesheet', href: req.baseURL + '/css/ext4.css', type: 'text/css')--><link rel="shortcut icon" type="image/ico" href="../favicon.ico"><!--[if IE]>
   2 <style type="text/css">.head-band { display: none; }
   3 .header { border: 0; top: 0; left: 0px; background: url(../header.gif) repeat-x; }
   4 .doc-tab .members .member a.more { background-color: #efefef; }
   5 </style><link rel="stylesheet" href="/new/css/ie.css" type="text/css"><![endif]-->
   6 </head><body id="ext-body" class="iScroll"><div id="notice" class="notice">For up to date documentation and features, visit
   7 <a href="http://docs.sencha.com/ext-js/4-0">http://docs.sencha.com/ext-js/4-0</a></div><div class="wrapper"><div class="head-band"></div><div class="header"><h2><a href="../index.html">Sencha Documentation</a></h2></div><div id="search"><form><input type="text" placeholder="Search" id="search-field" autocomplete="off" name="q"></form><div id="search-box"></div></div><div id="treePanel"></div><div id="container"><script type="text/javascript">
   8
   9     req = {
  10         liveURL: '.',
  11         standAloneMode: true,
  12         origDocClass: 'Ext.app.Controller',
  13         docClass: 'Ext.app.Controller',
  14         docReq: 'Ext.app.Controller',
  15         version: '4.0',
  16         baseURL: '.',
  17         baseDocURL: '.',
  18         baseProdURL: '.'
  19     };
  20
  21     clsInfo = {};
  22
  23
  24
  25 </script>
  26
  27 <script type="text/javascript" src="../search.js"></script>
  28 <!--script type="text/javascript" src="/new/javascripts/app/examples.js"></script-->
  29 <script type="text/javascript" src="../class_tree.js"></script>
  30 <script type="text/javascript" src="../class_doc.js"></script>
  31 <script type="text/javascript">
  32     req.source = 'Controller.html#Ext-app.Controller';
  33     clsInfo = {"methods":["Controller"],"cfgs":["id"],"properties":[],"events":[],"subclasses":["Ext.app.Application"]};
  34     Ext.onReady(function() {
  35         Ext.create('Docs.classPanel');
  36     });
  37 </script><div id="top-block" class="top-block"><h1 id="clsTitle" class="cls"><a href="../source/Controller.html#Ext-app.Controller" target="_blank">Ext.app.Controller</a></h1></div><div id="docContent"><div id="doc-overview-content"><div class="lft"><p>Controllers are the glue that binds an application together. All they really do is listen for events (usually from
  38 views) and take some action. Here's how we might create a Controller to manage Users:</p>
  39
  40 <pre class="prettyprint"><code>Ext.define('MyApp.controller.Users', {
  41     extend: 'Ext.app.Controller',
  42
  43     init: function() {
  44         console.log('Initialized Users! This happens before the Application launch function is called');
  45     }
  46 });
  47 </code></pre>
  48
  49 <p>The init function is a special method that is called when your application boots. It is called before the
  50 <a href="Ext.app.Application.html" rel="Ext.app.Application" class="docClass">Application</a>'s launch function is executed so gives a hook point to run any code before
  51 your Viewport is created.</p>
  52
  53 <p>The init function is a great place to set up how your controller interacts with the view, and is usually used in
  54 conjunction with another Controller function - <a href="Ext.app.Controller.html#control" rel="Ext.app.Controller#control" class="docClass">control</a>. The control function
  55 makes it easy to listen to events on your view classes and take some action with a handler function. Let's update
  56 our Users controller to tell us when the panel is rendered:</p>
  57
  58 <pre class="prettyprint"><code>Ext.define('MyApp.controller.Users', {
  59     extend: 'Ext.app.Controller',
  60
  61     init: function() {
  62         this.control({
  63             'viewport &gt; panel': {
  64                 render: this.onPanelRendered
  65             }
  66         });
  67     },
  68
  69     onPanelRendered: function() {
  70         console.log('The panel was rendered');
  71     }
  72 });
  73 </code></pre>
  74
  75 <p>We've updated the init function to use this.control to set up listeners on views in our application. The control
  76 function uses the new ComponentQuery engine to quickly and easily get references to components on the page. If you
  77 are not familiar with ComponentQuery yet, be sure to check out THIS GUIDE for a full explanation. In brief though,
  78 it allows us to pass a CSS-like selector that will find every matching component on the page.</p>
  79
  80 <p>In our init function above we supplied 'viewport > panel', which translates to "find me every Panel that is a direct
  81 child of a Viewport". We then supplied an object that maps event names (just 'render' in this case) to handler
  82 functions. The overall effect is that whenever any component that matches our selector fires a 'render' event, our
  83 onPanelRendered function is called.</p>
  84
  85 <p><u>Using refs</u></p>
  86
  87 <p>One of the most useful parts of Controllers is the new ref system. These use the new <a href="Ext.ComponentQuery.html" rel="Ext.ComponentQuery" class="docClass">Ext.ComponentQuery</a> to
  88 make it really easy to get references to Views on your page. Let's look at an example of this now:</p>
  89
  90 <pre class="prettyprint"><code>Ext.define('MyApp.controller.Users', {
  91     extend: 'Ext.app.Controller',
  92
  93     refs: [
  94         {
  95             ref: 'list',
  96             selector: 'grid'
  97         }
  98     ],
  99
 100     init: function() {
 101         this.control({
 102             'button': {
 103                 click: this.refreshGrid
 104             }
 105         });
 106     },
 107
 108     refreshGrid: function() {
 109         this.getList().store.load();
 110     }
 111 });
 112 </code></pre>
 113
 114 <p>This example assumes the existence of a <a href="Ext.grid.Panel.html" rel="Ext.grid.Panel" class="docClass">Grid</a> on the page, which contains a single button to
 115 refresh the Grid when clicked. In our refs array, we set up a reference to the grid. There are two parts to this -
 116 the 'selector', which is a <a href="Ext.ComponentQuery.html" rel="Ext.ComponentQuery" class="docClass">ComponentQuery</a> selector which finds any grid on the page and
 117 assigns it to the reference 'list'.</p>
 118
 119 <p>By giving the reference a name, we get a number of things for free. The first is the getList function that we use in
 120 the refreshGrid method above. This is generated automatically by the Controller based on the name of our ref, which
 121 was capitalized and prepended with get to go from 'list' to 'getList'.</p>
 122
 123 <p>The way this works is that the first time getList is called by your code, the ComponentQuery selector is run and the
 124 first component that matches the selector ('grid' in this case) will be returned. All future calls to getList will
 125 use a cached reference to that grid. Usually it is advised to use a specific ComponentQuery selector that will only
 126 match a single View in your application (in the case above our selector will match any grid on the page).</p>
 127
 128 <p>Bringing it all together, our init function is called when the application boots, at which time we call this.control
 129 to listen to any click on a <a href="Ext.button.Button.html" rel="Ext.button.Button" class="docClass">button</a> and call our refreshGrid function (again, this will
 130 match any button on the page so we advise a more specific selector than just 'button', but have left it this way for
 131 simplicity). When the button is clicked we use out getList function to refresh the grid.</p>
 132
 133 <p>You can create any number of refs and control any number of components this way, simply adding more functions to
 134 your Controller as you go. For an example of real-world usage of Controllers see the Feed Viewer example in the
 135 examples/app/feed-viewer folder in the SDK download.</p>
 136
 137 <p><u>Generated getter methods</u></p>
 138
 139 <p>Refs aren't the only thing that generate convenient getter methods. Controllers often have to deal with Models and
 140 Stores so the framework offers a couple of easy ways to get access to those too. Let's look at another example:</p>
 141
 142 <pre class="prettyprint"><code>Ext.define('MyApp.controller.Users', {
 143     extend: 'Ext.app.Controller',
 144
 145     models: ['User'],
 146     stores: ['AllUsers', 'AdminUsers'],
 147
 148     init: function() {
 149         var User = this.getUserModel(),
 150             allUsers = this.getAllUsersStore();
 151
 152         var ed = new User({name: 'Ed'});
 153         allUsers.add(ed);
 154     }
 155 });
 156 </code></pre>
 157
 158 <p>By specifying Models and Stores that the Controller cares about, it again dynamically loads them from the appropriate
 159 locations (app/model/User.js, app/store/AllUsers.js and app/store/AdminUsers.js in this case) and creates getter
 160 functions for them all. The example above will create a new User model instance and add it to the AllUsers Store.
 161 Of course, you could do anything in this function but in this case we just did something simple to demonstrate the
 162 functionality.</p>
 163
 164 <p><u>Further Reading</u></p>
 165
 166 <p>For more information about writing <a href="Ext.html" rel="Ext" class="docClass">Ext</a> JS 4 applications, please see the <a href="../guide/application_architecture.html">
 167 application architecture guide</a>. Also see the <a href="Ext.app.Application.html" rel="Ext.app.Application" class="docClass">Ext.app.Application</a> documentation.</p>
 168 <div class="members"><div class="m-cfgs"><div class="definedBy">Defined By</div><a name="configs"></a><h3 class="cfg p">Config Options</h3><h4 class="cfgGroup">Other Configs</h4><div id="config-id" class="member f ni"><a href="Ext.app.Controller.html#config-id" rel="config-id" class="expand more"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.app.Controller.html" class="definedIn docClass">Ext.app.Controller</a><br/><a href="../source/Controller.html#Ext-app.Controller-cfg-id" class="viewSource">view source</a></div><a name="id"></a><a name="config-id"></a><a href="Ext.app.Controller.html#" rel="config-id" class="cls expand">id</a><span> : Object</span></div><div class="description"><div class="short"><p>The id of this controller. You can use this id when dispatching.</p>
 169 </div><div class="long"><p>The id of this controller. You can use this id when dispatching.</p>
 170 </div></div></div></div><div class="m-methods"><a name="methods"></a><div class="definedBy">Defined By</div><h3 class="mth p">Methods</h3><div id="method-Controller" class="member f ni"><a href="Ext.app.Controller.html#method-Controller" rel="method-Controller" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.app.Controller.html" class="definedIn docClass">Ext.app.Controller</a><br/><a href="../source/Controller.html#Ext-app.Controller-method-constructor" class="viewSource">view source</a></div><a name="Controller"></a><a name="method-Controller"></a><a href="Ext.app.Controller.html#" rel="method-Controller" class="cls expand">Controller</a> : void</div><div class="description"><div class="short"><p>&nbsp;</p></div><div class="long">
 171 <h3 class="pa">Returns</h3><ul><li><span class="pre">void</span>&nbsp; &nbsp;
 172 </li></ul></div></div></div></div></div></div></div><div id="pageContent"></div></div></div></div></body></html>