#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

# Loader Class

Defined in: `loader/js/loader.js:60`
Module: loader-base
Parent Module: loader

Loader dynamically loads script and css files. It includes the dependency info for the version of the library in use, and will automatically pull in dependencies for the modules requested. It can load the files from the Yahoo! CDN, and it can utilize the combo service provided on this network to reduce the number of http connections required to download YUI files. You can also specify an external, custom combo service to host your modules as well.

       var Y = YUI();
       var loader = new Y.Loader({
           filter: 'debug',
           base: '../../',
           root: 'build/',
           combine: true,
           require: ['node', 'dd', 'console']
       });
       var out = loader.resolve(true);

## Constructor

### `Loader`

(

- `config`

)

Defined in `loader/js/loader.js:60`

#### Parameters:

- `config` Object

  an optional set of configuration options.

  - `base` String

    The base dir which to fetch this module from

  - `comboBase` String

    The Combo service base path. Ex: `http://yui.yahooapis.com/combo?`

  - `root` String

    The root path to prepend to module names for the combo service. Ex: `2.5.2/build/`

  - `filter` String | Object

    A filter to apply to result urls. See filter property

  - `filters` Object

    Per-component filter specification. If specified for a given component, this overrides the filter config.

  - `combine` Boolean

    Use a combo service to reduce the number of http connections required to load your dependencies

  - `[async=true]` Boolean optional

    Fetch files in async

  - `ignore:` Array

    A list of modules that should never be dynamically loaded

  - `force` Array

    A list of modules that should always be loaded when required, even if already present on the page

  - `insertBefore` HTMLElement | String

    Node or id for a node that should be used as the insertion point for new nodes

  - `jsAttributes` Object

    Object literal containing attributes to add to script nodes

  - `cssAttributes` Object

    Object literal containing attributes to add to link nodes

  - `timeout` Number

    The number of milliseconds before a timeout occurs when dynamically loading nodes. If not set, there is no timeout

  - `context` Object

    Execution context for all callbacks

  - `onSuccess` Function

    Callback for the 'success' event

  - `onFailure` Function

    Callback for the 'failure' event

  - `onCSS` Function

    Callback for the 'CSSComplete' event. When loading YUI components with CSS the CSS is loaded first, then the script. This provides a moment you can tie into to improve the presentation of the page while the script is loading.

  - `onTimeout` Function

    Callback for the 'timeout' event

  - `onProgress` Function

    Callback executed each time a script or css file is loaded

  - `modules` Object

    A list of module definitions. See Loader.addModule for the supported module metadata

  - `groups` Object

    A list of group definitions. Each group can contain specific definitions for `base`, `comboBase`, `combine`, and accepts a list of `modules`.

  - `2in3` String

    The version of the YUI 2 in 3 wrapper to use. The intrinsic support for YUI 2 modules in YUI 3 relies on versions of the YUI 2 components inside YUI 3 module wrappers. These wrappers change over time to accomodate the issues that arise from running YUI 2 in a YUI 3 sandbox.

  - `yui2` String

    When using the 2in3 project, you can select the version of YUI 2 to use. Valid values are `2.2.2`, `2.3.1`, `2.4.1`, `2.5.2`, `2.6.0`, `2.7.0`, `2.8.0`, `2.8.1` and `2.9.0` [default] -- plus all versions of YUI 2 going forward.

- Index
- Methods
- Properties

## Item Index

### Methods

- _addLangPack
- _addSkin
- _config
- _continue
- _explode
- _explodeRollups
- _filter
- _finish
- _insert
- _onFailure
- _onProgress
- _onSuccess
- _onTimeout
- _patternTest
- _populateCache
- _reduce
- _resetModules
- _rollup
- _setup
- _sort
- _url
- addAlias
- addGroup
- addModule
- calculate
- filterRequires
- formatSkin
- getLangPackName
- getModule
- getProvides
- getRequires
- insert
- isCSSLoaded
- load
- loadNext deprecated
- onCSS
- onFailure
- onProgress
- onSuccess
- onTimeout
- require
- resolve

### Properties

