#

Jump to Table of Contents

# YUI Loader

Loader dynamically loads script and css files for YUI modules as well as external modules. It includes the dependency infomation 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 as well as local combo servers.

## Configuration Options

The valid configuration options for Loader are as follows:

- `lang`: The list of preferred languages, as BCP 47 language tags, in order of preference. The loader uses this list to determine the best language to use for modules with language sensitive behavior and to load the necessary resource bundles. See the Internationalization module for more information.
- `base`: The base dir
- `comboBase`: The YUI combo service base dir. Ex: http://yui.yahooapis.com/combo?
- `maxURLLength`: The maximum URL length a combo url should be before it's chopped into a separate request.
- `comboSep`: The separator to use to build the combo request (defaults to &)
- `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).
  - `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"
              }

- `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
- `jsAttributes`: attributes to apply to dynamic script nodes
- `cssAttributes`: attributes to apply to dynamic link nodes
- `timeout`: number of milliseconds before a timeout occurs when dynamically loading nodes. in not set, there is no timeout
- `context`: execution context for all callbacks
- `modules`: A list of module definitions. The valid module configuration data is as follows:
  - `name`: required, the component name
  - `type`: required, the component type (js or css)
  - `path`: required if fullpath is not specified, the path to the script from "base"
  - `fullpath`: required if path isn't specified, the full path to the script. "base" will not be used to build the url
  - `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
  - `rollup`: the number of superseded modules required for automatic rollup
  - `lang`: array of BCP 47 language tags of languages for which this module has localized resource bundles
  - `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`.
- `groups`: in 3.1.0, the groups config was added as an enhancement over the 'modules' config. Each group can override the `base`, `comboBase`, `root`, `combine`, `maxURLLength`, `comboSep` and `modules` configs listed above. These values are used for all of the modules listed in the group

## Using Loader on Node.js

Loader can be used on Node.js for offline dependency calculations as well as dynamic file serving.

    var loader = new Y.Loader({
        //Don't combine the files
        combine: false,
        //Ignore things that are already loaded (in this process)
        ignoreRegistered: true,
        //Set the base path
        base: 'build/'
        //And the root
        root: __dirname,
        //Require your deps
        require: [ 'node', 'yql' ]
    });

    var out = loader.resolve(true);

    //This will be an object of js and css files needed to complete this request.
    console.log(out);

### Custom Modules

You can also use custom YUI modules as well as core YUI modules:

    var loader = new Y.Loader({
        modules: {
            foo: {
                fullpath: path.join(__dirname, './foo.js')
            }
        },
        require: ['foo']
    });

### External Modules

And you can even use external modules:

    #!/usr/bin/env node

    var Y = require('./yui-min').YUI();

    var loader = new Y.Loader({
        base: __dirname,
        modules: {
            jquery: {
                path: '/vendor/jquery.js'
            },
            backbone: {
                path: '/vendor/backbone.js',
                requires: [ 'jquery' ]
            }
        }
    });

    loader.require('backbone');

    var out = loader.resolve(true);

    console.log(out);

    /*
    {
        js:
          [ '/Users/davglass/src/loader/vendor/jquery.js',
            '/Users/davglass/src/loader/vendor/backbone.js' ],
        css: []
    }
    */

Using this approach, you can build CLI tools to concat files for deployment or even use query string parameters passed to a web app to return the content.

## Example config

    YUI({
           lang: 'ko-KR,en-GB,zh-Hant-TW', // languages in order of preference
           base: '../../build/', // the base path to the YUI install.  Usually not needed because the default is the same base path as the yui.js include file
           charset: 'utf-8', // specify a charset for inserted nodes, default is utf-8
           loadOptional: true, // automatically load optional dependencies, default false
           combine: true, // use the Yahoo! CDN combo service for YUI resources, default is true unless 'base' has been changed
           filter: 'raw', // apply a filter to load the raw or debug version of YUI files
           timeout: 10000, // specify the amount of time to wait for a node to finish loading before aborting
           insertBefore: 'customstyles', // The insertion point for new nodes
           // one or more external modules that can be loaded along side of YUI.  This is the only pattern
           // that was supported in 3.0.0 for declaring external modules.  3.1.0 adds 'groups' support,
           // which is an easier way to define a group of modules.  See below.
           modules:  {
               yui2_yde_datasource: {
                   fullpath: 'http://yui.yahooapis.com/combo?2.7.0/build/yahoo-dom-event/yahoo-dom-event.js&2.7.0/build/datasource/datasource-min.js'
               },
               yui_flot: {
                   fullpath: 'http://bluesmoon.github.com/yui-flot/yui.flot.js',
                   requires: ['yui2_yde_datasource']
               }
           },

           // one or more groups of modules which share the same base path and
           // combo service specification.
           groups: {
               // Note, while this is a valid way to load YUI2, 3.1.0 has intrinsic
               // YUI 2 loading built in.  See the examples to learn how to use
               // this feature.
               yui2: {
                   combine: true,
                   base: 'http://yui.yahooapis.com/2.8.0r4/build/',
                   comboBase: 'http://yui.yahooapis.com/combo?',
                   root: '2.8.0r4/build/',
                   modules:  { // one or more external modules that can be loaded along side of YUI
                       yui2_yde: {
                           path: "yahoo-dom-event/yahoo-dom-event.js"
                       },
                       yui2_anim: {
                           path: "animation/animation.js",
                           requires: ['yui2_yde']
                       }
                   }
               }
           }
    }).use('dd', 'yui_flot', function(Y) {
        // All YUI modules required to get drag and drop to work are now loaded.
    });