0N/A<div class="intro">

553N/A <p>The YUI module is the single core dependency for all YUI 3.x implementations. It must be included on all pages that use YUI &mdash; and it is the only dependency required to start writing YUI code. The YUI module contains loader functionality and a dependency calculator, allowing it to serve as a "seed" for your implementation. You provide the YUI module list you're using and the code that makes use of those modules; YUI will fetch all necessary components in a single, optimized HTTP request before executing your dependent code. While you may use some of the script- and CSS-loading facilities of the YUI module in your own implementation, this module's core purpose is to serve as a small seed from which complex, highly modular implementations can grow.</p>

0N/A <p>The YUI module creates a global YUI object. This object is instantiable, and it is used to create YUI instances to which are bound specific functional modules. A page can share a single YUI instance or can use different, insular instances for each piece of functionality on the page.</p>

0N/A</div>

0N/A

0N/A

0N/A<p>The YUI Global object is provided by one of our seed files:</p>

0N/A

0N/A<h2 id="loader-seed">The Loader Seed</h2>

0N/A```

0N/A<script src="http://yui.yahooapis.com/{{{yuiVersion}}}/build/yui/yui-min.js"></script>

0N/A```

0N/A

0N/A<p>This seed file contains everything you need to fetch/use YUI core modules. It includes our dynamic script loader as well as all of the meta-data required to load additional YUI modules.</p>

0N/A

0N/A

0N/A<h2 id="base-seed">The Base Seed</h2>

0N/A```

553N/A<script src="http://yui.yahooapis.com/{{{yuiVersion}}}/build/yui-base/yui-base-min.js"></script>

553N/A```

553N/A

0N/A<p>This seed file contains the core items you need to use YUI core modules. It also includes the capability to fetch our dynamic script loader. <em>This seed was our old `yui.js`</em></p>

0N/A

0N/A<h2 id="why">Why the namespace change?</h2>

0N/A<ol>

0N/A <li><strong>Backward Compatibility</strong>: With the change from <code>YAHOO</code> to <code>YUI</code> we are guaranteed not to break backward compatibility. This allows you to use both YUI 2.x and YUI 3.x on

0N/A the same page without fear of breaking existing code.</li>

0N/A <li><strong>Sandboxing</strong>: The new YUI Global Object is now smarter than ever, allowing you to create an instance of YUI in your own namespace and only load the modules that you need.

0N/A It makes it easier for multiple developers to work on different parts of the page with different modules with less worry of them stepping on each other's toes.</li>

0N/A <li><strong>Versioning</strong>: If another version of YUI is loaded on the page, it will not change objects used in

0N/A existing YUI instances. Both versions of YUI will operate with the corresponding versions of the reqested YUI modules without impacting each other.</li>

0N/A

0N/A

0N/A

0N/A <li><strong>More Dynamic</strong>: With Loader built into the core, loading files when you need them just got easier.</li>

0N/A <li><strong>Selector Powered</strong>: Using Selector as its base for node handling, you now get more power and ease of use for free.</li>

0N/A <li><strong>Event Normalization</strong>: With the new Event Facade, you get maximum event normalization for cleaner cross browser code.</li>

0N/A</ol>

0N/A

0N/A

0N/A<h2 id="core">YUI Core</h2>

0N/A<p>The YUI Global Object is an instantiatable object that allows you to create as many YUI instances as you need. Each completely configurable and loaded with only the modules that you need.</p>

0N/A

```

YUI().use('node', function(Y) {

Y.one('#demo');

});

```

<p>All of this functionality is available in the YUI Core:</p>

<table>

<thead>

<tr>

<th>YUI 3 Component</th>

<th>Module</th>

</tr>

</thead>

<tbody>

<tr>

<td>Array Operations</td><td>array</td>

</tr>

<tr>

<td>YUI Core</td><td>core</td>

</tr>

<tr>

<td>JavaScript language helper methods</td><td>lang</td>

</tr>

<tr>

<td>Periodic execution method</td><td>later</td>

</tr>

<tr>

<td>Logging support</td><td>log</td>

</tr>

<tr>

<td>Object Operations</td><td>object</td>

</tr>

<tr>

<td>Browser Sniffing</td><td>ua</td>

</tr>

<tr>

<td>YUI Object</td><td>yui</td>

</tr>

<tr>

<td>Dynamic script and css loading</td><td>get</td>

</tr>

<tr>

<td>YUI Loader</td><td>loader</td>

</tr>

</tbody>

</table>

<h2 id="use">Use method</h2>

<p>The `use` method allows you to choose the modules that you want loaded into your YUI instance. You can pick and choose what you need, you don't have to load everything that was included on the page.</p>

```

YUI().use('dd-drop', 'anim', function(Y) {

// Y.DD is available

// Y.Anim is available

});

YUI().use('anim', function(Y) {

// Y.DD is NOT available

// Y.Anim is available

});

```

