API Docs for: 3.8.0
Show:

Loader Class

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
)

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.

Methods

_addLangPack

(
  • lang
  • m
  • packName
)
Object private

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

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

Apply a new config to the Loader instance

Parameters:

  • o Object

    The new configuration

_continue

() private

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

_explode

() private

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

_explodeRollups

() private

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

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

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

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

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

_onProgress

() private

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

_onSuccess

() private

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

_onTimeout

() private

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

_patternTest

(
  • mname
  • pname
)
private

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

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

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

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

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

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

_url

(
  • path
  • name
  • [base=self.base]
)
String private

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
)

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
)

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

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 three 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.
      • [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
)

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

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

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

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

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

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

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
)

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
)

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
)

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

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

()

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

()

Callback that will be executed if there is a failure

onProgress

()

Callback executed each time a script or css file is loaded

onSuccess

()

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

onTimeout

()

Callback that will be executed if a timeout occurs

require

(
  • what
)

Add a requirement for one or more module

Parameters:

  • what String[] | string

    the modules to load.

resolve

(
  • [calc=false]
  • [s=loader.sorted]
)
Object

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

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

allowRollup

Boolean

Should we allow rollups

Default: false

async

Unknown

Should Loader fetch scripts in async, defaults to true

base

String

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

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

Base path for the combo service

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

comboSep

String

The default seperator to use between files in a combo URL

Default: Ampersand

context

Unknown

The execution context for all callbacks

Default: {YUI} the YUI instance

cssAttributes

Object

An object literal containing attributes to add to link nodes

data

Unknown

Data that is passed to all callbacks

dirty

Boolean

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

Default: true

filter

String | searchExp: string, replaceStr: string

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

Default filters for raw and debug

filters

Object

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

force

String[]

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

ignore

String[]

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

ignoreRegistered

Unknown

Ignore modules registered on the YUI global

Default: false

insertBefore

String | HTMLElement

Node reference or id where new nodes should be inserted before

inserted

String: boolean

List of modules inserted by the utility

jsAttributes

Object

An object literal containing attributes to add to script nodes

loaded

String: boolean

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

Whether or not to load optional dependencies for the requested modules

Default: false

maxURLLength

Int

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

The library metadata

patterns

Object

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

The list of requested modules

rollups

Unknown

List of rollup files found in the library metadata

root

String

Root path to prepend to module path for the combo service

Default: [YUI VERSION]/build/

skin

Object

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

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

sorted

String[]

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

timeout

Int

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