- _internalCallback
- allowRollup
- async
- base
- charset deprecated
- combine
- comboBase
- comboSep
- context
- cssAttributes
- data
- dirty
- filter
- FILTER_DEFS
- filters
- force
- ignore
- ignoreRegistered
- insertBefore
- inserted
- jsAttributes
- loaded
- loadOptional
- maxURLLength
- moduleInfo
- patterns
- REGEX_CSS
- required
- rollups
- root
- skin
- skipped
- sorted
- timeout

## Methods

### `_addLangPack`

(

- `lang`
- `m`
- `packName`

)
Object private

Defined in `loader/js/loader.js:1709`

Creates a "psuedo" package for languages provided in the lang array

#### Parameters:

- `lang` String

  The language to create

- `m` Object

  The module definition to create the language pack around

- `packName` String

  The name of the package (e.g: lang/datatype-date-en-US)

#### Returns:

Object: The module definition

### `_addSkin`

(

- `skin`
- `mod`
- `parent`

)
String private

Defined in `loader/js/loader.js:857`

Adds the skin def to the module info

#### Parameters:

- `skin` String

  the name of the skin.

- `mod` String

  the name of the module.

- `parent` String

  parent module if this is a skin of a submodule or plugin.

#### Returns:

String: the module name for the skin.

### `_config`

(

- `o`

)
private

Defined in `loader/js/loader.js:734`

Apply a new config to the Loader instance

#### Parameters:

- `o` Object

  The new configuration

### `_continue`

() private

Defined in `loader/js/loader.js:2388`

Once a loader operation is completely finished, process any additional queued items.

### `_explode`

() private

Defined in `loader/js/loader.js:1836`

Inspects the required modules list looking for additional dependencies. Expands the required list to include all required modules. Called by calculate()

### `_explodeRollups`

() private

Defined in `loader/js/loader.js:1305`

Grab all the items that were asked for, check to see if the Loader meta-data contains a "use" array. If it doesm remove the asked item and replace it with the content of the "use". This will make asking for: "dd" Actually ask for: "dd-ddm-base,dd-ddm,dd-ddm-drop,dd-drag,dd-proxy,dd-constrain,dd-drop,dd-scroll,dd-drop-plugin"

### `_filter`

(

- `u`
- `name`

)
String private

Defined in `loader/js/loader.js:2436`

Apply filter defined for this instance to a url/path

#### Parameters:

- `u` String

  the string to filter.

- `name` String

  the name of the module, if we are processing a single module as opposed to a combined url.

#### Returns:

String: the filtered string.

### `_finish`

(

- `msg`
- `success`

)
private

Defined in `loader/js/loader.js:1997`

Handles the queue when a module has been loaded for all cases

#### Parameters:

- `msg` String

  The message from Loader

- `success` Boolean

  A boolean denoting success or failure

### `_insert`

(

- `source`
- `o`
- `type`
- `[skipcalc=false]`

)
private

Defined in `loader/js/loader.js:2202`

Handles the actual insertion of script/link tags

#### Parameters:

- `source` Object

  The YUI instance the request came from

- `o` Object

  The metadata to include

- `type` String

  JS or CSS

- `[skipcalc=false]` Boolean optional

  Do a Loader.calculate on the meta

### `_onFailure`

() private

Defined in `loader/js/loader.js:2083`

The default Loader onFailure handler, calls this.onFailure with a payload

### `_onProgress`

() private

Defined in `loader/js/loader.js:2063`

The default Loader onProgress handler, calls this.onProgress with a payload

### `_onSuccess`

() private

Defined in `loader/js/loader.js:2020`

The default Loader onSuccess handler, calls this.onSuccess with a payload

### `_onTimeout`

(

- `transaction`

)
private

Defined in `loader/js/loader.js:2111`

The default Loader onTimeout handler, calls this.onTimeout with a payload

#### Parameters:

- `transaction` Get.Transaction

  The Transaction object from `Y.Get`

### `_patternTest`

(

- `mname`
- `pname`

)
private

Defined in `loader/js/loader.js:1877`

The default method used to test a module against a pattern

#### Parameters:

- `mname` String

  The module being tested

