docs/output/Ext.Loader.js

   1 Ext.data.JsonP.Ext_Loader({
   2   "tagname": "class",
   3   "name": "Ext.Loader",
   4   "doc": "<p>Ext.Loader is the heart of the new dynamic dependency loading capability in <a href=\"#/api/Ext\" rel=\"Ext\" class=\"docClass\">Ext</a> JS 4+. It is most commonly used\nvia the <a href=\"#/api/Ext-method-require\" rel=\"Ext-method-require\" class=\"docClass\">Ext.require</a> shorthand. <a href=\"#/api/Ext.Loader\" rel=\"Ext.Loader\" class=\"docClass\">Ext.Loader</a> supports both asynchronous and synchronous loading\napproaches, and leverage their advantages for the best development flow. We'll discuss about the pros and cons of each approach:</p>\n\n<h1>Asynchronous Loading</h1>\n\n<ul>\n<li><p>Advantages:</p>\n\n<ul>\n<li>Cross-domain</li>\n<li>No web server needed: you can run the application via the file system protocol (i.e: <code>file://path/to/your/index\n.html</code>)</li>\n<li>Best possible debugging experience: error messages come with the exact file name and line number</li>\n</ul>\n</li>\n<li><p>Disadvantages:</p>\n\n<ul>\n<li>Dependencies need to be specified before-hand</li>\n</ul>\n</li>\n</ul>\n\n\n<h3>Method 1: Explicitly include what you need:</h3>\n\n<pre><code>// Syntax\nExt.require({String/Array} expressions);\n\n// Example: Single alias\nExt.require('widget.window');\n\n// Example: Single class name\nExt.require('Ext.window.Window');\n\n// Example: Multiple aliases / class names mix\nExt.require(['widget.window', 'layout.border', 'Ext.data.Connection']);\n\n// Wildcards\nExt.require(['widget.*', 'layout.*', 'Ext.data.*']);\n</code></pre>\n\n<h3>Method 2: Explicitly exclude what you don't need:</h3>\n\n<pre><code>// Syntax: Note that it must be in this chaining format.\nExt.exclude({String/Array} expressions)\n   .require({String/Array} expressions);\n\n// Include everything except Ext.data.*\nExt.exclude('Ext.data.*').require('*'); \n\n// Include all widgets except widget.checkbox*,\n// which will match widget.checkbox, widget.checkboxfield, widget.checkboxgroup, etc.\nExt.exclude('widget.checkbox*').require('widget.*');\n</code></pre>\n\n<h1>Synchronous Loading on Demand</h1>\n\n<ul>\n<li><p><em>Advantages:</em></p>\n\n<ul>\n<li>There's no need to specify dependencies before-hand, which is always the convenience of including ext-all.js\nbefore</li>\n</ul>\n</li>\n<li><p><em>Disadvantages:</em></p>\n\n<ul>\n<li>Not as good debugging experience since file name won't be shown (except in Firebug at the moment)</li>\n<li>Must be from the same domain due to XHR restriction</li>\n<li>Need a web server, same reason as above</li>\n</ul>\n</li>\n</ul>\n\n\n<p>There's one simple rule to follow: Instantiate everything with Ext.create instead of the <code>new</code> keyword</p>\n\n<pre><code>Ext.create('widget.window', { ... }); // Instead of new Ext.window.Window({...});\n\nExt.create('Ext.window.Window', {}); // Same as above, using full class name instead of alias\n\nExt.widget('window', {}); // Same as above, all you need is the traditional `xtype`\n</code></pre>\n\n<p>Behind the scene, <a href=\"#/api/Ext.ClassManager\" rel=\"Ext.ClassManager\" class=\"docClass\">Ext.ClassManager</a> will automatically check whether the given class name / alias has already\n existed on the page. If it's not, <a href=\"#/api/Ext.Loader\" rel=\"Ext.Loader\" class=\"docClass\">Ext.Loader</a> will immediately switch itself to synchronous mode and automatic load the given\n class and all its dependencies.</p>\n\n<h1>Hybrid Loading - The Best of Both Worlds</h1>\n\n<p>It has all the advantages combined from asynchronous and synchronous loading. The development flow is simple:</p>\n\n<h3>Step 1: Start writing your application using synchronous approach. <a href=\"#/api/Ext.Loader\" rel=\"Ext.Loader\" class=\"docClass\">Ext.Loader</a> will automatically fetch all</h3>\n\n<p> dependencies on demand as they're needed during run-time. For example: ###</p>\n\n<pre><code>Ext.onReady(function(){\n    var window = Ext.createWidget('window', {\n        width: 500,\n        height: 300,\n        layout: {\n            type: 'border',\n            padding: 5\n        },\n        title: 'Hello Dialog',\n        items: [{\n            title: 'Navigation',\n            collapsible: true,\n            region: 'west',\n            width: 200,\n            html: 'Hello',\n            split: true\n        }, {\n            title: 'TabPanel',\n            region: 'center'\n        }]\n    });\n\n    window.show();\n})\n</code></pre>\n\n<h3>Step 2: Along the way, when you need better debugging ability, watch the console for warnings like these:</h3>\n\n<pre><code>[Ext.Loader] Synchronously loading 'Ext.window.Window'; consider adding Ext.require('Ext.window.Window') before your application's code\nClassManager.js:432\n[Ext.Loader] Synchronously loading 'Ext.layout.container.Border'; consider adding Ext.require('Ext.layout.container.Border') before your application's code\n</code></pre>\n\n<p>Simply copy and paste the suggested code above <code>Ext.onReady</code>, i.e:</p>\n\n<pre><code>Ext.require('Ext.window.Window');\nExt.require('Ext.layout.container.Border');\n\nExt.onReady(...);\n</code></pre>\n\n<p>Everything should now load via asynchronous mode.</p>\n\n<h1>Deployment</h1>\n\n<p>It's important to note that dynamic loading should only be used during development on your local machines.\nDuring production, all dependencies should be combined into one single JavaScript file. <a href=\"#/api/Ext.Loader\" rel=\"Ext.Loader\" class=\"docClass\">Ext.Loader</a> makes\nthe whole process of transitioning from / to between development / maintenance and production as easy as\npossible. Internally <a href=\"#/api/Ext.Loader-property-history\" rel=\"Ext.Loader-property-history\" class=\"docClass\">Ext.Loader.history</a> maintains the list of all dependencies your application\nneeds in the exact loading sequence. It's as simple as concatenating all files in this array into one,\nthen include it on top of your application.</p>\n\n<p>This process will be automated with Sencha Command, to be released and documented towards <a href=\"#/api/Ext\" rel=\"Ext\" class=\"docClass\">Ext</a> JS 4 Final.</p>\n",
   5   "extends": null,
   6   "mixins": [
   7
   8   ],
   9   "alternateClassNames": [
  10
  11   ],
  12   "xtype": null,
  13   "author": "Jacky Nguyen <jacky@sencha.com>",
  14   "docauthor": "Jacky Nguyen <jacky@sencha.com>",
  15   "singleton": true,
  16   "private": false,
  17   "cfg": [
  18     {
  19       "tagname": "cfg",
  20       "name": "disableCaching",
  21       "member": "Ext.Loader",
  22       "type": "Boolean",
  23       "doc": "<p>Appends current timestamp to script files to prevent caching\nDefaults to true</p>\n",
  24       "private": false,
  25       "filename": "/Users/nick/Projects/sencha/SDK/platform/core/src/class/Loader.js",
  26       "linenr": 234,
  27       "html_filename": "Loader.html",
  28       "href": "Loader.html#Ext-Loader-cfg-disableCaching"
  29     },
  30     {
  31       "tagname": "cfg",
  32       "name": "disableCachingParam",
  33       "member": "Ext.Loader",
  34       "type": "String",
  35       "doc": "<p>The get parameter name for the cache buster's timestamp.\nDefaults to '_dc'</p>\n",
  36       "private": false,
  37       "filename": "/Users/nick/Projects/sencha/SDK/platform/core/src/class/Loader.js",
  38       "linenr": 241,
  39       "html_filename": "Loader.html",
  40       "href": "Loader.html#Ext-Loader-cfg-disableCachingParam"
  41     },
  42     {
  43       "tagname": "cfg",
  44       "name": "enabled",
  45       "member": "Ext.Loader",
  46       "type": "Boolean",
  47       "doc": "<p>Whether or not to enable the dynamic dependency loading feature\nDefaults to false</p>\n",
  48       "private": false,
  49       "filename": "/Users/nick/Projects/sencha/SDK/platform/core/src/class/Loader.js",
  50       "linenr": 227,
  51       "html_filename": "Loader.html",
  52       "href": "Loader.html#Ext-Loader-cfg-enabled"
  53     },
  54     {
  55       "tagname": "cfg",
  56       "name": "paths",
  57       "member": "Ext.Loader",
  58       "type": "Object",
  59       "doc": "<p>The mapping from namespaces to file paths</p>\n\n<pre><code>{\n    'Ext': '.', // This is set by default, <a href=\"#/api/Ext.layout.container.Container\" rel=\"Ext.layout.container.Container\" class=\"docClass\">Ext.layout.container.Container</a> will be\n                // loaded from ./layout/Container.js\n\n    'My': './src/my_own_folder' // My.layout.Container will be loaded from\n                                // ./src/my_own_folder/layout/Container.js\n}\n</code></pre>\n\n<p>Note that all relative paths are relative to the current HTML document.\nIf not being specified, for example, <code>Other.awesome.Class</code>\nwill simply be loaded from <code>./Other/awesome/Class.js</code></p>\n",
  60       "private": false,
  61       "filename": "/Users/nick/Projects/sencha/SDK/platform/core/src/class/Loader.js",
  62       "linenr": 248,
  63       "html_filename": "Loader.html",
  64       "href": "Loader.html#Ext-Loader-cfg-paths",
  65       "shortDoc": "The mapping from namespaces to file paths\n\n{\n    'Ext': '.', // This is set by default, Ext.layout.container.Containe..."
  66     }
  67   ],
  68   "method": [
  69     {
  70       "tagname": "method",
  71       "name": "exclude",
  72       "member": "Ext.Loader",
  73       "doc": "<p>Explicitly exclude files from being loaded. Useful when used in conjunction with a broad include expression.\nCan be chained with more <code>require</code> and <code>exclude</code> methods, eg:</p>\n\n<pre><code>Ext.exclude('Ext.data.*').require('*');\n\nExt.exclude('widget.button*').require('widget.*');\n</code></pre>\n",
  74       "params": [
  75         {
  76           "type": "Array",
  77           "name": "excludes",
  78           "doc": "\n",
  79           "optional": false
  80         }
  81       ],
  82       "return": {
  83         "type": "Object",
  84         "doc": "<p>object contains <code>require</code> method for chaining</p>\n"
  85       },
  86       "private": false,
  87       "static": false,
  88       "filename": "/Users/nick/Projects/sencha/SDK/platform/core/src/class/Loader.js",
  89       "linenr": 593,
  90       "html_filename": "Loader.html",
  91       "href": "Loader.html#Ext-Loader-method-exclude",
  92       "shortDoc": "Explicitly exclude files from being loaded. Useful when used in conjunction with a broad include expression.\nCan be c..."
  93     },
  94     {
  95       "tagname": "method",
  96       "name": "getConfig",
  97       "member": "Ext.Loader",
  98       "doc": "<p>Get the config value corresponding to the specified name. If no name is given, will return the config object</p>\n",
  99       "params": [
 100         {
 101           "type": "String",
 102           "name": "name",
 103           "doc": "<p>The config property name</p>\n",
 104           "optional": false
 105         }
 106       ],
 107       "return": {
 108         "type": "Object/Mixed",
 109         "doc": "\n"
 110       },
 111       "private": false,
 112       "static": false,
 113       "filename": "/Users/nick/Projects/sencha/SDK/platform/core/src/class/Loader.js",
 114       "linenr": 305,
 115       "html_filename": "Loader.html",
 116       "href": "Loader.html#Ext-Loader-method-getConfig",
 117       "shortDoc": "<p>Get the config value corresponding to the specified name. If no name is given, will return the config object</p>\n"
 118     },
 119     {
 120       "tagname": "method",
 121       "name": "getPath",
 122       "member": "Ext.Loader",
 123       "doc": "<p>Translates a className to a file path by adding the\nthe proper prefix and converting the .'s to /'s. For example:</p>\n\n<pre><code>Ext.Loader.setPath('My', '/path/to/My');\n\nalert(Ext.Loader.getPath('My.awesome.Class')); // alerts '/path/to/My/awesome/Class.js'\n</code></pre>\n\n<p>Note that the deeper namespace levels, if explicitly set, are always resolved first. For example:</p>\n\n<pre><code>Ext.Loader.setPath({\n    'My': '/path/to/lib',\n    'My.awesome': '/other/path/for/awesome/stuff',\n    'My.awesome.more': '/more/awesome/path'\n});\n\nalert(Ext.Loader.getPath('My.awesome.Class')); // alerts '/other/path/for/awesome/stuff/Class.js'\n\nalert(Ext.Loader.getPath('My.awesome.more.Class')); // alerts '/more/awesome/path/Class.js'\n\nalert(Ext.Loader.getPath('My.cool.Class')); // alerts '/path/to/lib/cool/Class.js'\n\nalert(Ext.Loader.getPath('Unknown.strange.Stuff')); // alerts 'Unknown/strange/Stuff.js'\n</code></pre>\n",
 124       "params": [
 125         {
 126           "type": "String",
 127           "name": "className",
 128           "doc": "\n",
 129           "optional": false
 130         }
 131       ],
 132       "return": {
 133         "type": "String",
 134         "doc": "<p>path</p>\n"
 135       },
 136       "private": false,
 137       "static": false,
 138       "filename": "/Users/nick/Projects/sencha/SDK/platform/core/src/class/Loader.js",
 139       "linenr": 343,
 140       "html_filename": "Loader.html",
 141       "href": "Loader.html#Ext-Loader-method-getPath",
 142       "shortDoc": "Translates a className to a file path by adding the\nthe proper prefix and converting the .'s to /'s. For example:\n\nEx..."
 143     },
 144     {
 145       "tagname": "method",
 146       "name": "onReady",
 147       "member": "Ext.Loader",
 148       "doc": "<p>Add a new listener to be executed when all required scripts are fully loaded</p>\n",
 149       "params": [
 150         {
 151           "type": "Function",
 152           "name": "fn",
 153           "doc": "<p>The function callback to be executed</p>\n",
 154           "optional": false
 155         },
 156         {
 157           "type": "Object",
 158           "name": "scope",
 159           "doc": "<p>The execution scope (<code>this</code>) of the callback function</p>\n",
 160           "optional": false
 161         },
 162         {
 163           "type": "Boolean",
 164           "name": "withDomReady",
 165           "doc": "<p>Whether or not to wait for document dom ready as well</p>\n",
 166           "optional": false
 167         },
 168         {
 169           "type": "Object",
 170           "name": "options",
 171           "doc": "\n",
 172           "optional": false
 173         }
 174       ],
 175       "return": {
 176         "type": "void",
 177         "doc": "\n"
 178       },
 179       "private": false,
 180       "static": false,
 181       "filename": "/Users/nick/Projects/sencha/SDK/platform/core/src/class/Loader.js",
 182       "linenr": 902,
 183       "html_filename": "Loader.html",
 184       "href": "Loader.html#Ext-Loader-method-onReady",
 185       "shortDoc": "<p>Add a new listener to be executed when all required scripts are fully loaded</p>\n"
 186     },
 187     {
 188       "tagname": "method",
 189       "name": "require",
 190       "member": "Ext.Loader",
 191       "doc": "<p>Loads all classes by the given names and all their direct dependencies; optionally executes the given callback function when\nfinishes, within the optional scope. This method is aliased by <a href=\"#/api/Ext-method-require\" rel=\"Ext-method-require\" class=\"docClass\">Ext.require</a> for convenience</p>\n",
 192       "params": [
 193         {
 194           "type": "String/Array",
 195           "name": "expressions",
 196           "doc": "<p>Can either be a string or an array of string</p>\n",
 197           "optional": false
 198         },
 199         {
 200           "type": "Function",
 201           "name": "fn",
 202           "doc": "<p>(Optional) The callback function</p>\n",
 203           "optional": false
 204         },
 205         {
 206           "type": "Object",
 207           "name": "scope",
 208           "doc": "<p>(Optional) The execution scope (<code>this</code>) of the callback function</p>\n",
 209           "optional": false
 210         },
 211         {
 212           "type": "String/Array",
 213           "name": "excludes",
 214           "doc": "<p>(Optional) Classes to be excluded, useful when being used with expressions</p>\n",
 215           "optional": false
 216         }
 217       ],
 218       "return": {
 219         "type": "void",
 220         "doc": "\n"
 221       },
 222       "private": false,
 223       "static": false,
 224       "filename": "/Users/nick/Projects/sencha/SDK/platform/core/src/class/Loader.js",
 225       "linenr": 634,
 226       "html_filename": "Loader.html",
 227       "href": "Loader.html#Ext-Loader-method-require",
 228       "shortDoc": "Loads all classes by the given names and all their direct dependencies; optionally executes the given callback functi..."
 229     },
 230     {
 231       "tagname": "method",
 232       "name": "setConfig",
 233       "member": "Ext.Loader",
 234       "doc": "<p>Set the configuration for the loader. This should be called right after ext-core.js\n(or ext-core-debug.js) is included in the page, i.e:</p>\n\n<pre><code>&lt;script type=\"text/javascript\" src=\"ext-core-debug.js\"&gt;&lt;/script&gt;\n&lt;script type=\"text/javascript\"&gt;\n  Ext.Loader.setConfig({\n      enabled: true,\n      paths: {\n          'My': 'my_own_path'\n      }\n  });\n&lt;script&gt;\n&lt;script type=\"text/javascript\"&gt;\n  Ext.require(...);\n\n  Ext.onReady(function() {\n      // application code here\n  });\n&lt;/script&gt;\n</code></pre>\n\n<p>Refer to <a href=\"#/api/Ext.Loader--configs\" rel=\"Ext.Loader--configs\" class=\"docClass\">configs</a> for the list of possible properties</p>\n",
 235       "params": [
 236         {
 237           "type": "Object",
 238           "name": "config",
 239           "doc": "<p>The config object to override the default values in <a href=\"#/api/Ext.Loader--config\" rel=\"Ext.Loader--config\" class=\"docClass\">config</a></p>\n",
 240           "optional": false
 241         },
 242         {
 243           "type": "Object",
 244           "name": "value",
 245           "doc": "\n",
 246           "optional": false
 247         }
 248       ],
 249       "return": {
 250         "type": "Ext.Loader",
 251         "doc": "<p>this</p>\n"
 252       },
 253       "private": false,
 254       "static": false,
 255       "filename": "/Users/nick/Projects/sencha/SDK/platform/core/src/class/Loader.js",
 256       "linenr": 267,
 257       "html_filename": "Loader.html",
 258       "href": "Loader.html#Ext-Loader-method-setConfig",
 259       "shortDoc": "Set the configuration for the loader. This should be called right after ext-core.js\n(or ext-core-debug.js) is include..."
 260     },
 261     {
 262       "tagname": "method",
 263       "name": "setPath",
 264       "member": "Ext.Loader",
 265       "doc": "<p>Sets the path of a namespace.\nFor Example:</p>\n\n<pre><code>Ext.Loader.setPath('Ext', '.');\n</code></pre>\n",
 266       "params": [
 267         {
 268           "type": "String/Object",
 269           "name": "name",
 270           "doc": "<p>See <a href=\"#/api/Ext.Function-method-flexSetter\" rel=\"Ext.Function-method-flexSetter\" class=\"docClass\">flexSetter</a></p>\n",
 271           "optional": false
 272         },
 273         {
 274           "type": "String",
 275           "name": "path",
 276           "doc": "<p>See <a href=\"#/api/Ext.Function-method-flexSetter\" rel=\"Ext.Function-method-flexSetter\" class=\"docClass\">flexSetter</a></p>\n",
 277           "optional": false
 278         }
 279       ],
 280       "return": {
 281         "type": "Ext.Loader",
 282         "doc": "<p>this</p>\n"
 283       },
 284       "private": false,
 285       "static": false,
 286       "filename": "/Users/nick/Projects/sencha/SDK/platform/core/src/class/Loader.js",
 287       "linenr": 318,
 288       "html_filename": "Loader.html",
 289       "href": "Loader.html#Ext-Loader-method-setPath",
 290       "shortDoc": "<p>Sets the path of a namespace.\nFor Example:</p>\n\n<pre><code>Ext.Loader.setPath('Ext', '.');\n</code></pre>\n"
 291     },
 292     {
 293       "tagname": "method",
 294       "name": "syncRequire",
 295       "member": "Ext.Loader",
 296       "doc": "<p>Synchronously loads all classes by the given names and all their direct dependencies; optionally executes the given callback function when finishes, within the optional scope. This method is aliased by <a href=\"#/api/Ext-method-syncRequire\" rel=\"Ext-method-syncRequire\" class=\"docClass\">Ext.syncRequire</a> for convenience</p>\n",
 297       "params": [
 298         {
 299           "type": "String/Array",
 300           "name": "expressions",
 301           "doc": "<p>Can either be a string or an array of string</p>\n",
 302           "optional": false
 303         },
 304         {
 305           "type": "Function",
 306           "name": "fn",
 307           "doc": "<p>(Optional) The callback function</p>\n",
 308           "optional": false
 309         },
 310         {
 311           "type": "Object",
 312           "name": "scope",
 313           "doc": "<p>(Optional) The execution scope (<code>this</code>) of the callback function</p>\n",
 314           "optional": false
 315         },
 316         {
 317           "type": "String/Array",
 318           "name": "excludes",
 319           "doc": "<p>(Optional) Classes to be excluded, useful when being used with expressions</p>\n",
 320           "optional": false
 321         }
 322       ],
 323       "return": {
 324         "type": "void",
 325         "doc": "\n"
 326       },
 327       "private": false,
 328       "static": false,
 329       "filename": "/Users/nick/Projects/sencha/SDK/platform/core/src/class/Loader.js",
 330       "linenr": 619,
 331       "html_filename": "Loader.html",
 332       "href": "Loader.html#Ext-Loader-method-syncRequire",
 333       "shortDoc": "Synchronously loads all classes by the given names and all their direct dependencies; optionally executes the given c..."
 334     }
 335   ],
 336   "property": [
 337     {
 338       "tagname": "property",
 339       "name": "history",
 340       "member": "Ext.Loader",
 341       "type": "Array",
 342       "doc": "<p>An array of class names to keep track of the dependency loading order.\nThis is not guaranteed to be the same everytime due to the asynchronous\nnature of the Loader.</p>\n",
 343       "private": false,
 344       "static": false,
 345       "filename": "/Users/nick/Projects/sencha/SDK/platform/core/src/class/Loader.js",
 346       "linenr": 212,
 347       "html_filename": "Loader.html",
 348       "href": "Loader.html#Ext-Loader-property-history",
 349       "shortDoc": "An array of class names to keep track of the dependency loading order.\nThis is not guaranteed to be the same everytim..."
 350     }
 351   ],
 352   "event": [
 353
 354   ],
 355   "filename": "/Users/nick/Projects/sencha/SDK/platform/core/src/class/Loader.js",
 356   "linenr": 1,
 357   "html_filename": "Loader.html",
 358   "href": "Loader.html#Ext-Loader",
 359   "cssVar": [
 360
 361   ],
 362   "cssMixin": [
 363
 364   ],
 365   "component": false,
 366   "superclasses": [
 367
 368   ],
 369   "subclasses": [
 370
 371   ],
 372   "mixedInto": [
 373
 374   ],
 375   "allMixins": [
 376
 377   ]
 378 });