Yahoo! UI Library

loader  3.3.0

Yahoo! UI Library > loader > Loader
Search:
 
Filters

Class Loader

See also: YUI.use for the normal use case. The use function automatically will pull in missing dependencies.
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 supports rollup files and will automatically use these when appropriate in order to minimize the number of http connections required to load all of the dependencies. 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. While the loader can be instantiated by the end user, it normally is not.

Constructor

Loader ( o )
Parameters:
o <object> an optional set of configuration options. Valid options:
  • base: The base dir
  • comboBase: The YUI combo service base dir. Ex: http://yui.yahooapis.com/combo?
  • root: The root path to prepend to module names for the combo service. Ex: 2.5.2/build/
  • filter:. 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"
}
  • filters: per-component filter specification. If specified for a given component, this overrides the filter config
  • combine: Use the YUI combo service to reduce the number of http connections required to load your dependencies
  • ignore: A list of modules that should never be dynamically loaded
  • force: A list of modules that should always be loaded when required, even if already present on the page
  • insertBefore: Node or id for a node that should be used as the insertion point for new nodes
  • charset: charset for dynamic nodes (deprecated, use jsAttributes or cssAttributes)
  • jsAttributes: object literal containing attributes to add to script nodes
  • cssAttributes: object literal containing attributes to add to link nodes
  • timeout: The number of milliseconds before a timeout occurs when dynamically loading nodes. If not set, there is no timeout
  • context: execution context for all callbacks
  • onSuccess: callback for the 'success' event
  • onFailure: callback for the 'failure' event
  • 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.
  • onTimeout: callback for the 'timeout' event
  • onProgress: callback executed each time a script or css file is loaded
  • modules: A list of module definitions. See Loader.addModule for the supported module metadata
  • groups: A list of group definitions. Each group can contain specific definitions for base, comboBase, combine, and accepts a list of modules. See above for the description of these properties.
  • 2in3: 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: 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, and 2.8.1 [default] -- plus all versions of YUI 2 going forward.

Properties

_internalCallback - private object

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

allowRollup - boolean

Should we allow rollups
Default Value: true

base - string

The base directory.
Default Value: http://yui.yahooapis.com/[YUI VERSION]/build/

charset - string

The charset attribute for inserted nodes
Deprecated: , use cssAttributes or jsAttributes.

combine - boolean

If configured, the loader will attempt to use the combo service for YUI resources and configured external resources.
Default Value: true if a base dir isn't in the config

comboBase - string

Base path for the combo service
Default Value: http://yui.yahooapis.com/combo?

context - object

The execution context for all callbacks
Default Value: {YUI} the YUI instance

cssAttributes - object

An object literal containing attributes to add to link nodes

data - object

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 Value: 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"
}

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 - object

Ignore modules registered on the YUI global
Default Value: 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 Value: false

maxURLLength - int

Max url length for combo urls. The default is 2048 for internet explorer, and 8192 otherwise. 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. Browsers: IE: 2048 Other A-Grade Browsers: Higher that what is typically supported 'capable' mobile browsers: Servers: Apache: 8192

moduleInfo - object

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.

required - {string: boolean}

The list of requested modules

rollups - object

List of rollup files found in the library metadata

root - string

Root path to prepend to module path for the combo service
Default Value: [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 - object

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.

Methods

_addSkin

private string _addSkin ( skin , mod , parent )
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.

_explode

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

_filter

private string _filter ( u , name )
Apply filter defined for this instance to a url/path method _filter
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.

_reduce

private object _reduce ( )
Remove superceded modules and loaded modules. Called by calculate() after we have the mega list of all dependencies
Returns: object
the reduced dependency hash.

_rollup

private void _rollup ( )
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 void _setup ( )
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 void _sort ( )
Sorts the dependency tree. The last step of calculate()

_url

private string _url ( path )
Generates the full url for a module method _url
Parameters:
path <string> the path fragment.
Returns: string
the full url.

addGroup

void addGroup ( o , name )
Add a new module group
name:
required, the group name
base:
The base dir for this module group
root:
The root path to add to each combo resource path
combine:
combo handle
comboBase:
combo service base path
modules:
the group of modules
Parameters:
o <object> An object containing the module data.
name <string> the group name.

addModule

object addModule ( o , name )
Add a new module to the component metadata.
name:
required, the component name
type:
required, the component type (js or css)
path:
required, the path to the script from "base"
requires:
array of modules required by this component
optional:
array of optional modules for this component
supersedes:
array of the modules this component replaces
after:
array of modules the components which, if present, should be sorted above this one
after_map:
faster alternative to 'after' -- supply a hash instead of an array
rollup:
the number of superseded modules required for automatic rollup
fullpath:
If fullpath is specified, this is used instead of the configured base + path
skinnable:
flag to determine if skin assets should automatically be pulled in
submodules:
a hash of submodules
group:
The group the module belongs to -- this is set automatically when it is added as part of a group configuration.
lang:
array of BCP 47 language tags of languages for which this module has localized resource bundles, e.g., ["en-GB","zh-Hans-CN"]
condition:
Specifies that the module should be loaded automatically if a condition is met. This is an object with up to three fields: [trigger] - the name of a module that can trigger the auto-load [test] - a function that returns true when the module is to be loaded. [when] - 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'.
Parameters:
o <object> An object containing the module data.
name <string> the module name (optional), 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

void 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.

formatSkin

string formatSkin ( skin , mod )
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

string getLangPackName ( lang , mname )
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.

getProvides

object getProvides ( name )
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

array getRequires ( mod )
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

void 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.

loadNext

void loadNext ( mname )
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

void 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

void onFailure ( )
Callback that will be executed if there is a failure

onProgress

void onProgress ( )
Callback executed each time a script or css file is loaded

onSuccess

void onSuccess ( )
Callback that will be executed when the loader is finished with an insert

onTimeout

void onTimeout ( )
Callback that will be executed if a timeout occurs

require

void require ( what )
Add a requirement for one or more module
Parameters:
what <string[] | string*> the modules to load.

Classes

Copyright © 2011 Yahoo! Inc. All rights reserved.