- `pname` String

  The pattern to match

### `_populateCache`

() private

Defined in `loader/js/loader.js:520`

Checks the cache for modules and conditions, if they do not exist process the default metadata and populate the local moduleInfo hash.

### `_reduce`

() Object private

Defined in `loader/js/loader.js:1957`

Remove superceded modules and loaded modules. Called by calculate() after we have the mega list of all dependencies

#### Returns:

Object: the reduced dependency hash.

### `_resetModules`

() private

Defined in `loader/js/loader.js:555`

Reset modules in the module cache to a pre-processed state so additional computations with a different skin or language will work as expected.

### `_rollup`

() private

Provided by the rollup module.

Defined in `loader/js/rollup.js:8`

Look for rollup packages to determine if all of the modules a rollup supersedes are required. If so, include the rollup to help reduce the total number of connections required. Called by calculate(). This is an optional feature, and requires the appropriate submodule to function.

### `_setup`

() private

Defined in `loader/js/loader.js:1758`

Investigates the current YUI configuration on the page. By default, modules already detected will not be loaded again unless a force option is encountered. Called by calculate()

### `_sort`

() private

Defined in `loader/js/loader.js:2130`

Sorts the dependency tree. The last step of calculate()

### `_url`

(

- `path`
- `name`
- `[base=self.base]`

)
String private

Defined in `loader/js/loader.js:2467`

Generates the full url for a module

#### Parameters:

- `path` String

  the path fragment.

- `name` String

  The name of the module

- `[base=self.base]` String optional

  The base url to use

#### Returns:

String: the full url.

### `addAlias`

(

- `use`
- `name`

)

Defined in `loader/js/loader.js:903`

Adds an alias module to the system

#### Parameters:

- `use` Array

  An array of modules that makes up this alias

- `name` String

  The name of the alias

#### Example:

      var loader = new Y.Loader({});
      loader.addAlias([ 'node', 'yql' ], 'davglass');
      loader.require(['davglass']);
      var out = loader.resolve(true);

      //out.js will contain Node and YQL modules

### `addGroup`

(

- `config`
- `name`

)

Defined in `loader/js/loader.js:923`

Add a new module group

#### Parameters:

- `config` Object

  An object containing the group configuration data

  - `name` String

    required, the group name

  - `base` String

    The base directory for this module group

  - `root` String

    The root path to add to each combo resource path

  - `combine` Boolean

    Should the request be combined

  - `comboBase` String

    Combo service base path

  - `modules` Object

    The group of modules

- `name` String

  the group name.

#### Example:

     var loader = new Y.Loader({});
     loader.addGroup({
         name: 'davglass',
         combine: true,
         comboBase: '/combo?',
         root: '',
         modules: {
             //Module List here
         }
     }, 'davglass');

### `addModule`

(

- `config`
- `[name]`

)
Object

Defined in `loader/js/loader.js:977`

Add a new module to the component metadata.

#### Parameters:

- `config` Object

  An object containing the module data.

  - `name` String

    Required, the component name

  - `type` String

    Required, the component type (js or css)

  - `path` String

    Required, the path to the script from `base`

  - `requires` Array

    Array of modules required by this component

  - `[optional]` Array optional

    Array of optional modules for this component

  - `[supersedes]` Array optional

    Array of the modules this component replaces

  - `[after]` Array optional

    Array of modules the components which, if present, should be sorted above this one

  - `[after_map]` Object optional

    Faster alternative to 'after' -- supply a hash instead of an array

  - `[rollup]` Number optional

    The number of superseded modules required for automatic rollup

  - `[fullpath]` String optional

    If `fullpath` is specified, this is used instead of the configured `base + path`

  - `[skinnable]` Boolean optional

    Flag to determine if skin assets should automatically be pulled in

  - `[submodules]` Object optional

    Hash of submodules

  - `[group]` String optional

    The group the module belongs to -- this is set automatically when it is added as part of a group configuration.

  - `[lang]` Array optional

    Array of BCP 47 language tags of languages for which this module has localized resource bundles, e.g., `["en-GB", "zh-Hans-CN"]`

  - `[condition]` Object optional

    Specifies that the module should be loaded automatically if a condition is met. This is an object with up to four fields:

    - `[trigger]` String optional
      The name of a module that can trigger the auto-load
    - `[test]` Function optional
      A function that returns true when the module is to be loaded.
    - `[ua]` String optional
      The UA name of Y.UA object that returns true when the module is to be loaded. e.g., `"ie"`, `"nodejs"`.
    - `[when]` String optional
      Specifies the load order of the conditional module with regard to the position of the trigger module. This should be one of three values: `before`, `after`, or `instead`. The default is `after`.
  - `[testresults]` Object optional

    A hash of test results from `Y.Features.all()`

  - `[configFn]` Function optional

    A function to exectute when configuring this module

    - `mod` Object
      The module config, modifying this object will modify it's config. Returning false will delete the module's config.
