src/app/Application.js

   1 /*
   2
   3 This file is part of Ext JS 4
   4
   5 Copyright (c) 2011 Sencha Inc
   6
   7 Contact:  http://www.sencha.com/contact
   8
   9 GNU General Public License Usage
  10 This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file.  Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
  11
  12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
  13
  14 */
  15 /**
  16  * Represents an Ext JS 4 application, which is typically a single page app using a {@link Ext.container.Viewport Viewport}.
  17  * A typical Ext.app.Application might look like this:
  18  *
  19  *     Ext.application({
  20  *         name: 'MyApp',
  21  *         launch: function() {
  22  *             Ext.create('Ext.container.Viewport', {
  23  *                 items: {
  24  *                     html: 'My App'
  25  *                 }
  26  *             });
  27  *         }
  28  *     });
  29  *
  30  * This does several things. First it creates a global variable called 'MyApp' - all of your Application's classes (such
  31  * as its Models, Views and Controllers) will reside under this single namespace, which drastically lowers the chances
  32  * of colliding global variables.
  33  *
  34  * When the page is ready and all of your JavaScript has loaded, your Application's {@link #launch} function is called,
  35  * at which time you can run the code that starts your app. Usually this consists of creating a Viewport, as we do in
  36  * the example above.
  37  *
  38  * # Telling Application about the rest of the app
  39  *
  40  * Because an Ext.app.Application represents an entire app, we should tell it about the other parts of the app - namely
  41  * the Models, Views and Controllers that are bundled with the application. Let's say we have a blog management app; we
  42  * might have Models and Controllers for Posts and Comments, and Views for listing, adding and editing Posts and Comments.
  43  * Here's how we'd tell our Application about all these things:
  44  *
  45  *     Ext.application({
  46  *         name: 'Blog',
  47  *         models: ['Post', 'Comment'],
  48  *         controllers: ['Posts', 'Comments'],
  49  *
  50  *         launch: function() {
  51  *             ...
  52  *         }
  53  *     });
  54  *
  55  * Note that we didn't actually list the Views directly in the Application itself. This is because Views are managed by
  56  * Controllers, so it makes sense to keep those dependencies there. The Application will load each of the specified
  57  * Controllers using the pathing conventions laid out in the [application architecture guide][mvc] -
  58  * in this case expecting the controllers to reside in `app/controller/Posts.js` and
  59  * `app/controller/Comments.js`. In turn, each Controller simply needs to list the Views it uses and they will be
  60  * automatically loaded. Here's how our Posts controller like be defined:
  61  *
  62  *     Ext.define('MyApp.controller.Posts', {
  63  *         extend: 'Ext.app.Controller',
  64  *         views: ['posts.List', 'posts.Edit'],
  65  *
  66  *         //the rest of the Controller here
  67  *     });
  68  *
  69  * Because we told our Application about our Models and Controllers, and our Controllers about their Views, Ext JS will
  70  * automatically load all of our app files for us. This means we don't have to manually add script tags into our html
  71  * files whenever we add a new class, but more importantly it enables us to create a minimized build of our entire
  72  * application using the Ext JS 4 SDK Tools.
  73  *
  74  * For more information about writing Ext JS 4 applications, please see the
  75  * [application architecture guide][mvc].
  76  *
  77  * [mvc]: #!/guide/application_architecture
  78  *
  79  * @docauthor Ed Spencer
  80  */
  81 Ext.define('Ext.app.Application', {
  82     extend: 'Ext.app.Controller',
  83
  84     requires: [
  85         'Ext.ModelManager',
  86         'Ext.data.Model',
  87         'Ext.data.StoreManager',
  88         'Ext.tip.QuickTipManager',
  89         'Ext.ComponentManager',
  90         'Ext.app.EventBus'
  91     ],
  92
  93     /**
  94      * @cfg {String} name The name of your application. This will also be the namespace for your views, controllers
  95      * models and stores. Don't use spaces or special characters in the name.
  96      */
  97
  98     /**
  99      * @cfg {Object} scope The scope to execute the {@link #launch} function in. Defaults to the Application
 100      * instance.
 101      */
 102     scope: undefined,
 103
 104     /**
 105      * @cfg {Boolean} enableQuickTips True to automatically set up Ext.tip.QuickTip support.
 106      */
 107     enableQuickTips: true,
 108
 109     /**
 110      * @cfg {String} defaultUrl When the app is first loaded, this url will be redirected to.
 111      */
 112
 113     /**
 114      * @cfg {String} appFolder The path to the directory which contains all application's classes.
 115      * This path will be registered via {@link Ext.Loader#setPath} for the namespace specified in the {@link #name name} config.
 116      */
 117     appFolder: 'app',
 118
 119     /**
 120      * @cfg {Boolean} autoCreateViewport True to automatically load and instantiate AppName.view.Viewport
 121      * before firing the launch function.
 122      */
 123     autoCreateViewport: false,
 124
 125     /**
 126      * Creates new Application.
 127      * @param {Object} [config] Config object.
 128      */
 129     constructor: function(config) {
 130         config = config || {};
 131         Ext.apply(this, config);
 132
 133         var requires = config.requires || [];
 134
 135         Ext.Loader.setPath(this.name, this.appFolder);
 136
 137         if (this.paths) {
 138             Ext.Object.each(this.paths, function(key, value) {
 139                 Ext.Loader.setPath(key, value);
 140             });
 141         }
 142
 143         this.callParent(arguments);
 144
 145         this.eventbus = Ext.create('Ext.app.EventBus');
 146
 147         var controllers = Ext.Array.from(this.controllers),
 148             ln = controllers && controllers.length,
 149             i, controller;
 150
 151         this.controllers = Ext.create('Ext.util.MixedCollection');
 152
 153         if (this.autoCreateViewport) {
 154             requires.push(this.getModuleClassName('Viewport', 'view'));
 155         }
 156
 157         for (i = 0; i < ln; i++) {
 158             requires.push(this.getModuleClassName(controllers[i], 'controller'));
 159         }
 160
 161         Ext.require(requires);
 162
 163         Ext.onReady(function() {
 164             for (i = 0; i < ln; i++) {
 165                 controller = this.getController(controllers[i]);
 166                 controller.init(this);
 167             }
 168
 169             this.onBeforeLaunch.call(this);
 170         }, this);
 171     },
 172
 173     control: function(selectors, listeners, controller) {
 174         this.eventbus.control(selectors, listeners, controller);
 175     },
 176
 177     /**
 178      * Called automatically when the page has completely loaded. This is an empty function that should be
 179      * overridden by each application that needs to take action on page load
 180      * @property launch
 181      * @type Function
 182      * @param {String} profile The detected {@link #profiles application profile}
 183      * @return {Boolean} By default, the Application will dispatch to the configured startup controller and
 184      * action immediately after running the launch function. Return false to prevent this behavior.
 185      */
 186     launch: Ext.emptyFn,
 187
 188     /**
 189      * @private
 190      */
 191     onBeforeLaunch: function() {
 192         if (this.enableQuickTips) {
 193             Ext.tip.QuickTipManager.init();
 194         }
 195
 196         if (this.autoCreateViewport) {
 197             this.getView('Viewport').create();
 198         }
 199
 200         this.launch.call(this.scope || this);
 201         this.launched = true;
 202         this.fireEvent('launch', this);
 203
 204         this.controllers.each(function(controller) {
 205             controller.onLaunch(this);
 206         }, this);
 207     },
 208
 209     getModuleClassName: function(name, type) {
 210         var namespace = Ext.Loader.getPrefix(name);
 211
 212         if (namespace.length > 0 && namespace !== name) {
 213             return name;
 214         }
 215
 216         return this.name + '.' + type + '.' + name;
 217     },
 218
 219     getController: function(name) {
 220         var controller = this.controllers.get(name);
 221
 222         if (!controller) {
 223             controller = Ext.create(this.getModuleClassName(name, 'controller'), {
 224                 application: this,
 225                 id: name
 226             });
 227
 228             this.controllers.add(controller);
 229         }
 230
 231         return controller;
 232     },
 233
 234     getStore: function(name) {
 235         var store = Ext.StoreManager.get(name);
 236
 237         if (!store) {
 238             store = Ext.create(this.getModuleClassName(name, 'store'), {
 239                 storeId: name
 240             });
 241         }
 242
 243         return store;
 244     },
 245
 246     getModel: function(model) {
 247         model = this.getModuleClassName(model, 'model');
 248
 249         return Ext.ModelManager.getModel(model);
 250     },
 251
 252     getView: function(view) {
 253         view = this.getModuleClassName(view, 'view');
 254
 255         return Ext.ClassManager.get(view);
 256     }
 257 });
 258