index.mustache revision 72d545a3aacf73830ad019134a025794ed01ce1e
<div class="intro">
<p>The YUI module is the single core dependency for all YUI 3 implementations. It must be included on all pages that use YUI — 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>
<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>
</div>
<p>The YUI Global object is provided by one of our seed files:</p>
<h2 id="loader-seed">The Loader Seed</h2>
```
<script src="http://yui.yahooapis.com/{{{yuiVersion}}}/build/yui/yui-min.js"></script>
```
<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>
<h2 id="base-seed">The Base Seed</h2>
```
<script src="http://yui.yahooapis.com/{{{yuiVersion}}}/build/yui-base/yui-base-min.js"></script>
```
<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>
<!--h2 id="why">Why the namespace change?</h2>
<ol>
<li><strong>Backward Compatibility</strong>: With the change from `YAHOO` to `YUI` we are guaranteed not to break backward compatibility. This allows you to use both YUI 2 and YUI 3 on
the same page without fear of breaking existing code.</li>
<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.
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>
<li><strong>Versioning</strong>: If another version of YUI is loaded on the page, it will not change objects used in
existing YUI instances. Both versions of YUI will operate with the corresponding versions of the reqested YUI modules without impacting each other.</li>
<li><strong>More Dynamic</strong>: With Loader built into the core, loading files when you need them just got easier.</li>
<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>
<li><strong>Event Normalization</strong>: With the new Event Facade, you get maximum event normalization for cleaner cross browser code.</li>
</ol-->
<h2 id="core">YUI Core</h2>
<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>
```
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
});
```
<h3>Use callback</h3>
<p>You can pass a function in as the last argument to `use`. 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('anim', function(Y) {
// Y.Anim is available
});
```
<h3>Use shorthand</h3>
<p>The `use` method contains a shorthand reference for all modules on the page. It uses the `*` 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 `use`
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 `use` 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 `bootstrap` to false.</p>
<h2 id="config">Configuring the YUI instance</h2>
There are 4 primary ways to configure YUI and each have their own unique benefits. The YUI object
is configured via properties on a simple Javascript Object.
```
{
debug: true,
combine: true,
comboBase: 'http://mydomain.com/combo?',
root: 'yui3/'
}
```
A complete list of configuration options are
<a href="/yui/docs/api/classes/config.html">available in the API Docs</a>.
<h3>YUI_config</h3>
Setting options on the global variable `YUI_config`, the implementor can configure every YUI
instance on the page <strong>before</strong> YUI is loaded onto the page.
```
YUI_config = {
debug: true,
combine: true,
comboBase: 'http://mydomain.com/combo?',
root: 'yui3/'
};
```
<h3>YUI.GlobalConfig</h3>
Setting options to the `YUI.GlobalConfig` object, the implementor can configure every YUI
instance on the page <strong>after</strong> YUI is loaded onto the page.
```
YUI.GlobalConfig = {
debug: true,
combine: true,
comboBase: 'http://mydomain.com/combo?',
root: 'yui3/'
};
```
<h3>YUI.applyConfig</h3>
The global `YUI.applyConfig()` method allows the implementor to configure every YUI instance
on the page, but it <strong>merges</strong> configs passed to it. This can be useful if your
module is loaded onto the page in a <em>mashup</em>. The other configuration options do not
merge, they are simply an object.
```
debug: true,
combine: true
});
comboBase: 'http://mydomain.com/combo?',
root: 'yui3/'
});
```
<h3>Instance Config</h3>
The instance level configuration is the most common configuration option. You simply
pass your configuration object directly to the `YUI` constructor:
```
YUI({
debug: true,
combine: true,
comboBase: 'http://mydomain.com/combo?',
root: 'yui3/'
}).use('node', function(Y) {
//
});
```
<h2 id="modulelist">Module List</h2>
<p>
YUI provides more than 250 unique modules to use in your applications.
<a href="modules.html">You can view a full list of modules here.</a>
</p>
<h2 id="yuiadd">Creating Custom Modules with YUI.add</h2>
<p>`YUI.add` 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 `use` method. Modules registered this way
are dynamically attached during the `use` phase, so
they can be fully protected by the YUI sandbox.</p>
<p>During the `use` phase, the function passed to
`YUI.add` 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 `YUI.add` 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 `requires` attribute. The `use` 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 `use` 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="nodejs">Using YUI on Node.js</h2>
<p>As of 3.5.0, YUI runs natively on <a href="http://nodejs.org/">Node.js</a> and comes with an official <a href="http://search.npmjs.org/#/yui">npm</a> package for easy installation.</p>
<p>More information on using YUI on Node.js can be <a href="nodejs.html">found here</a>.</p>
<h2 id="loader">Loader</h2>
<p><a href="loader.html">Loader</a>'s functionality is now built into the YUI Global Object
(as long as it's on the page) and puts its power behind the
`YUI().use` 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>
<p>You can find <a href="loader.html">more information about Loader here</a>.</p>
<h2 id="Lang">Y.Lang</h2>
<p>`Y.Lang` contains JavaScript language utilities and extensions that are used in the YUI library.