- `[name]` String optional

  The module name, required if not in the module data.

#### Returns:

Object: the module definition or null if the object passed in did not provide all required attributes.

### `calculate`

(

- `o`
- `type`

)

Defined in `loader/js/loader.js:1680`

Calculates the dependency tree, the result is stored in the sorted property.

#### Parameters:

- `o` Object

  optional options object.

- `type` String

  optional argument to prune modules.

### `filterRequires`

(

- `r`

)
Array

Defined in `loader/js/loader.js:1342`

Explodes the required array to remove aliases and replace them with real modules

#### Parameters:

- `r` Array

  The original requires array

#### Returns:

Array: The new array of exploded requirements

### `formatSkin`

(

- `skin`
- `mod`

)
String

Defined in `loader/js/loader.js:839`

Returns the skin module name for the specified skin name. If a module name is supplied, the returned skin module name is specific to the module passed in.

#### Parameters:

- `skin` String

  the name of the skin.

- `mod` String

  optional: the name of a module to skin.

#### Returns:

String: the full skin module name.

### `getLangPackName`

(

- `lang`
- `mname`

)
String

Defined in `loader/js/loader.js:1826`

Builds a module name for a language pack

#### Parameters:

- `lang` String

  the language code.

- `mname` String

  the module to build it for.

#### Returns:

String: the language pack module name.

### `getModule`

(

- `mname`

)
Object

Defined in `loader/js/loader.js:1887`

Get's the loader meta data for the requested module

#### Parameters:

- `mname` String

  The module name to get

#### Returns:

Object: The module metadata

### `getProvides`

(

- `name`

)
Object

Defined in `loader/js/loader.js:1648`

Returns a hash of module names the supplied module satisfies.

#### Parameters:

- `name` String

  The name of the module.

#### Returns:

Object: what this module provides.

### `getRequires`

(

- `mod`

)
Array

Defined in `loader/js/loader.js:1376`

Returns an object containing properties for all modules required in order to load the requested module

#### Parameters:

- `mod` Object

  The module definition from moduleInfo.

#### Returns:

Array: the expanded requirement list.

### `insert`

(

- `o`
- `type`

)

Defined in `loader/js/loader.js:2400`

inserts the requested modules and their dependencies. `type` can be "js" or "css". Both script and css are inserted if type is not provided.

#### Parameters:

- `o` Object

  optional options object.

- `type` String

  the type of dependency to insert.

### `isCSSLoaded`

(

- `name`

)

Defined in `loader/js/loader.js:1605`

Check to see if named css module is already loaded on the page

#### Parameters:

- `name` String

  The name of the css file

#### Returns:

Boolean

### `load`

(

- `cb`

)

Defined in `loader/js/loader.js:2680`

Shortcut to calculate, resolve and load all modules.

    var loader = new Y.Loader({
        ignoreRegistered: true,
        modules: {
            mod: {
                path: 'mod.js'
            }
        },
        requires: [ 'mod' ]
    });
    loader.load(function() {
        console.log('All modules have loaded..');
    });

#### Parameters:

- `cb` Callback

  Executed after all load operations are complete

### `loadNext`

(

- `mname`

)
deprecated

Defined in `loader/js/loader.js:2420`