<h2>Use callback</h2>

<p>You can pass a function in as the last argument to <code>use</code>. This function will execute after the YUI instance loads all the modules.

This is required if you do not have all dependencies on the page.</p>

<p>The callback method has one argument passed, the YUI instance that we are dealing with. In this function you know that all the modules have been loaded and it's ok to use them.</p>

```

YUI().use('animation', function(Y) {

// Y.Anim is available

});

```

<h2>Use shorthand</h2>

<p>The <code>use</code> method contains a shorthand reference for all modules on the page. It uses the <code>*</code> as the module name.</p>

<p>This will load every module that is included on the page.</p>

```

YUI().use('*', function(Y) {

// Implementation code

});

```

<h2>Static inclusion vs. dynamic loading</h2>

<p>YUI automatically tries to complete itself when missing dependencies are detected.

When dynamically loading the dependencies, the callback passed to <code>use</code>

will be executed <em>asynchronously</em>. If you statically include all of the

library requirements (or all were previously loaded by another means), the

use() callback will execute synchronously. The purpose of the callback is so

that it doesn't matter to the implementation whether the operation was synchronous

or not. Code immediately following the <code>use</code> statement will not have

access to any of the requested modules if anything has to be dynamically loaded.

You can prevent YUI from automatically trying to obtain missing dependencies by setting the

YUI config <code>bootstrap</code> to false.</p>

<h2 id="modulelist">Module List</h2>

<p>Here is a partial list of the modules and their descriptions.</p>

<table>

<thead>

<tr>

<th>YUI 3 Component</th>

<th>Module</th>

</tr>

</thead>

<tbody>

<tr>

<td>Animation</td><td>anim</td>

</tr>

<tr>

<td>Attribute Engine</td><td>attribute</td>

</tr>

<tr>

<td>Class Builder</td><td>base</td>

</tr>

<tr>

<td>Collection Utilities</td><td>collection</td>

</tr>

<tr>

<td>Drag &amp; Drop</td><td>dd</td>

</tr>

<tr>

<td>DOM Element Utilites</td><td>dom</td>

</tr>

<tr>

<td>DOM Event Utilities</td><td>event</td>

</tr>

<tr>

<td>Custom Event Engine</td><td>event-custom</td>

</tr>

<tr>

<td>IO (XHR/XDR)</td><td>io</td>

</tr>

<tr>

<td>JSON</td><td>json</td>

</tr>

<tr>

<td>HTML Element Wrapper</td><td>node</td>

</tr>

<tr>

<td>Support for non-blocking iterative operations</td><td>async-queue</td>

</tr>

</tbody>

</table>

<h2 id="yuiadd">Creating Custom Modules with YUI.add</h2>

<p><code>YUI.add</code> is a static global method that is

the single entry point for first class YUI modules. This method

registers the module so that it can attached to a YUI instance

via the <code>use</code> method. Modules registered this way

are dynamically attached during the <code>use</code> phase, so

they can be fully protected by the YUI sandbox.</p>

<p>During the <code>use</code> phase, the function passed to

<code>YUI.add</code> is executed. It receives the YUI instance

as a parameter, and this can be used to add functionality to

the instance.</p>

<p>While you can add the module wrapper to your code yourself,

the <a href="http://yuilibrary.com/projects/builder">YUI Build Tool</a>

can wrap your code for you (it can also minify and lint your code, among

other things).

<p>The third parameter is a version identifier for your module. This

is not the YUI version you are targeting</p>

<p>The fourth parameter is an optional metadata object. This is read

by YUI when <code>YUI.add</code> executes -- it is used to fill in the

dependency information if this information was not previously provided

in the loader metadata provided to the YUI instance. See below for

information about dynamically loading modules. Dependencies are declared

via the <code>requires</code> attribute. The <code>use</code> attribute

describes a module/submodule relationship -- when you build a YUI

module with submodules, the built module file will have the entire

YUI.add wrapped content for each submodule. The <code>use</code> attribute

informs YUI that these modules must be used when the parent module is.

```

YUI.add('mymodules-mod1', function(Y) {

Y.namespace('mynamespace');

Y.mynamespace.Mod1 = function() {

// expose an API

};

}, '0.1.1' /* module version */, {

requires: ['base']

});

```

<h2 id="loader">Loader</h2>

<p>Loader's functionality is now built into the YUI Global Object

