index.mustache revision 75d7c0828cc6c14fe43d0822cb539140063eeb64
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass<div class="intro">
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove The `YUI` module is the core of YUI 3. It must be included on all pages that use YUI, and it's 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" that can load other dependencies as needed.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove<h2>Getting Started</h2>
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveThe first step in using YUI is to load the YUI "seed". The seed is the bare minimum core code that's needed to allow YUI to dynamically load additional dependencies on demand. YUI is extremely modular, and the small seed file makes it easy to load only the modules you want to use on a given page.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveInclude the YUI seed file by adding this script tag to your HTML:
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass<script src="http://yui.yahooapis.com/{{{yuiVersion}}}/build/yui/yui-min.js"></script>
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveThe seed file adds a single global variable to the page: the `YUI` object. To begin using YUI, you'll first create a new YUI instance and then tell that instance which YUI modules you want to use.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove<div id="demo">Click me</div>
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove// Create a new YUI sandbox and load the "node" module.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveYUI().use('node', function (Y) {
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // YUI will call this function and pass in the YUI instance (Y) once all
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // modules have finished loading and are ready to use.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // We can now use Y.Node to get references to DOM elements using CSS
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // selectors.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove var demo = Y.one('#demo');
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // And we can listen for DOM events.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove demo.on('click', function (e) {
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove demo.set('text', 'You clicked me!');
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveCalling `YUI()` creates a brand new YUI instance without any active modules. We then call `.use()` on that new instance and pass in a list of modules we want to use, in the form of string parameters. You can name as many modules as you like here. Finally, we pass a callback function that will be executed once all those modules have finished loading. The callback function receives the YUI instance as an argument, which we've named `Y`.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveThis pattern is called a "sandbox", and it's the most important concept to understand about YUI. It not only makes it easy to load dependencies on demand, it also ensures that your code (and YUI's code!) doesn't pollute the global scope of the page or interfere with other global JavaScript you may be using.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveThis also means that you can have multiple YUI sandboxes on the same page, and they won't interfere with each other (but they <em>will</em> avoid reloading module code that has already been loaded).
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove<h2>Alternative Seed Files</h2>
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveIn [[#Getting Started]], we described the most common way to load YUI using what we call the "Loader Seed". This is a seed file that contains both the core of YUI and the code for the YUI Loader and all the metadata that's necessary to dynamically load additional YUI modules. Depending on your needs, you may want to use a different seed file to further optimize how you load YUI.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove<h3 id="base-seed">The Base Seed</h3>
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav Glass<script src="http://yui.yahooapis.com/{{{yuiVersion}}}/build/yui-base/yui-base-min.js"></script>
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveThe base seed contains the YUI core and the <a href="../get/index.html">Get Utility</a>, but doesn't include Loader or any module metadata. The first time you call `YUI().use()`, it will automatically fetch Loader and the module metadata, and then will make a second request to fetch any additional modules you've asked for.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveThis results in a smaller initial seed file that can speed up the initial page load, but requires more requests overall to get an actual YUI instance up and running. Prior to version 3.4.0, this was the default YUI seed file.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove<h3 id="core-seed">The Core Seed</h3>
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove<script src="http://yui.yahooapis.com/{{{yuiVersion}}}/build/yui-core/yui-core-min.js"></script>
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveThe core seed contains only the YUI core, and isn't capable of dynamically loading other modules. This is the smallest of all the seed files, but requires you to manually load any dependencies you need before using them.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove<h2>Loading Modules</h2>
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove<h3>Dynamic Loading with `use()`</h3>
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveThe `use()` method allows you to specify the modules that you want to load into your YUI instance.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveYUI().use('node', 'event', function (Y) {
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // The node and event modules are available on this YUI instance.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveYUI modules aren't actually executed until they're used and attached to a YUI instance, and two different YUI instances can have two different sets of modules attached to them. Even if both instances use the same module, each instance gets its own "copy" of that module and isn't affected by changes made in another instance.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveYUI().use('node', function (Y) {
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // We can blow away the Y.Node module in this outer YUI instance...
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove YUI().use('node', function (Y2) {
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // ...without affecting it inside another YUI instance...
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveYou can also call `use()` on an existing YUI instance to attach more modules to that instance without needing to create a completely new YUI instance. This is useful for lazy-loading modules that aren't needed up front.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove// First we create a YUI instance and use the node module.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveYUI().use('calendar', function (Y) {
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // The calendar module is available here.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // Later, we decide we want to use the autocomplete module, so we attach it
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // to the same instance.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove Y.use('autocomplete', function () {
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // The autocomplete module is available here, and the calendar module is
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // still available as well since this is the same YUI instance.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove<h3>Understanding `YUI().use()`</h3>
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveThe `YUI().use()` call might seem like magic, but it's actually doing something very simple. It's easier to understand what's going on if we break it into multiple steps.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveFirst, calling `YUI()` creates a brand new YUI instance. This instance will later be passed on to our callback function as the `Y` argument, but if we wanted to, we could just stop here and start using it immediately without even calling `use()`.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveNext, we call `use()` on the new YUI instance that was just created. We pass in a list of the modules we want to use, followed by a function that we want YUI to call once all those modules are available.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveFinally, YUI loads any necessary modules, attaches them to the YUI instance (this is when the modules are actually executed), and then calls our callback function. The YUI instance passes itself to the callback function as an argument for convenience, so that we don't have to store the instance in a global variable.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveThe callback function passed to `use()` is executed asynchronously, which means that it doesn't block subsequent code while modules are being loaded.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveBroken out into more verbose code, these three steps look like this:
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove// Step one: create a new YUI instance.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grovevar Y = YUI();
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove// Step two: load and attach some modules in that instance. Note that we
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove// call Y.use() here and not YUI().use().
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveY.use('node', 'event', function (Y) {
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // Step three: do stuff with node and event.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // The Y object that gets passed to this function is exactly the same as the
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // global Y object created in step one, so it's really only necessary when
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // you don't store the YUI instance in a global variable.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveExcept for creating a global `Y` variable, that code does exactly the same thing
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Groveas this code:
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveYUI().use('node', 'event', function (Y) {
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // Do stuff with node and event.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveIf you wanted to, you could create a global `Y` variable using the shorter style as well:
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grovevar Y = YUI().use('node', 'event', function (Y) {
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // Do stuff with node and event.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove<h3>Module States</h3>
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveWithin any given YUI instance, there are three possible states for a module:
54d9f2784fc7e4f704c3efbfdf67cf74f41c0ca3Dav Glass <li><p><strong>Not loaded</strong>: The module code has not been downloaded yet and is not available to any YUI instance.</p></li>
54d9f2784fc7e4f704c3efbfdf67cf74f41c0ca3Dav Glass <li><p><strong>Loaded</strong>: The module code has been downloaded, but has not been attached to this specific YUI instance. Other instances may be using it, but this instance isn't using it yet.</p></li>
54d9f2784fc7e4f704c3efbfdf67cf74f41c0ca3Dav Glass <li><p><strong>Attached</strong>: The module code has been downloaded and is attached to this YUI instance. The module is ready to use.</p></li>
54d9f2784fc7e4f704c3efbfdf67cf74f41c0ca3Dav Glass Since we haven't created an instance yet, all YUI modules are
54d9f2784fc7e4f704c3efbfdf67cf74f41c0ca3Dav Glass in the 'Not loaded' state until they are requested.
54d9f2784fc7e4f704c3efbfdf67cf74f41c0ca3Dav GlassYUI().use('calendar', function(Y) {
54d9f2784fc7e4f704c3efbfdf67cf74f41c0ca3Dav Glass //Now calender and all if it's dependencies are 'Loaded' and 'Attached' on this instance
54d9f2784fc7e4f704c3efbfdf67cf74f41c0ca3Dav GlassYUI().use('node', function(Y) {
54d9f2784fc7e4f704c3efbfdf67cf74f41c0ca3Dav Glass //Now node and all of it's dependencies are 'Loaded' and 'Attached' on this instance
54d9f2784fc7e4f704c3efbfdf67cf74f41c0ca3Dav Glass //Calender and it's un-used dependencies are in the 'Loaded' state on this instance
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove<h3>Static Loading</h3>
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveTo reach the "loaded" state, a module's JavaScript just needs to be included on the page after the YUI seed file. The `use()` method will do this for you automatically if necessary, but you could also load a module manually if you wanted to. We call this static loading (since it's the opposite of dynamic loading).
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove<script src="http://yui.yahooapis.com/{{{yuiVersion}}}/build/yui-base/yui-base-min.js"></script>
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove<script src="http://yui.yahooapis.com/{{{yuiVersion}}}/build/node-base/node-base-min.js"></script>
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveYUI().use('node-base', function (Y) {
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // Since the node-base module has already been loaded statically, YUI
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // doesn't need to download it again and can just execute and attach the
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // module code here.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveIf you want to take full manual control of your dependencies, you can statically load any modules you want to use and then pass `'*'` to `use()` instead of specifying a list of module names. This tells YUI to attach all loaded modules to your YUI instance without requiring you to name each module you want to attach.
4613cfd8960e141ac5d088a10bc6124df2e46f24Dav GlassYUI().use('*', function(Y) {
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // Any modules that were already loaded on the page statically will now be
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // attached and ready to use. YUI will not automatically load any modules
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove // that weren't already on the page.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove<h2 id="config">Configuring YUI</h2>
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveThere are four primary ways to configure YUI and each has its own unique benefits. The YUI object is configured via properties on a simple JavaScript object.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove debug: true,
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove combine: true,
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove root: 'yui3/'
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveA complete list of configuration options is
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove<a href="{{apiDocs}}/classes/config.html">available in the API Docs</a>.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove<h3>Instance Config</h3>
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveThe most common way to specify config options for YUI is to pass them into the `YUI()` constructor when creating a new instance:
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass debug: true,
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass combine: true,
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass root: 'yui3/'
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove }).use('node', function (Y) {
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveThese config options will only apply to this specific instance of YUI.
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass<h3>YUI_config</h3>
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveBy setting options on the global variable `YUI_config`, you can configure every YUI
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Groveinstance on the page even <em>before</em> YUI is loaded.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveYUI_config = {
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove debug: true,
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove combine: true,
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove root: 'yui3/'
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveBy setting options on the `YUI.GlobalConfig` object, you can configure every YUI
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Groveinstance on the page <em>after</em> YUI is loaded.
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove debug: true,
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove combine: true,
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove root: 'yui3/'
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan GroveThe global `YUI.applyConfig()` method allows you to configure every YUI instance on the page, but it <em>merges</em> configs passed to it into each instance's existing config. 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.
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass debug: true,
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass combine: true
f6d4c278480066ea3f6f85cfbeae259aacfa86f8Dav Glass root: 'yui3/'
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove<h2 id="yuiadd">Creating Custom Modules with `YUI.add()`</h2>
9d2003304196a2769a38dca27c76e4fda1e875b0Dav Glass<p>For more information on creating your custom modules, see our <a href="create.html">Creating YUI Modules</a> example.</p>
72d545a3aacf73830ad019134a025794ed01ce1eDav Glass<h2 id="nodejs">Using YUI on Node.js</h2>
b993d73b72d01aea95784d3f766a44c72db4bd21Ryan Grove<p>As of version 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 package</a> for easy installation. More information on using YUI on Node.js can be found in the <a href="nodejs.html">YUI on Node.js guide</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>
75d7c0828cc6c14fe43d0822cb539140063eeb64Dav Glass<h3 id="async">New Async Loading in 3.5.0</h3>
75d7c0828cc6c14fe43d0822cb539140063eeb64Dav Glass<p>In `3.5.0`, we introduced asnychronous loading in Loader by default. This means that any script
75d7c0828cc6c14fe43d0822cb539140063eeb64Dav Glass`Loader` injects into the page will be loaded asnychronously. This will decrease load time and
75d7c0828cc6c14fe43d0822cb539140063eeb64Dav Glassimprove performance by allowing the browser to fetch as many scripts at once as it can.
75d7c0828cc6c14fe43d0822cb539140063eeb64Dav Glass<p>If your custom modules are properly wrapped in a `YUI.add` callback, you will see no difference at all.
75d7c0828cc6c14fe43d0822cb539140063eeb64Dav GlassHowever, if you are loading custom modules that require ordered script loading
75d7c0828cc6c14fe43d0822cb539140063eeb64Dav Glass(depends on another dynamic, unwrapped module), you will need to change your module config to tell
75d7c0828cc6c14fe43d0822cb539140063eeb64Dav Glass`Loader` to <strong>not</strong> load these modules with the `async` flag. You can do this by adding
75d7c0828cc6c14fe43d0822cb539140063eeb64Dav Glassan `async: false` config to it's module definition and `Y.Get.script` will not load it asynchronously.
75d7c0828cc6c14fe43d0822cb539140063eeb64Dav Glass aync: false,
75d7c0828cc6c14fe43d0822cb539140063eeb64Dav Glass fullpath: './one.js'
75d7c0828cc6c14fe43d0822cb539140063eeb64Dav Glass async: false,
75d7c0828cc6c14fe43d0822cb539140063eeb64Dav Glass fullpath: './two.js',
75d7c0828cc6c14fe43d0822cb539140063eeb64Dav Glass requires: [ 'one' ]
75d7c0828cc6c14fe43d0822cb539140063eeb64Dav Glass}).use('two'), function(Y) {
75d7c0828cc6c14fe43d0822cb539140063eeb64Dav Glass //Module one & two are loaded now.
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>
fb80fb11b2381e31ac3a239fbe1393814276e113Ryan Grove<h2 id="modulelist">Complete Module List</h2>
fb80fb11b2381e31ac3a239fbe1393814276e113Ryan GroveYUI 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>