index.mustache revision 72d545a3aacf73830ad019134a025794ed01ce1e
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass<div class="intro">
12ea6e8d01681430f89557c24dcefdacb29d391fDav Glass <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>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass <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>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass<p>The YUI Global object is provided by one of our seed files:</p>
046ea4d1ee0f22d956cd360e1e0c0b275aa4bbd0Dav Glass<h2 id="loader-seed">The Loader Seed</h2>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass<script src="http://yui.yahooapis.com/{{{yuiVersion}}}/build/yui/yui-min.js"></script>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass<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>
046ea4d1ee0f22d956cd360e1e0c0b275aa4bbd0Dav Glass<h2 id="base-seed">The Base Seed</h2>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass<script src="http://yui.yahooapis.com/{{{yuiVersion}}}/build/yui-base/yui-base-min.js"></script>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass<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>
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass<!--h2 id="why">Why the namespace change?</h2>
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass <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
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass the same page without fear of breaking existing code.</li>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass <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.
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass 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>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass <li><strong>Versioning</strong>: If another version of YUI is loaded on the page, it will not change objects used in
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass existing YUI instances. Both versions of YUI will operate with the corresponding versions of the reqested YUI modules without impacting each other.</li>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass <li><strong>More Dynamic</strong>: With Loader built into the core, loading files when you need them just got easier.</li>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass <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>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass <li><strong>Event Normalization</strong>: With the new Event Facade, you get maximum event normalization for cleaner cross browser code.</li>
046ea4d1ee0f22d956cd360e1e0c0b275aa4bbd0Dav Glass<h2 id="core">YUI Core</h2>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass<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>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav GlassYUI().use('node', function(Y) {
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass<p>All of this functionality is available in the YUI Core:</p>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass <th>YUI 3 Component</th>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass <th>Module</th>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass <td>Array Operations</td><td>array</td>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass <td>YUI Core</td><td>core</td>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass <td>JavaScript language helper methods</td><td>lang</td>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass <td>Periodic execution method</td><td>later</td>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass <td>Logging support</td><td>log</td>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass <td>Object Operations</td><td>object</td>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass <td>Browser Sniffing</td><td>ua</td>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass <td>YUI Object</td><td>yui</td>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass <td>Dynamic script and css loading</td><td>get</td>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass <td>YUI Loader</td><td>loader</td>
046ea4d1ee0f22d956cd360e1e0c0b275aa4bbd0Dav Glass<h2 id="use">Use method</h2>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass<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>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav GlassYUI().use('dd-drop', 'anim', function(Y) {
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass // Y.DD is available
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass // Y.Anim is available
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav GlassYUI().use('anim', function(Y) {
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass // Y.DD is NOT available
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass // Y.Anim is available
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass<h3>Use callback</h3>
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass<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.
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav GlassThis is required if you do not have all dependencies on the page.</p>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass<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>
deaaed5d80c583c22128aea2af24d700678666b6Dav GlassYUI().use('anim', function(Y) {
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass // Y.Anim is available
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass<h3>Use shorthand</h3>
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass<p>The `use` method contains a shorthand reference for all modules on the page. It uses the `*` as the module name.</p>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass<p>This will load every module that is included on the page.</p>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav GlassYUI().use('*', function(Y) {
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass // Implementation code
046ea4d1ee0f22d956cd360e1e0c0b275aa4bbd0Dav Glass<h2>Static inclusion vs. dynamic loading</h2>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass<p>YUI automatically tries to complete itself when missing dependencies are detected.
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass When dynamically loading the dependencies, the callback passed to `use`
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass will be executed <em>asynchronously</em>. If you statically include all of the
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass library requirements (or all were previously loaded by another means), the
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass use() callback will execute synchronously. The purpose of the callback is so
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass that it doesn't matter to the implementation whether the operation was synchronous
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass or not. Code immediately following the `use` statement will not have
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass access to any of the requested modules if anything has to be dynamically loaded.
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass You can prevent YUI from automatically trying to obtain missing dependencies by setting the
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass YUI config `bootstrap` to false.</p>
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass<h2 id="config">Configuring the YUI instance</h2>
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav GlassThere are 4 primary ways to configure YUI and each have their own unique benefits. The YUI object
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glassis configured via properties on a simple Javascript Object.
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass debug: true,
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass combine: true,
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass root: 'yui3/'
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav GlassA complete list of configuration options are
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass<a href="/yui/docs/api/classes/config.html">available in the API Docs</a>.
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass<h3>YUI_config</h3>
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav GlassSetting options on the global variable `YUI_config`, the implementor can configure every YUI
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glassinstance on the page <strong>before</strong> YUI is loaded onto the page.
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass YUI_config = {
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass debug: true,
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass combine: true,
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass root: 'yui3/'
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav GlassSetting options to the `YUI.GlobalConfig` object, the implementor can configure every YUI
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glassinstance on the page <strong>after</strong> YUI is loaded onto the page.
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass debug: true,
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass combine: true,
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass root: 'yui3/'
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav GlassThe global `YUI.applyConfig()` method allows the implementor to configure every YUI instance
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glasson the page, but it <strong>merges</strong> configs passed to it. This can be useful if your
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glassmodule is loaded onto the page in a <em>mashup</em>. The other configuration options do not
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glassmerge, they are simply an object.
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass debug: true,
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass combine: true
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass root: 'yui3/'
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass<h3>Instance Config</h3>
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav GlassThe instance level configuration is the most common configuration option. You simply
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glasspass your configuration object directly to the `YUI` constructor:
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass debug: true,
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass combine: true,
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass root: 'yui3/'
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass }).use('node', function(Y) {
046ea4d1ee0f22d956cd360e1e0c0b275aa4bbd0Dav Glass<h2 id="modulelist">Module List</h2>
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass YUI provides more than 250 unique modules to use in your applications.
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass <a href="modules.html">You can view a full list of modules here.</a>
046ea4d1ee0f22d956cd360e1e0c0b275aa4bbd0Dav Glass<h2 id="yuiadd">Creating Custom Modules with YUI.add</h2>
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass<p>`YUI.add` is a static global method that is
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glassthe single entry point for first class YUI modules. This method
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glassregisters the module so that it can attached to a YUI instance
72d545a3aacf73830ad019134a025794ed01ce1eDav Glassvia the `use` method. Modules registered this way
72d545a3aacf73830ad019134a025794ed01ce1eDav Glassare dynamically attached during the `use` phase, so
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glassthey can be fully protected by the YUI sandbox.</p>
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass<p>During the `use` phase, the function passed to
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass`YUI.add` is executed. It receives the YUI instance
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glassas a parameter, and this can be used to add functionality to
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glassthe instance.</p>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass<p>While you can add the module wrapper to your code yourself,
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glassthe <a href="http://yuilibrary.com/projects/builder">YUI Build Tool</a>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glasscan wrap your code for you (it can also minify and lint your code, among
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glassother things).
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass<p>The third parameter is a version identifier for your module. This
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glassis not the YUI version you are targeting</p>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass<p>The fourth parameter is an optional metadata object. This is read
72d545a3aacf73830ad019134a025794ed01ce1eDav Glassby YUI when `YUI.add` executes -- it is used to fill in the
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glassdependency information if this information was not previously provided
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glassin the loader metadata provided to the YUI instance. See below for
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glassinformation about dynamically loading modules. Dependencies are declared
72d545a3aacf73830ad019134a025794ed01ce1eDav Glassvia the `requires` attribute. The `use` attribute
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glassdescribes a module/submodule relationship -- when you build a YUI
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glassmodule with submodules, the built module file will have the entire
72d545a3aacf73830ad019134a025794ed01ce1eDav GlassYUI.add wrapped content for each submodule. The `use` attribute
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glassinforms YUI that these modules must be used when the parent module is.
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav GlassYUI.add('mymodules-mod1', function(Y) {
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass Y.namespace('mynamespace');
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass // expose an API
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass}, '0.1.1' /* module version */, {
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass requires: ['base']
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass<h2 id="nodejs">Using YUI on Node.js</h2>
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass<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>
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass<p>More information on using YUI on Node.js can be <a href="nodejs.html">found here</a>.</p>
046ea4d1ee0f22d956cd360e1e0c0b275aa4bbd0Dav Glass<h2 id="loader">Loader</h2>
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass<p><a href="loader.html">Loader</a>'s functionality is now built into the YUI Global Object
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass (as long as it's on the page) and puts its power behind the
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass `YUI().use` method.</p>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass<p>If you request a module that is not loaded on the page
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass(or a dependency that is not loaded), loader will fetch a copy
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glassof that module (and its dependencies) and attach them to your
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav GlassYUI instance.</p>
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass<p>You can find <a href="loader.html">more information about Loader here</a>.</p>
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass<h2 id="Lang">Y.Lang</h2>
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass<p>`Y.Lang` contains JavaScript language utilities and extensions that are used in the YUI library.
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass<p>Find more <a href="lang.html">information on `Y.Lang` here</a>.</p>