For up to date documentation and features, visit http://docs.sencha.com/ext-js/4-0

## Sencha Documentation

# Ext.Loader

Ext.Loader is the heart of the new dynamic dependency loading capability in Ext JS 4+. It is most commonly used via the Ext.require shorthand. Ext.Loader supports both asynchronous and synchronous loading approaches, and leverage their advantages for the best development flow. We'll discuss about the pros and cons of each approach:

# Asynchronous Loading

- Advantages:

  - Cross-domain
  - No web server needed: you can run the application via the file system protocol (i.e: `file://path/to/your/index .html`)
  - Best possible debugging experience: error messages come with the exact file name and line number

- Disadvantages:

  - Dependencies need to be specified before-hand

### Method 1: Explicitly include what you need:

    // Syntax
    Ext.require({String/Array} expressions);

    // Example: Single alias
    Ext.require('widget.window');

    // Example: Single class name
    Ext.require('Ext.window.Window');

    // Example: Multiple aliases / class names mix
    Ext.require(['widget.window', 'layout.border', 'Ext.data.Connection']);

    // Wildcards
    Ext.require(['widget.*', 'layout.*', 'Ext.data.*']);

### Method 2: Explicitly exclude what you don't need:

    // Syntax: Note that it must be in this chaining format.
    Ext.exclude({String/Array} expressions)
       .require({String/Array} expressions);

    // Include everything except Ext.data.*
    Ext.exclude('Ext.data.*').require('*');

    // Include all widgets except widget.checkbox*,
    // which will match widget.checkbox, widget.checkboxfield, widget.checkboxgroup, etc.
    Ext.exclude('widget.checkbox*').require('widget.*');

# Synchronous Loading on Demand

- Advantages:

  - There's no need to specify dependencies before-hand, which is always the convenience of including ext-all.js before

- Disadvantages:

  - Not as good debugging experience since file name won't be shown (except in Firebug at the moment)
  - Must be from the same domain due to XHR restriction
  - Need a web server, same reason as above

There's one simple rule to follow: Instantiate everything with Ext.create instead of the `new` keyword

    Ext.create('widget.window', { ... }); // Instead of new Ext.window.Window({...});

    Ext.create('Ext.window.Window', {}); // Same as above, using full class name instead of alias

    Ext.widget('window', {}); // Same as above, all you need is the traditional `xtype`

Behind the scene, Ext.ClassManager will automatically check whether the given class name / alias has already existed on the page. If it's not, Ext.Loader will immediately switch itself to synchronous mode and automatic load the given class and all its dependencies.

# Hybrid Loading - The Best of Both Worlds

It has all the advantages combined from asynchronous and synchronous loading. The development flow is simple:

### Step 1: Start writing your application using synchronous approach. Ext.Loader will automatically fetch all

dependencies on demand as they're needed during run-time. For example: ###

    Ext.onReady(function(){
        var window = Ext.createWidget('window', {
            width: 500,
            height: 300,
            layout: {
                type: 'border',
                padding: 5
            },
            title: 'Hello Dialog',
            items: [{
                title: 'Navigation',
                collapsible: true,
                region: 'west',
                width: 200,
                html: 'Hello',
                split: true
            }, {
                title: 'TabPanel',
                region: 'center'
            }]
        });

        window.show();
    })

### Step 2: Along the way, when you need better debugging ability, watch the console for warnings like these:

    [Ext.Loader] Synchronously loading 'Ext.window.Window'; consider adding Ext.require('Ext.window.Window') before your application's code
    ClassManager.js:432
    [Ext.Loader] Synchronously loading 'Ext.layout.container.Border'; consider adding Ext.require('Ext.layout.container.Border') before your application's code

Simply copy and paste the suggested code above `Ext.onReady`, i.e:

    Ext.require('Ext.window.Window');
    Ext.require('Ext.layout.container.Border');

    Ext.onReady(...);

Everything should now load via asynchronous mode.

# Deployment

It's important to note that dynamic loading should only be used during development on your local machines. During production, all dependencies should be combined into one single JavaScript file. Ext.Loader makes the whole process of transitioning from / to between development / maintenance and production as easy as possible. Internally Ext.Loader.history maintains the list of all dependencies your application needs in the exact loading sequence. It's as simple as concatenating all files in this array into one, then include it on top of your application.

This process will be automated with Sencha Command, to be released and documented towards Ext JS 4 Final.

Defined By

### Config Options

#### Other Configs

Ext.Loader
view source
disableCaching : Boolean

Appends current timestamp to script files to prevent caching Defaults to true

Appends current timestamp to script files to prevent caching Defaults to true

Ext.Loader
view source
disableCachingParam : String

The get parameter name for the cache buster's timestamp. Defaults to '_dc'

The get parameter name for the cache buster's timestamp. Defaults to '_dc'

Ext.Loader
view source
enabled : Boolean

Whether or not to enable the dynamic dependency loading feature Defaults to false

Whether or not to enable the dynamic dependency loading feature Defaults to false