(as long as it's on the page) and puts its power behind the

<code>YUI().use</code> method.</p>

<p>If you request a module that is not loaded on the page

(or a dependency that is not loaded), loader will fetch a copy

of that module (and its dependencies) and attach them to your

YUI instance.</p>

```

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.

});

```

<p>The valid configuration options for Loader are as follows:<p>

<ul>

<li>`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 <a href="../intl/">Internationalization</a> module for more information.</li>

<li>`base`: The base dir</li>

<li>`comboBase`: The YUI combo service base dir. Ex: http://yui.yahooapis.com/combo?</li>

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

<li>`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:

<ul>

<li>`DEBUG`: Selects the debug versions of the library (e.g., event-debug.js). </li>

<li>`RAW`: Selects the non-minified version of the library (e.g., event.js).</li>

</ul>

You can also define a custom filter, which must be an object literal

containing a search expression and a replace string:

<pre>

myFilter: &#123;

'searchExp': "-min\\.js",

'replaceStr': "-debug.js"

&#125;

</pre>

</li>

<li>`combine`: Use the YUI combo service to reduce the number of http connections required to load your dependencies</li>

<li>`ignore`: A list of modules that should never be dynamically loaded</li>

<li>`force`: A list of modules that should always be loaded when required, even if already present on the page</li>

<li>`insertBefore`: Node or id for a node that should be used as the insertion point for new nodes</li>

<li>`charset`: charset for dynamic nodes</li>

<li>`jsAttributes`: attributes to apply to dynamic script nodes</li>

<li>`cssAttributes`: attributes to apply to dynamic link nodes</li>

<li>`timeout`: number of milliseconds before a timeout occurs when dynamically loading nodes. in not set, there is no timeout</li>

<li>`context`: execution context for all callbacks</li>

<li>`modules`: A list of module definitions. The valid module configuration data is as follows:

<ul>

<li>`name`: required, the component name</li>

<li>`type`: required, the component type (js or css)</li>

<li>`path`: required if fullpath is not specified, the path to the script from "base"</li>

<li>`fullpath`: required if path isn't specified, the full path to the script. "base" will not be used to build the url</li>

<li>`requires`: array of modules required by this component</li>

<li>`optional`: array of optional modules for this component</li>

<li>`supersedes`: array of the modules this component replaces</li>

<li>`after`: array of modules the components which, if present, should be sorted above this one</li>

<li>`rollup`: the number of superseded modules required for automatic rollup</li>

<li>`lang`: array of BCP 47 language tags of languages for which this module has localized resource bundles</li>

<li>`condition`: Specifies that the module should be loaded automatically if

a condition is met. This is an object with up to three fields:

<ul>

<li>`trigger` - the name of a module that can trigger the auto-load</li>

<li>`test` - a function that returns true when the module is to be loaded.</li>

<li>`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`.</li>

</ul>

</li>

</ul>

</li>

<li>`groups`: in 3.1.0, the groups config was added as an enhancement over the 'modules' config. Each group can

the <code>base</code>, <code>comboBase</code>, <code>root</code>, <code>combine</code>, and <code>modules</code>

configs listed above. These values are used for all of the modules listed in the group</li>

</ul>

<h2 id="Lang">Lang</h2>

<p><code>Lang</code> contains JavaScript language utilities and extensions that are used in the YUI library.

```

var Y = YUI();

// true, an array literal is an array

Y.Lang.isArray([1, 2]);

// false, an object literal is not an array

Y.Lang.isArray({"one": "two"});

// however, when declared as an array, it is true

function() {

var a = new Array();

a["one"] = "two";

return Y.Lang.isArray(a);

}();

// false, a collection of elements is like an array, but isn't

Y.Lang.isArray(document.getElementsByTagName("body"));

// true, false is a boolean

Y.Lang.isBoolean(false);

// false, 1 and the string "true" are not booleans

Y.Lang.isBoolean(1);

Y.Lang.isBoolean("true");

// null is null, but false, undefined and "" are not

Y.Lang.isNull(null); // true

Y.Lang.isNull(undefined); // false

Y.Lang.isNull(""); // false

// a function is a function, but an object is not

Y.Lang.isFunction(function(){}); // true

Y.Lang.isFunction({foo: "bar"}); // false

// true, ints and floats are numbers

Y.Lang.isNumber(0);

Y.Lang.isNumber(123.123);

// false, strings that can be cast to numbers aren't really numbers

Y.Lang.isNumber("123.123");

// false, undefined numbers and infinity are not numbers we want to use

Y.Lang.isNumber(1/0);

// true, objects, functions, and arrays are objects

Y.Lang.isObject({});

Y.Lang.isObject(function(){});

Y.Lang.isObject([1,2]);

// false, primitives are not objects

Y.Lang.isObject(1);

Y.Lang.isObject(true);

Y.Lang.isObject("{}");

// strings

Y.Lang.isString("{}"); // true

Y.Lang.isString({foo: "bar"}); // false

Y.Lang.isString(123); // false

Y.Lang.isString(true); // false

// undefined is undefined, but null and false are not

Y.Lang.isUndefined(undefined); // true

Y.Lang.isUndefined(false); // false

Y.Lang.isUndefined(null); // false

```