Executed every time a module is loaded, and if we are in a load cycle, we attempt to load the next script. Public so that it is possible to call this if using a method other than Y.register to determine when scripts are fully loaded

#### Parameters:

- `mname` String

  optional the name of the module that has been loaded (which is usually why it is time to load the next one).

### `onCSS`

()

Defined in `loader/js/loader.js:138`

Callback for the 'CSSComplete' event. When loading YUI components with CSS the CSS is loaded first, then the script. This provides a moment you can tie into to improve the presentation of the page while the script is loading.

### `onFailure`

()

Defined in `loader/js/loader.js:131`

Callback that will be executed if there is a failure

### `onProgress`

()

Defined in `loader/js/loader.js:148`

Callback executed each time a script or css file is loaded

### `onSuccess`

()

Defined in `loader/js/loader.js:123`

Callback that will be executed when the loader is finished with an insert

### `onTimeout`

()

Defined in `loader/js/loader.js:155`

Callback that will be executed if a timeout occurs

### `require`

(

- `what`

)

Defined in `loader/js/loader.js:1293`

Add a requirement for one or more module

#### Parameters:

- `what` String[] | string

  the modules to load.

### `resolve`

(

- `[calc=false]`
- `[s=loader.sorted]`

)
Object

Defined in `loader/js/loader.js:2479`

Returns an Object hash of file arrays built from `loader.sorted` or from an arbitrary list of sorted modules.

#### Parameters:

- `[calc=false]` Boolean optional

  Perform a loader.calculate() before anything else

- `[s=loader.sorted]` Array optional

  An override for the loader.sorted array

#### Returns:

Object: Object hash (js and css) of two arrays of file lists

#### Example:

This method can be used as an off-line dep calculator

       var Y = YUI();
       var loader = new Y.Loader({
           filter: 'debug',
           base: '../../',
           root: 'build/',
           combine: true,
           require: ['node', 'dd', 'console']
       });
       var out = loader.resolve(true);

## Properties

### `_internalCallback`

Unknown private

Defined in `loader/js/loader.js:115`

Internal callback to handle multiple internal insert() calls so that css is inserted prior to js

### `allowRollup`

Boolean

Defined in `loader/js/loader.js:299`

Should we allow rollups

Default: false

### `async`

Unknown

Defined in `loader/js/loader.js:426`

Should Loader fetch scripts in `async`, defaults to `true`

### `base`

String

Defined in `loader/js/loader.js:204`

The base directory.

Default: http://yui.yahooapis.com/[YUI VERSION]/build/

### `charset`

String deprecated

Defined in `loader/js/loader.js:182`

Deprecated: , use cssAttributes or jsAttributes.

The charset attribute for inserted nodes

### `combine`

Boolean

Defined in `loader/js/loader.js:226`

If configured, the loader will attempt to use the combo service for YUI resources and configured external resources.

Default: true if a base dir isn't in the config

### `comboBase`

String

Defined in `loader/js/loader.js:212`

Base path for the combo service

Default: http://yui.yahooapis.com/combo?

### `comboSep`

String

Defined in `loader/js/loader.js:236`

The default seperator to use between files in a combo URL

Default: Ampersand

### `context`

Unknown

Defined in `loader/js/loader.js:162`

The execution context for all callbacks

Default: {YUI} the YUI instance

### `cssAttributes`

Object

Defined in `loader/js/loader.js:190`

An object literal containing attributes to add to link nodes

### `data`

Unknown

Defined in `loader/js/loader.js:169`

Data that is passed to all callbacks

### `dirty`

Boolean

Defined in `loader/js/loader.js:478`

Flag to indicate the dependency tree needs to be recomputed if insert is called again.

Default: true

### `filter`

String | searchExp: string, replaceStr: string

Defined in `loader/js/loader.js:307`

A filter to apply to result urls. This filter will modify the default path for all modules. The default path for the YUI library is the minified version of the files (e.g., event-min.js). The filter property can be a predefined filter or a custom filter. The valid predefined filters are:

DEBUG
  Selects the debug versions of the library (e.g., event-debug.js). This option will automatically include the Logger widget
RAW
  Selects the non-minified version of the library (e.g., event.js).