Ext.Loader
view source
paths : Object
The mapping from namespaces to file paths { 'Ext': '.', // This is set by default, Ext.layout.container.Containe...

The mapping from namespaces to file paths

    {
        'Ext': '.', // This is set by default, Ext.layout.container.Container will be
                    // loaded from ./layout/Container.js

        'My': './src/my_own_folder' // My.layout.Container will be loaded from
                                    // ./src/my_own_folder/layout/Container.js
    }

Note that all relative paths are relative to the current HTML document. If not being specified, for example, `Other.awesome.Class` will simply be loaded from `./Other/awesome/Class.js`

Defined By

### Properties

Ext.Loader
view source
history : Array
An array of class names to keep track of the dependency loading order. This is not guaranteed to be the same everytim...

An array of class names to keep track of the dependency loading order. This is not guaranteed to be the same everytime due to the asynchronous nature of the Loader.

Ext.Loader
view source
setPath : Object

Sets the path of a namespace. For Example:

    Ext.Loader.setPath('Ext', '.');

Sets the path of a namespace. For Example:

    Ext.Loader.setPath('Ext', '.');

Defined By

### Methods

Ext.Loader
view source
exclude( Array excludes) : Object
Explicitly exclude files from being loaded. Useful when used in conjunction with a broad include expression. Can be c...

Explicitly exclude files from being loaded. Useful when used in conjunction with a broad include expression. Can be chained with more `require` and `exclude` methods, eg:

    Ext.exclude('Ext.data.*').require('*');

    Ext.exclude('widget.button*').require('widget.*');

### Parameters

- excludes : Array

### Returns

- Object

  object contains `require` method for chaining

Ext.Loader
view source
getConfig( String name) : Object/Mixed

Get the config value corresponding to the specified name. If no name is given, will return the config object

Get the config value corresponding to the specified name. If no name is given, will return the config object

### Parameters

- name : String

  The config property name

### Returns

- Object/Mixed

Ext.Loader
view source
getPath( String className) : String
Translates a className to a file path by adding the the proper prefix and converting the .'s to /'s. For example: Ex...

Translates a className to a file path by adding the the proper prefix and converting the .'s to /'s. For example:

    Ext.Loader.setPath('My', '/path/to/My');

    alert(Ext.Loader.getPath('My.awesome.Class')); // alerts '/path/to/My/awesome/Class.js'

Note that the deeper namespace levels, if explicitly set, are always resolved first. For example:

    Ext.Loader.setPath({
        'My': '/path/to/lib',
        'My.awesome': '/other/path/for/awesome/stuff',
        'My.awesome.more': '/more/awesome/path'
    });

    alert(Ext.Loader.getPath('My.awesome.Class')); // alerts '/other/path/for/awesome/stuff/Class.js'

    alert(Ext.Loader.getPath('My.awesome.more.Class')); // alerts '/more/awesome/path/Class.js'

    alert(Ext.Loader.getPath('My.cool.Class')); // alerts '/path/to/lib/cool/Class.js'

    alert(Ext.Loader.getPath('Unknown.strange.Stuff')); // alerts 'Unknown/strange/Stuff.js'

### Parameters

- className : String

### Returns

- String

  path

Ext.Loader
view source
onReady( Function fn, Object scope, Boolean withDomReady, Object options) : void

Add a new listener to be executed when all required scripts are fully loaded

Add a new listener to be executed when all required scripts are fully loaded

### Parameters

- fn : Function

  The function callback to be executed

- scope : Object

  The execution scope (`this`) of the callback function

- withDomReady : Boolean

  Whether or not to wait for document dom ready as well

- options : Object

### Returns

- void

Ext.Loader
view source
require( String/Array expressions, Function fn, Object scope, String/Array excludes) : void
Loads all classes by the given names and all their direct dependencies; optionally executes the given callback functi...

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 Ext.require for convenience

### Parameters

- expressions : String/Array

  Can either be a string or an array of string

- fn : Function

  (Optional) The callback function

- scope : Object

  (Optional) The execution scope (`this`) of the callback function

- excludes : String/Array

  (Optional) Classes to be excluded, useful when being used with expressions

### Returns

- void

Ext.Loader
view source
setConfig( Object config, Object value) : Ext.Loader
Set the configuration for the loader. This should be called right after ext-core.js (or ext-core-debug.js) is include...

Set the configuration for the loader. This should be called right after ext-core.js (or ext-core-debug.js) is included in the page, i.e:

    <script type="text/javascript" src="ext-core-debug.js"></script>
    <script type="text/javascript">
      Ext.Loader.setConfig({
          enabled: true,
          paths: {
              'My': 'my_own_path'
          }
      });
    <script>
    <script type="text/javascript">
      Ext.require(...);

      Ext.onReady(function() {
          // application code here
      });
    </script>

Refer to configs for the list of possible properties

### Parameters

- config : Object

  The config object to override the default values in config

- value : Object

### Returns

- Ext.Loader

  this

Ext.Loader
view source
syncRequire( String/Array expressions, Function fn, Object scope, String/Array excludes) : void
Synchronously loads all classes by the given names and all their direct dependencies; optionally executes the given c...

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 Ext.syncRequire for convenience

### Parameters

- expressions : String/Array

  Can either be a string or an array of string

- fn : Function

  (Optional) The callback function

- scope : Object

  (Optional) The execution scope (`this`) of the callback function

- excludes : String/Array

  (Optional) Classes to be excluded, useful when being used with expressions

### Returns

- void