Merge remote-tracking branch 'adambard/master' into adambard/master-cn

1 files changed, 212 insertions, 0 deletions

diff --git a/amd.html.markdown b/amd.html.markdown
new file mode 100644
index 00000000..d7fb41ba
--- /dev/null
+++ b/amd.html.markdown
@@ -0,0 +1,212 @@
+---

+category: tool

+tool: amd

+contributors:

+    - ["Frederik Ring", "https://github.com/m90"]

+filename: learnamd.js

+---

+

+## Getting Started with AMD

+

+The **Asynchronous Module Definition** API specifies a mechanism for defining

+JavaScript modules such that the module and its dependencies can be asynchronously

+loaded. This is particularly well suited for the browser environment where

+synchronous loading of modules incurs performance, usability, debugging, and

+cross-domain access problems.

+

+### Basic concept

+```javascript

+// The basic AMD API consists of nothing but two methods: `define` and `require`

+// and is all about module definition and consumption:

+// `define(id?, dependencies?, factory)` defines a module

+// `require(dependencies, callback)` imports a set of dependencies and

+// consumes them in the passed callback

+

+// Let's start by using define to define a new named module

+// that has no dependencies. We'll do so by passing a name

+// and a factory function to define:

+define('awesomeAMD', function(){

+  var isAMDAwesome = function(){

+    return true;

+  };

+  // The return value of a module's factory function is

+  // what other modules or require calls will receive when

+  // requiring our `awesomeAMD` module.

+  // The exported value can be anything, (constructor) functions,

+  // objects, primitives, even undefined (although that won't help too much).

+  return isAMDAwesome;

+});

+

+// Now, let's define another module that depends upon our `awesomeAMD` module.

+// Notice that there's an additional argument defining our

+// module's dependencies now:

+define('loudmouth', ['awesomeAMD'], function(awesomeAMD){

+  // dependencies will be passed to the factory's arguments

+  // in the order they are specified

+  var tellEveryone = function(){

+    if (awesomeAMD()){

+      alert('This is sOoOo rad!');

+    } else {

+      alert('Pretty dull, isn\'t it?');

+    }

+  };

+  return tellEveryone;

+});

+

+// As we do know how to use define now, let's use `require` to

+// kick off our program. `require`'s signature is `(arrayOfDependencies, callback)`.

+require(['loudmouth'], function(loudmouth){

+  loudmouth();

+});

+

+// To make this tutorial run code, let's implement a very basic

+// (non-asynchronous) version of AMD right here on the spot:

+function define(name, deps, factory){

+  // notice how modules without dependencies are handled

+  define[name] = require(factory ? deps : [], factory || deps);

+}

+

+function require(deps, callback){

+  var args = [];

+  // first let's retrieve all the dependencies needed

+  // by the require call

+  for (var i = 0; i < deps.length; i++){

+    args[i] = define[deps[i]];

+  }

+  // satisfy all the callback's dependencies

+  return callback.apply(null, args);

+}

+// you can see this code in action here: http://jsfiddle.net/qap949pd/

+```

+

+### Real-world usage with require.js

+

+In contrast to the introductory example, `require.js` (the most popular AMD library) actually implements the **A** in **AMD**, enabling you to load modules and their dependencies asynchronously via XHR:

+

+```javascript

+/* file: app/main.js */

+require(['modules/someClass'], function(SomeClass){

+  // the callback is deferred until the dependency is loaded

+  var thing = new SomeClass();

+});

+console.log('So here we are, waiting!'); // this will run first

+```

+

+By convention, you usually store one module in one file. `require.js` can resolve module names based on file paths, so you don't have to name your modules, but can simply reference them using their location. In the example `someClass` is assumed to be in the `modules` folder, relative to your configuration's `baseUrl`:

+

+* app/

+  * main.js

+  * modules/

+    * someClass.js

+    * someHelpers.js

+    * ...

+  * daos/

+    * things.js

+    * ...

+

+This means we can define `someClass` without specifying a module id:

