Ext JS 4.0.7 Sencha Docs

Ext.Loader

Files

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, e.g.:

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.

Available since: 3.4.0

Defined By

Config options

Appends current timestamp to script files to prevent caching. ...

Appends current timestamp to script files to prevent caching.

Defaults to: true

Available since: 4.0.0

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

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

Defaults to: '_dc'

Available since: 4.0.0

Whether or not to enable the dynamic dependency loading feature. ...

Whether or not to enable the dynamic dependency loading feature.

Defaults to: false

Available since: 4.0.0

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

Defaults to: {'Ext': '.'}

Available since: 4.0.0

Defined By

Properties

...

Defaults to: {}

Available since: 4.0.0

Ext.Loader
view source
: Objectprivate
Configuration ...

Configuration

Defaults to: {enabled: false, disableCaching: true, disableCachingParam: '_dc', paths: {'Ext': '.'}}

Available since: 4.0.0

Ext.Loader
view source
: Objectprivate

Available since: 4.0.0

...

Defaults to: false

Available since: 4.0.0

An array of class names to keep track of the dependency loading order. ...

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.

Defaults to: []

Available since: 4.0.0

Ext.Loader
view source
: Objectprivate
Maintain the list of files that have already been handled so that they never get double-loaded ...

Maintain the list of files that have already been handled so that they never get double-loaded

Defaults to: {}

Available since: 4.0.0

Ext.Loader
view source
: Booleanprivate
Flag indicating whether there are still files being loaded ...

Flag indicating whether there are still files being loaded

Defaults to: false

Available since: 4.0.0

...

Defaults to: 0

Available since: 4.0.0

...

Defaults to: 0

Available since: 4.0.0

Contains optional dependencies to be loaded last ...

Contains optional dependencies to be loaded last

Defaults to: []

Available since: 4.0.0

Ext.Loader
view source
: Arrayprivate
Maintain the queue for all dependencies. ...

Maintain the queue for all dependencies. Each item in the array is an object of the format: {

 requires: [...], // The required classes for this queue item
 callback: function() { ... } // The function to execute when all classes specified in requires exist

}

Defaults to: []

Available since: 4.0.0

Ext.Loader
view source
: Arrayprivate
Maintain the list of listeners to execute when all required scripts are fully loaded ...

Maintain the list of listeners to execute when all required scripts are fully loaded

Defaults to: []

Available since: 4.0.0

Ext.Loader
view source
: Objectprivate
Map of fully qualified class names to an array of dependent classes. ...

Map of fully qualified class names to an array of dependent classes.

Defaults to: {}

Available since: 4.0.0

Defined By

Methods

Ext.Loader
view source
( requires ) : Ext.Loaderchainableprivate
...

Available since: 4.0.0

Parameters

Returns

Ext.Loader
view source
( script ) : Ext.Loaderchainableprivate
...

Available since: 4.0.0

Parameters

Returns

Ext.Loader
view source
( excludes ) : Object
Explicitly exclude files from being loaded. ...

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, e.g.:

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

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

Ext.exclude is alias for Ext.Loader.exclude for convenience.

Available since: 4.0.0

Parameters

Returns

  • Object

    object contains require method for chaining

Fires

    Ext.Loader
    view source
    ( name ) : Object
    Get the config value corresponding to the specified name. ...

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

    Available since: 4.0.0

    Parameters

    • name : String

      The config property name

    Returns

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

    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'
    

    Available since: 4.0.0

    Parameters

    Returns

    Fires

      Ext.Loader
      view source
      ( className )private
      ...

      Available since: 4.0.0

      Parameters

      Ext.Loader
      view source
      ( className ) : Ext.Loaderchainableprivate
      ...

      Available since: 4.0.0

      Parameters

      Returns

      Ext.Loader
      view source
      ( url, onLoad, onError, scope )private
      Inject a script element to document's head, call onLoad and onError accordingly ...

      Inject a script element to document's head, call onLoad and onError accordingly

      Available since: 4.0.0

      Parameters

      Fires

        Ext.Loader
        view source
        ( url, onLoad, scope, synchronous )private
        Load a script file, supports both asynchronous and synchronous approaches ...

        Load a script file, supports both asynchronous and synchronous approaches

        Available since: 4.0.0

        Parameters

        Fires

          Ext.Loader
          view source
          ( className, filePath, errorMessage, isSynchronous )private
          ...

          Available since: 4.0.0

          Parameters

          Ext.Loader
          view source
          ( className, filePath )private
          ...

          Available since: 3.4.0

          Parameters

          Fires

            Ext.Loader
            view source
            ( fn, scope, withDomReady )
            Adds new listener to be executed when all required scripts are fully loaded. ...

            Adds new listener to be executed when all required scripts are fully loaded.

            Available since: 4.0.0

            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

            Ext.Loader
            view source
            ( ) : Ext.Loaderchainableprivate
            Refresh all items in the queue. ...

            Refresh all items in the queue. If all dependencies for an item exist during looping, it will execute the callback and call refreshQueue again. Triggers onReady when the queue is empty

            Available since: 4.0.0

            Returns

            Fires

              Ext.Loader
              view source
              ( expressions, [fn], [scope], [excludes] )
              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.

              Ext.require is alias for Ext.Loader.require for convenience.

              Available since: 4.0.0

              Parameters

              • expressions : String/String[]

                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/String[] (optional)

                Classes to be excluded, useful when being used with expressions

              Fires

                Ext.Loader
                view source
                ( name, [value] ) : Ext.Loaderchainable
                Set the configuration for the loader. ...

                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, e.g.:

                <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 config options of Ext.Loader for the list of possible properties.

                Available since: 4.0.0

                Parameters

                • name : String/Object

                  Name of the value to override, or a config object to override multiple values.

                • value : Object (optional)

                  The new value to set, needed if first parameter is String.

                Returns

                Ext.Loader
                view source
                ( name, path ) : Ext.Loaderchainable
                Sets the path of a namespace. ...

                Sets the path of a namespace. For Example:

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

                Available since: 4.0.0

                Parameters

                Returns

                Ext.Loader
                view source
                ( expressions, [fn], [scope], [excludes] )
                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.

                Ext.syncRequire is alias for Ext.Loader.syncRequire for convenience.

                Available since: 4.0.0

                Parameters

                • expressions : String/String[]

                  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/String[] (optional)

                  Classes to be excluded, useful when being used with expressions

                Fires

                  Ext.Loader
                  view source
                  ( force ) : Ext.Loaderchainableprivate
                  ...

                  Available since: 4.0.0

                  Parameters

                  Returns

                  Fires