Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Merge branch 'live-docs'

Conflicts:
	src/yui/docs/component.json
	src/yui/docs/index.mustache
	src/yui/docs/modules.mustache
	src/yui/scripts/build_doc_modules.js
  • Loading branch information...
commit fb80fb11b2381e31ac3a239fbe1393814276e113 2 parents 93532c1 + b993d73
@rgrove rgrove authored
View
5 src/yui/docs/component.json
@@ -91,7 +91,8 @@
},
"modules": {
"displayName": "YUI Modules List",
- "hideTableOfContents": true
+ "hideTableOfContents": true,
+ "hideExamples": true
},
"loader": {
"displayName": "YUI Loader"
@@ -100,5 +101,5 @@
"displayName": "Y.Lang",
"hideTableOfContents": true
}
- }
+ }
}
View
503 src/yui/docs/index.mustache
@@ -1,198 +1,323 @@
<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 &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>
- <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>
+ <p>
+ 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.
+ </p>
</div>
+<h2>Getting Started</h2>
-<p>The YUI Global object is provided by one of our seed files:</p>
+<p>
+The 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.
+</p>
+
+<p>
+Include the YUI seed file by adding this script tag to your HTML:
+</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>
+<p>
+The 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.
+</p>
+```
+<div id="demo">Click me</div>
+<script>
+// Create a new YUI sandbox and load the "node" module.
+YUI().use('node', function (Y) {
+ // YUI will call this function and pass in the YUI instance (Y) once all
+ // modules have finished loading and are ready to use.
+
+ // We can now use Y.Node to get references to DOM elements using CSS
+ // selectors.
+ var demo = Y.one('#demo');
+
+ // And we can listen for DOM events.
+ demo.on('click', function (e) {
+ demo.set('text', 'You clicked me!');
+ });
+});
+</script>
+```
+
+<p>
+Calling `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`.
+</p>
+
+<p>
+This 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.
+</p>
+
+<p>
+This 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).
+</p>
+
+<h2>Alternative Seed Files</h2>
+
+<p>
+In [[#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.
+</p>
+
+<h3 id="base-seed">The Base Seed</h3>
-<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>
+<p>
+The 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.
+</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>
+<p>
+This 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.
+</p>
+
+<h3 id="core-seed">The Core Seed</h3>
+
+```
+<script src="http://yui.yahooapis.com/{{{yuiVersion}}}/build/yui-core/yui-core-min.js"></script>
+```
+
+<p>
+The 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.
+</p>
+
+<h2>Loading Modules</h2>
+
+<h3>Dynamic Loading with `use()`</h3>
+
+<p>
+The `use()` method allows you to specify the modules that you want to load into your YUI instance.
+</p>
+
+```
+YUI().use('node', 'event', function (Y) {
+ // The node and event modules are available on this YUI instance.
+});
+```
+<p>
+YUI 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.
+</p>
+```
+YUI().use('node', function (Y) {
+ // We can blow away the Y.Node module in this outer YUI instance...
+ Y.Node = null;
- <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-->
+ YUI().use('node', function (Y2) {
+ // ...without affecting it inside another YUI instance...
+ console.log(typeof Y2.Node); // => "function"
+ });
+});
+```
+<p>
+You 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.
+</p>
-<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>
+```
+// First we create a YUI instance and use the node module.
+YUI().use('calendar', function (Y) {
+ // The calendar module is available here.
+
+ // Later, we decide we want to use the autocomplete module, so we attach it
+ // to the same instance.
+ Y.use('autocomplete', function () {
+ // The autocomplete module is available here, and the calendar module is
+ // still available as well since this is the same YUI instance.
+ });
+});
+```
+
+<h3>Understanding `YUI().use()`</h3>
+
+<p>
+The `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.
+</p>
+
+<p>
+First, 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()`.
+</p>
+
+<p>
+Next, 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.
+</p>
+
+<p>
+Finally, 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.
+</p>
+
+<p>
+The callback function passed to `use()` is executed asynchronously, which means that it doesn't block subsequent code while modules are being loaded.
+</p>
+
+<p>
+Broken out into more verbose code, these three steps look like this:
+</p>
```
-YUI().use('node', function(Y) {
- Y.one('#demo');
+// Step one: create a new YUI instance.
+var Y = YUI();
+
+// Step two: load and attach some modules in that instance. Note that we
+// call Y.use() here and not YUI().use().
+Y.use('node', 'event', function (Y) {
+ // Step three: do stuff with node and event.
+
+ // The Y object that gets passed to this function is exactly the same as the
+ // global Y object created in step one, so it's really only necessary when
+ // you don't store the YUI instance in a global variable.
});
```
-<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
+<p>
+Except for creating a global `Y` variable, that code does exactly the same thing
+as this code:
+</p>
+
+```
+YUI().use('node', 'event', function (Y) {
+ // Do stuff with node and event.
});
+```
-YUI().use('anim', function(Y) {
- // Y.DD is NOT available
- // Y.Anim is available
+<p>
+If you wanted to, you could create a global `Y` variable using the shorter style as well:
+</p>
+
+```
+var Y = YUI().use('node', 'event', function (Y) {
+ // Do stuff with node and event.
});
```
-<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>
+<h3>Module States</h3>
+
+Within any given YUI instance, there are three possible states for a module:
+</p>
+
+<ol>
+<li><p><strong>Not loaded</strong>: The module code has not been downloaded yet and is not available to any YUI instance.</p></li>
+
+<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>
+
+<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>
+</ol>
+
+<h3>Static Loading</h3>
+
+<p>
+To 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).
+</p>
```
-YUI().use('anim', function(Y) {
- // Y.Anim is available
+<script src="http://yui.yahooapis.com/{{{yuiVersion}}}/build/yui-base/yui-base-min.js"></script>
+<script src="http://yui.yahooapis.com/{{{yuiVersion}}}/build/node-base/node-base-min.js"></script>
+<script>
+YUI().use('node-base', function (Y) {
+ // Since the node-base module has already been loaded statically, YUI
+ // doesn't need to download it again and can just execute and attach the
+ // module code here.
});
+</script>
```
-<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>
+<p>
+If 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.
+</p>
```
YUI().use('*', function(Y) {
- // Implementation code
+ // Any modules that were already loaded on the page statically will now be
+ // attached and ready to use. YUI will not automatically load any modules
+ // that weren't already on the page.
});
```
-<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>
+<h2 id="config">Configuring YUI</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.
+<p>
+There 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.
+</p>
+
+```
+{
+ debug: true,
+ combine: true,
+ comboBase: 'http://mydomain.com/combo?',
+ root: 'yui3/'
+}
+```
+
+<p>
+A complete list of configuration options is
+<a href="{{apiDocs}}/classes/config.html">available in the API Docs</a>.
+</p>
+
+<h3>Instance Config</h3>
+
+<p>
+The most common way to specify config options for YUI is to pass them into the `YUI()` constructor when creating a new instance:
+</p>
```
- {
+ YUI({
debug: true,
combine: true,
comboBase: 'http://mydomain.com/combo?',
root: 'yui3/'
- }
+ }).use('node', function (Y) {
+ // ...
+ });
```
-
-A complete list of configuration options are
-<a href="/yui/docs/api/classes/config.html">available in the API Docs</a>.
+<p>
+These config options will only apply to this specific instance of YUI.
+</p>
<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.
+<p>
+By setting options on the global variable `YUI_config`, you can configure every YUI
+instance on the page even <em>before</em> YUI is loaded.
+</p>
- ```
- YUI_config = {
- debug: true,
- combine: true,
- comboBase: 'http://mydomain.com/combo?',
- root: 'yui3/'
- };
- ```
+```
+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/'
- };
- ```
+<p>
+By setting options on the `YUI.GlobalConfig` object, you can configure every YUI
+instance on the page <em>after</em> YUI is loaded.
+</p>
-<h3>YUI.applyConfig</h3>
+```
+YUI.GlobalConfig = {
+ debug: true,
+ combine: true,
+ comboBase: 'http://mydomain.com/combo?',
+ root: 'yui3/'
+};
+```
-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.
+<h3>YUI.applyConfig</h3>
+<p>
+The 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.
+</p>
```
YUI.applyConfig({
debug: true,
@@ -204,76 +329,64 @@ merge, they are simply an object.
});
```
-<h3>Instance Config</h3>
+<h2 id="yuiadd">Creating Custom Modules with `YUI.add()`</h2>
-The instance level configuration is the most common configuration option. You simply
-pass your configuration object directly to the `YUI` constructor:
+<p>
+`YUI.add()` is a static method that registers a reusable module&mdash;essentially, it adds a module to the set of modules available to be attached to a YUI instance via the `use()` method.
+</p>
- ```
- YUI({
- debug: true,
- combine: true,
- comboBase: 'http://mydomain.com/combo?',
- root: 'yui3/'
- }).use('node', function(Y) {
- //
- });
- ```
+<p>
+Defining a reusable YUI module is as simple as providing a name and a callback function to `YUI.add()`.
+</p>
+```
+YUI.add('my-module', function (Y) {
+ // Write your module code here, and make your module available on the Y
+ // object if desired.
+ Y.MyModule = {
+ sayHello: function () {
+ console.log('Hello!');
+ }
+ };
+});
+```
+
+<p>
+Note that there are no parentheses after `YUI` when calling `YUI.add()` as there are when calling `YUI().use()`. This is because `add()` is a static method of the global `YUI` object, not a method on a specific YUI instance. Modules are registered globally via `add()` and are later attached to a specific YUI instance via `use()`.
+</p>
+
+<p>
+The `add()` method accepts two optional arguments after the callback function: a module version string and a config object. The most useful option in the config object is `requires`, which allows you to specify an array of other YUI modules that your module requires. YUI will then be sure to load these dependencies before executing your module.
+</p>
+
+```
+YUI.add('my-module', function (Y) {
+ // ...
+}, '0.0.1', {
+ requires: ['node', 'event']
+});
+```
-<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']
+<p>
+After your module has been added via `YUI.add()`, you can specify its name in a `use()` call to attach it to a YUI instance.
+</p>
+
+```
+YUI().use('my-module', function (Y) {
+ // The Y instance here is the same Y instance that was passed into
+ // my-module's add() callback, so the Y.MyModule object that was created
+ // there is now available here as well.
+ Y.MyModule.sayHello();
});
```
+<p>
+A module's `add()` callback isn't executed until that module is attached to a YUI instance via `use()`. Each time a module is attached via `use()`, the module's `add()` callback will be executed, and will receive as an argument the same YUI instance that will later be passed to the `use()` callback.
+</p>
+
<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>
+<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>
<h2 id="loader">Loader</h2>
<p><a href="loader.html">Loader</a>'s functionality is now built into the YUI Global Object
@@ -291,3 +404,9 @@ YUI instance.</p>
<p>`Y.Lang` contains JavaScript language utilities and extensions that are used in the YUI library.
<p>Find more <a href="lang.html">information on `Y.Lang` here</a>.</p>
+
+<h2 id="modulelist">Complete 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>
View
2  src/yui/docs/modules.mustache
@@ -1,3 +1,3 @@
-<p>Here is an auto-generated list of modules available in YUI.</p>
+<p>This is an auto-generated list of modules available in YUI.</p>
{{>modules}}
View
2  src/yui/scripts/build_doc_modules.js
@@ -38,7 +38,7 @@ Object.keys(data.modules).forEach(function(i) {
var v = data.modules[i];
var d = v.description || '';
-
+
d = d.split('\n')[0].replace('<p>', '').replace('</p>', '');
if (alias_data[v.name] && alias_data[v.name].use) {

0 comments on commit fb80fb1

Please sign in to comment.
Something went wrong with that request. Please try again.