You can also define a custom filter, which must be an object literal containing a search expression and a replace string:

     myFilter: {
         'searchExp': "-min\\.js",
         'replaceStr': "-debug.js"
     }

### `FILTER_DEFS`

Object protected final

Defined in `loader/js/loader.js:606`

Default filters for raw and debug

### `filters`

Object

Defined in `loader/js/loader.js:334`

per-component filter specification. If specified for a given component, this overrides the filter config.

### `force`

String[]

Defined in `loader/js/loader.js:289`

A list of modules that should always be loaded, even if they have already been inserted into the page.

### `ignore`

String[]

Defined in `loader/js/loader.js:281`

A list of modules that should not be loaded, even if they turn up in the dependency tree

### `ignoreRegistered`

Unknown

Defined in `loader/js/loader.js:256`

Ignore modules registered on the YUI global

Default: false

### `insertBefore`

String | HTMLElement

Defined in `loader/js/loader.js:175`

Node reference or id where new nodes should be inserted before

### `inserted`

String: boolean

Defined in `loader/js/loader.js:487`

List of modules inserted by the utility

### `jsAttributes`

Object

Defined in `loader/js/loader.js:197`

An object literal containing attributes to add to script nodes

### `loaded`

String: boolean

Defined in `loader/js/loader.js:415`

Set when beginning to compute the dependency tree. Composed of what YUI reports to be loaded combined with what has been loaded by any instance on the page with the version number specified in the metadata.

### `loadOptional`

Boolean

Defined in `loader/js/loader.js:453`

Whether or not to load optional dependencies for the requested modules

Default: false

### `maxURLLength`

Int

Defined in `loader/js/loader.js:243`

Max url length for combo urls. The default is 1024. This is the URL limit for the Yahoo! hosted combo servers. If consuming a different combo service that has a different URL limit it is possible to override this default by supplying the maxURLLength config option. The config option will only take effect if lower than the default.

### `moduleInfo`

Unknown

Defined in `loader/js/loader.js:362`

The library metadata

### `patterns`

Object

Defined in `loader/js/loader.js:349`

If a module name is predefined when requested, it is checked againsts the patterns provided in this property. If there is a match, the module is added with the default configuration.

At the moment only supporting module prefixes, but anticipate supporting at least regular expressions.

### `REGEX_CSS`

RegExp protected final

Defined in `loader/js/loader.js:594`

Available since 3.5.0

Regex that matches a CSS URL. Used to guess the file type when it's not specified.

### `required`

String: boolean

Defined in `loader/js/loader.js:342`

The list of requested modules

### `rollups`

Unknown

Defined in `loader/js/loader.js:447`

List of rollup files found in the library metadata

### `root`

String

Defined in `loader/js/loader.js:263`

Root path to prepend to module path for the combo service

Default: [YUI VERSION]/build/

### `skin`

Object

Defined in `loader/js/loader.js:371`

Provides the information used to skin the skinnable components. The following skin definition would result in 'skin1' and 'skin2' being loaded for calendar (if calendar was requested), and 'sam' for all other skinnable components:

     skin: {
         // The default skin, which is automatically applied if not
         // overriden by a component-specific skin definition.
         // Change this in to apply a different skin globally
         defaultSkin: 'sam',

         // This is combined with the loader base property to get
         // the default root directory for a skin. ex:
         // http://yui.yahooapis.com/2.3.0/build/assets/skins/sam/
         base: 'assets/skins/',

         // Any component-specific overrides can be specified here,
         // making it possible to load different skins for different
         // components.  It is possible to load more than one skin
         // for a given component as well.
         overrides: {
             calendar: ['skin1', 'skin2']
         }
     }

### `skipped`

Unknown

Defined in `loader/js/loader.js:494`

List of skipped modules during insert() because the module was not defined

### `sorted`

String[]

Defined in `loader/js/loader.js:462`

All of the derived dependencies in sorted order, which will be populated when either calculate() or insert() is called

### `timeout`

Int

Defined in `loader/js/loader.js:272`

Timeout value in milliseconds. If set, self value will be used by the get utility. the timeout event will fire if a timeout occurs.