X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/6746dc89c47ed01b165cc1152533605f97eb8e8d..HEAD:/src/app/Controller.js diff --git a/src/app/Controller.js b/src/app/Controller.js index d9992eec..d589ddf3 100644 --- a/src/app/Controller.js +++ b/src/app/Controller.js @@ -14,30 +14,30 @@ If you are unsure which license is appropriate for your use, please contact the */ /** * @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 > panel': { @@ -45,37 +45,37 @@ If you are unsure which license is appropriate for your use, please contact the * } * }); * }, - * + * * 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 > 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 + * 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. - * + * * Using refs - * + * * 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': { @@ -83,68 +83,68 @@ If you are unsure which license is appropriate for your use, please contact the * } * }); * }, - * + * * 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 - + * + * 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. - * + * * Generated getter methods - * - * 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); * } * }); - * + * * 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. - * + * * Further Reading - * + * * 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', { mixins: { @@ -154,6 +154,60 @@ Ext.define('Ext.app.Controller', { /** * @cfg {String} id The id of this controller. You can use this id when dispatching. */ + + /** + * @cfg {String[]} models + * Array of models to require from AppName.model namespace. For example: + * + * Ext.define("MyApp.controller.Foo", { + * extend: "Ext.app.Controller", + * models: ['User', 'Vehicle'] + * }); + * + * This is equivalent of: + * + * Ext.define("MyApp.controller.Foo", { + * extend: "Ext.app.Controller", + * requires: ['MyApp.model.User', 'MyApp.model.Vehicle'] + * }); + * + */ + + /** + * @cfg {String[]} views + * Array of views to require from AppName.view namespace. For example: + * + * Ext.define("MyApp.controller.Foo", { + * extend: "Ext.app.Controller", + * views: ['List', 'Detail'] + * }); + * + * This is equivalent of: + * + * Ext.define("MyApp.controller.Foo", { + * extend: "Ext.app.Controller", + * requires: ['MyApp.view.List', 'MyApp.view.Detail'] + * }); + * + */ + + /** + * @cfg {String[]} stores + * Array of stores to require from AppName.store namespace. For example: + * + * Ext.define("MyApp.controller.Foo", { + * extend: "Ext.app.Controller", + * stores: ['Users', 'Vehicles'] + * }); + * + * This is equivalent of: + * + * Ext.define("MyApp.controller.Foo", { + * extend: "Ext.app.Controller", + * requires: ['MyApp.store.Users', 'MyApp.store.Vehicles'] + * }); + * + */ onClassExtended: function(cls, data) { var className = Ext.getClassName(cls), @@ -212,9 +266,23 @@ Ext.define('Ext.app.Controller', { } }, - // Template method + /** + * 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 + + /** + * 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) { @@ -281,10 +349,10 @@ Ext.define('Ext.app.Controller', { }, /** - * Adds listeners to components selected via {@link Ext.ComponentQuery}. Accepts an - * object containing component paths mapped to a hash of listener functions. + * 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` + * 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', { @@ -295,7 +363,7 @@ Ext.define('Ext.app.Controller', { * } * }); * }, - * + * * updateUser: function(button) { * console.log('clicked the Save button'); * } @@ -303,7 +371,7 @@ Ext.define('Ext.app.Controller', { * * See {@link Ext.ComponentQuery} for more information on component selectors. * - * @param {String|Object} selectors If a String, the second argument is used as the + * @param {String/Object} selectors If a String, the second argument is used as the * listeners, otherwise an object of selectors -> listeners is assumed * @param {Object} listeners */ @@ -312,32 +380,43 @@ Ext.define('Ext.app.Controller', { }, /** - * Returns a reference to a {@link Ext.app.Controller controller} with the given name - * @param name {String} + * 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); }, /** - * Returns a reference to a {@link Ext.data.Store store} with the given name - * @param name {String} + * 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); }, /** - * Returns a reference to a {@link Ext.data.Model Model} with the given name - * @param name {String} + * 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); }, /** - * Returns a reference to a view with the given name - * @param name {String} + * 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);