index.mustache revision 72d545a3aacf73830ad019134a025794ed01ce1e
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox User<div class="intro">
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic Updater <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>
18920d790825d96ca3943aa2dcb6eb80dc611c5fTinderbox User <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>
c57668a2fbbe558c1bd21652813616f2f517c469Tinderbox User<p>The YUI Global object is provided by one of our seed files:</p>
1f4c645185bd8fc70048e0a69eee46193a284e5cTinderbox User<h2 id="loader-seed">The Loader Seed</h2>
8de3f14f1c300c3e1ed99084cc03485b42c92bf1Tinderbox User<script src="http://yui.yahooapis.com/{{{yuiVersion}}}/build/yui/yui-min.js"></script>
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews<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>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<h2 id="base-seed">The Base Seed</h2>
a7c412f37cc73d0332887a746e81220cbf09dd00Mark Andrews<script src="http://yui.yahooapis.com/{{{yuiVersion}}}/build/yui-base/yui-base-min.js"></script>
e676a596869d8a80a644c99a848afb53d1c5975eMark Andrews<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>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<!--h2 id="why">Why the namespace change?</h2>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <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
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User the same page without fear of breaking existing code.</li>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <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.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User 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>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <li><strong>Versioning</strong>: If another version of YUI is loaded on the page, it will not change objects used in
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User existing YUI instances. Both versions of YUI will operate with the corresponding versions of the reqested YUI modules without impacting each other.</li>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <li><strong>More Dynamic</strong>: With Loader built into the core, loading files when you need them just got easier.</li>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User <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>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <li><strong>Event Normalization</strong>: With the new Event Facade, you get maximum event normalization for cleaner cross browser code.</li>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<h2 id="core">YUI Core</h2>
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox User<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>
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox UserYUI().use('node', function(Y) {
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<p>All of this functionality is available in the YUI Core:</p>
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox User <th>YUI 3 Component</th>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater <th>Module</th>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <td>Array Operations</td><td>array</td>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <td>YUI Core</td><td>core</td>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <td>JavaScript language helper methods</td><td>lang</td>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater <td>Periodic execution method</td><td>later</td>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <td>Logging support</td><td>log</td>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <td>Object Operations</td><td>object</td>
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt <td>Browser Sniffing</td><td>ua</td>
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt <td>YUI Object</td><td>yui</td>
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt <td>Dynamic script and css loading</td><td>get</td>
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt <td>YUI Loader</td><td>loader</td>
27739dd25026283c24645c8a1044b95ef9eb5ac6Tinderbox User<h2 id="use">Use method</h2>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<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>
7a6494cfb6cc7d3f67af07359561e05e6bb8c0edTinderbox UserYUI().use('dd-drop', 'anim', function(Y) {
0e573cdd111e060e5f6c18249b5ccacbe8abe278Tinderbox User // Y.DD is available
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews // Y.Anim is available
7a6494cfb6cc7d3f67af07359561e05e6bb8c0edTinderbox UserYUI().use('anim', function(Y) {
77932ac533c711eca5cd86de4e7eca8d91102b43Tinderbox User // Y.DD is NOT available
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews // Y.Anim is available
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<h3>Use callback</h3>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<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.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsThis is required if you do not have all dependencies on the page.</p>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<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>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserYUI().use('anim', function(Y) {
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews // Y.Anim is available
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<h3>Use shorthand</h3>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<p>The `use` method contains a shorthand reference for all modules on the page. It uses the `*` as the module name.</p>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<p>This will load every module that is included on the page.</p>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserYUI().use('*', function(Y) {
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews // Implementation code
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews<h2>Static inclusion vs. dynamic loading</h2>
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews<p>YUI automatically tries to complete itself when missing dependencies are detected.
0e573cdd111e060e5f6c18249b5ccacbe8abe278Tinderbox User When dynamically loading the dependencies, the callback passed to `use`
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews will be executed <em>asynchronously</em>. If you statically include all of the
fd972434c29fc1169d66594e4cc7697d33036c2bTinderbox User library requirements (or all were previously loaded by another means), the
37d8e0a4455876fe1e4cca511076cc2c5ab9eedeTinderbox User use() callback will execute synchronously. The purpose of the callback is so
37d8e0a4455876fe1e4cca511076cc2c5ab9eedeTinderbox User that it doesn't matter to the implementation whether the operation was synchronous
fd972434c29fc1169d66594e4cc7697d33036c2bTinderbox User or not. Code immediately following the `use` statement will not have
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont access to any of the requested modules if anything has to be dynamically loaded.
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews You can prevent YUI from automatically trying to obtain missing dependencies by setting the
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews YUI config `bootstrap` to false.</p>
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews<h2 id="config">Configuring the YUI instance</h2>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsThere are 4 primary ways to configure YUI and each have their own unique benefits. The YUI object
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrewsis configured via properties on a simple Javascript Object.
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews debug: true,
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews combine: true,
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews root: 'yui3/'
e20788e1216ed720aefa84f3295f7899d9f28c22Mark AndrewsA complete list of configuration options are
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews<a href="/yui/docs/api/classes/config.html">available in the API Docs</a>.
01a5c5503482fb3ba52088bf0178a7213273bf96Mark Andrews<h3>YUI_config</h3>
37d8e0a4455876fe1e4cca511076cc2c5ab9eedeTinderbox UserSetting options on the global variable `YUI_config`, the implementor can configure every YUI
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox Userinstance on the page <strong>before</strong> YUI is loaded onto the page.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User YUI_config = {
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews debug: true,
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User combine: true,
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User root: 'yui3/'
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserSetting options to the `YUI.GlobalConfig` object, the implementor can configure every YUI
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewsinstance on the page <strong>after</strong> YUI is loaded onto the page.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User combine: true,
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User root: 'yui3/'
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserThe global `YUI.applyConfig()` method allows the implementor to configure every YUI instance
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewson the page, but it <strong>merges</strong> configs passed to it. This can be useful if your
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox Usermodule is loaded onto the page in a <em>mashup</em>. The other configuration options do not
dd65eb1efb40b1c47d57963192bfc54873b219beAutomatic Updatermerge, they are simply an object.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews debug: true,
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User combine: true
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User root: 'yui3/'
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<h3>Instance Config</h3>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserThe instance level configuration is the most common configuration option. You simply
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewspass your configuration object directly to the `YUI` constructor:
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews debug: true,
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User combine: true,
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox User root: 'yui3/'
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews }).use('node', function(Y) {
37d8e0a4455876fe1e4cca511076cc2c5ab9eedeTinderbox User<h2 id="modulelist">Module List</h2>
7ca715ad1587a68a531ea1cdea07515d7232567eTinderbox User YUI provides more than 250 unique modules to use in your applications.
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox User <a href="modules.html">You can view a full list of modules here.</a>
e676a596869d8a80a644c99a848afb53d1c5975eMark Andrews<h2 id="yuiadd">Creating Custom Modules with YUI.add</h2>
91d187ce035f39073f0732ff2a401a45c3c955fbMark Andrews<p>`YUI.add` is a static global method that is
37d8e0a4455876fe1e4cca511076cc2c5ab9eedeTinderbox Userthe single entry point for first class YUI modules. This method
8e5fce1f9ceba17dd7e3ff0eb287e1e999c14249Mark Andrewsregisters the module so that it can attached to a YUI instance
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrewsvia the `use` method. Modules registered this way
4151211e6649332f7b5a55870cbe37128bcc7b29Tinderbox Userare dynamically attached during the `use` phase, so
91d187ce035f39073f0732ff2a401a45c3c955fbMark Andrewsthey can be fully protected by the YUI sandbox.</p>
bc0a53583d92309bebcf93c408e2f3247ebd3d3cAutomatic Updater<p>During the `use` phase, the function passed to
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater`YUI.add` is executed. It receives the YUI instance
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updateras a parameter, and this can be used to add functionality to
59528addd704f8d5757b54e540520f74e588a7c7Automatic Updaterthe instance.</p>
b02be031b9ff37b042adc8e68e36b8bbc1f672b7Tinderbox User<p>While you can add the module wrapper to your code yourself,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updaterthe <a href="http://yuilibrary.com/projects/builder">YUI Build Tool</a>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewscan wrap your code for you (it can also minify and lint your code, among
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<p>The third parameter is a version identifier for your module. This
d7d105151a78d35afb4233d2a6dbd47b7ec0d9a5Tinderbox Useris not the YUI version you are targeting</p>
b02be031b9ff37b042adc8e68e36b8bbc1f672b7Tinderbox User<p>The fourth parameter is an optional metadata object. This is read
37d8e0a4455876fe1e4cca511076cc2c5ab9eedeTinderbox Userby YUI when `YUI.add` executes -- it is used to fill in the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updaterdependency information if this information was not previously provided
19b3dc94bce93fa76bd7e066f9298630dbc9dcb4Automatic Updaterin the loader metadata provided to the YUI instance. See below for
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updaterinformation about dynamically loading modules. Dependencies are declared
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updatervia the `requires` attribute. The `use` attribute
7f94d9a8162c9a96b56e66176702b66e79d8e1a2Automatic Updaterdescribes a module/submodule relationship -- when you build a YUI
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updatermodule with submodules, the built module file will have the entire
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic UpdaterYUI.add wrapped content for each submodule. The `use` attribute
5ecad47f69b3fd945472ab2900a9ff826a7ce2f6Automatic Updaterinforms YUI that these modules must be used when the parent module is.
c2abd6efeb9affa70aabb63da2acb23e135cf7f2Mark AndrewsYUI.add('mymodules-mod1', function(Y) {
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox User Y.namespace('mynamespace');
9cd5eb6fe0f26d65724b99216cb31dcdd12e4afdAutomatic Updater // expose an API
4cda4fd158d6ded5586bacea8c388445d99611eaAutomatic Updater}, '0.1.1' /* module version */, {
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews requires: ['base']
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<h2 id="nodejs">Using YUI on Node.js</h2>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<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>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<p>More information on using YUI on Node.js can be <a href="nodejs.html">found here</a>.</p>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<h2 id="loader">Loader</h2>
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews<p><a href="loader.html">Loader</a>'s functionality is now built into the YUI Global Object
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews (as long as it's on the page) and puts its power behind the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater `YUI().use` method.</p>
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox User<p>If you request a module that is not loaded on the page
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox User(or a dependency that is not loaded), loader will fetch a copy
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updaterof that module (and its dependencies) and attach them to your
a7c412f37cc73d0332887a746e81220cbf09dd00Mark AndrewsYUI instance.</p>
da59e63e7af147a8bcef985b98b04443e04c3a0eTinderbox User<p>You can find <a href="loader.html">more information about Loader here</a>.</p>
cf7e98f59148b559946a7f1ca728471374f1eef3Automatic Updater<h2 id="Lang">Y.Lang</h2>
6025cbbe8408f4b09d53d5ec1e95cb6da97e0a8dTinderbox User<p>`Y.Lang` contains JavaScript language utilities and extensions that are used in the YUI library.
757ff043760e4743dda1a10e7d58349275934902Tinderbox User<p>Find more <a href="lang.html">information on `Y.Lang` here</a>.</p>