Upgrade to ExtJS 4.0.0 - Released 04/26/2011
[extjs.git] / docs / api / Ext.app.Controller.html
diff --git a/docs/api/Ext.app.Controller.html b/docs/api/Ext.app.Controller.html
new file mode 100644 (file)
index 0000000..0d8b760
--- /dev/null
@@ -0,0 +1,172 @@
+<!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]>
+<style type="text/css">.head-band { display: none; }
+.header { border: 0; top: 0; left: 0px; background: url(../header.gif) repeat-x; }
+.doc-tab .members .member a.more { background-color: #efefef; }
+</style><link rel="stylesheet" href="/new/css/ie.css" type="text/css"><![endif]-->
+</head><body id="ext-body" class="iScroll"><div id="notice" class="notice">For up to date documentation and features, visit 
+<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">
+
+    req = {
+        liveURL: '.',
+        standAloneMode: true,
+        origDocClass: 'Ext.app.Controller',
+        docClass: 'Ext.app.Controller',
+        docReq: 'Ext.app.Controller',
+        version: '4.0',
+        baseURL: '.',
+        baseDocURL: '.',
+        baseProdURL: '.'
+    };
+
+    clsInfo = {};
+
+
+
+</script>
+
+<script type="text/javascript" src="../search.js"></script>
+<!--script type="text/javascript" src="/new/javascripts/app/examples.js"></script-->
+<script type="text/javascript" src="../class_tree.js"></script>
+<script type="text/javascript" src="../class_doc.js"></script>
+<script type="text/javascript">
+    req.source = 'Controller.html#Ext-app.Controller';
+    clsInfo = {"methods":["Controller"],"cfgs":["id"],"properties":[],"events":[],"subclasses":["Ext.app.Application"]};
+    Ext.onReady(function() {
+        Ext.create('Docs.classPanel');
+    });
+</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
+views) and take some action. Here's how we might create a Controller to manage Users:</p>
+
+<pre class="prettyprint"><code>Ext.define('MyApp.controller.Users', {
+    extend: 'Ext.app.Controller',
+
+    init: function() {
+        console.log('Initialized Users! This happens before the Application launch function is called');
+    }
+});
+</code></pre>
+
+<p>The init function is a special method that is called when your application boots. It is called before the
+<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
+your Viewport is created.</p>
+
+<p>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 - <a href="Ext.app.Controller.html#control" rel="Ext.app.Controller#control" class="docClass">control</a>. 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:</p>
+
+<pre class="prettyprint"><code>Ext.define('MyApp.controller.Users', {
+    extend: 'Ext.app.Controller',
+
+    init: function() {
+        this.control({
+            'viewport &gt; panel': {
+                render: this.onPanelRendered
+            }
+        });
+    },
+
+    onPanelRendered: function() {
+        console.log('The panel was rendered');
+    }
+});
+</code></pre>
+
+<p>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,
+it allows us to pass a CSS-like selector that will find every matching component on the page.</p>
+
+<p>In our init function above we supplied 'viewport > panel', which translates to "find me every Panel that is a direct
+child of a Viewport". 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.</p>
+
+<p><u>Using refs</u></p>
+
+<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
+make it really easy to get references to Views on your page. Let's look at an example of this now:</p>
+
+<pre class="prettyprint"><code>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();
+    }
+});
+</code></pre>
+
+<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
+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 <a href="Ext.ComponentQuery.html" rel="Ext.ComponentQuery" class="docClass">ComponentQuery</a> selector which finds any grid on the page and
+assigns it to the reference 'list'.</p>
+
+<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
+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'.</p>
+
+<p>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
+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).</p>
+
+<p>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 <a href="Ext.button.Button.html" rel="Ext.button.Button" class="docClass">button</a> 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.</p>
+
+<p>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.</p>
+
+<p><u>Generated getter methods</u></p>
+
+<p>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:</p>
+
+<pre class="prettyprint"><code>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);
+    }
+});
+</code></pre>
+
+<p>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
+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
+functionality.</p>
+
+<p><u>Further Reading</u></p>
+
+<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">
+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>
+<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>
+</div><div class="long"><p>The id of this controller. You can use this id when dispatching.</p>
+</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">
+<h3 class="pa">Returns</h3><ul><li><span class="pre">void</span>&nbsp; &nbsp;
+</li></ul></div></div></div></div></div></div></div><div id="pageContent"></div></div></div></div></body></html>
\ No newline at end of file