+

+```javascript

+/* file: app/modules/someClass.js */

+define(['daos/things', 'modules/someHelpers'], function(thingsDao, helpers){

+  // module definition, of course, will also happen asynchronously

+  function SomeClass(){

+    this.method = function(){/**/};

+    // ...

+  }

+  return SomeClass;

+});

+```

+To alter the default path mapping behavior use `requirejs.config(configObj)` in your `main.js`:

+

+```javascript

+/* file: main.js */

+requirejs.config({

+  baseUrl : 'app',

+  paths : {

+    // you can also load modules from other locations

+    jquery : '//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min',

+    coolLibFromBower : '../bower_components/cool-lib/coollib'

+  }

+});

+require(['jquery', 'coolLibFromBower', 'modules/someHelpers'], function($, coolLib, helpers){

+  // a `main` file needs to call require at least once,

+  // otherwise no code will ever run

+  coolLib.doFancyStuffWith(helpers.transform($('#foo')));

+});

+```

+`require.js`-based apps will usually have a single entry point (`main.js`) that is passed to the `require.js` script tag as a data-attribute. It will be automatically loaded and executed on pageload:

+

+```html

+<!DOCTYPE html>

+<html>

+<head>

+  <title>A hundred script tags? Never again!</title>

+</head>

+<body>

+  <script src="require.js" data-main="app/main"></script>

+</body>

+</html>

+```

+

+### Optimizing a whole project using r.js

+

+Many people prefer using AMD for sane code organization during development, but still want to ship a single script file in production instead of performing hundreds of XHRs on page load.

+

+`require.js` comes with a script called `r.js` (that you will probably run in node.js, although Rhino is supported too) that can analyse your project's dependency graph, and build a single file containing all your modules (properly named), minified and ready for consumption.

+

+Install it using `npm`:

+```shell

+$ npm install requirejs -g

+```

+

+Now you can feed it with a configuration file:

+```shell

+$ r.js -o app.build.js

+```

+

+For our above example the configuration might look like:

+```javascript

+/* file : app.build.js */

+({

+  name : 'main', // name of the entry point

+  out : 'main-built.js', // name of the file to write the output to

+  baseUrl : 'app',

+  paths : {

+    // `empty:` tells r.js that this should still be loaded from the CDN, using

+    // the location specified in `main.js`

+    jquery : 'empty:',

+    coolLibFromBower : '../bower_components/cool-lib/coollib'

+  }

+})

+```

+

+To use the built file in production, simply swap `data-main`:

+```html

+<script src="require.js" data-main="app/main-built"></script>

+```

+

+An incredibly detailed [overview of build options](https://github.com/jrburke/r.js/blob/master/build/example.build.js) is available in the GitHub repo.

+

+### Topics not covered in this tutorial

+* [Loader plugins / transforms](http://requirejs.org/docs/plugins.html)

+* [CommonJS style loading and exporting](http://requirejs.org/docs/commonjs.html)

+* [Advanced configuration](http://requirejs.org/docs/api.html#config)

+* [Shim configuration (loading non-AMD modules)](http://requirejs.org/docs/api.html#config-shim)

+* [CSS loading and optimizing with require.js](http://requirejs.org/docs/optimization.html#onecss)

+* [Using almond.js for builds](https://github.com/jrburke/almond)

+

+### Further reading:

+

+* [Official Spec](https://github.com/amdjs/amdjs-api/wiki/AMD)

+* [Why AMD?](http://requirejs.org/docs/whyamd.html)

+* [Universal Module Definition](https://github.com/umdjs/umd)

+

+### Implementations:

+

+* [require.js](http://requirejs.org)

+* [dojo toolkit](http://dojotoolkit.org/documentation/tutorials/1.9/modules/)

+* [cujo.js](http://cujojs.com/)

+* [curl.js](https://github.com/cujojs/curl)

+* [lsjs](https://github.com/zazl/lsjs)

+* [mmd](https://github.com/alexlawrence/mmd)