docs/module-definition.html

<!doctype html>
<html>
<head>
<meta http-equiv="Pragma" content="no-cache"/>
<meta charset="utf-8"/>
<title>Module Definition - Sea.js Manual &amp; Documentation</title>
<link rel="stylesheet" href="assets/api.css"/>
</head>
<body>
<div id="container">

  <header>
    <h1>Sea.js Manual &amp; Documentation</h1>
    <div id="gtoc">
      <p><a href="../">Home</a> | <a href="index.html">Index</a></p>
    </div>
    <hr/>
  </header>

  <div id="toc">
    <h2 id="table_of_Contents">Table of Contents</h2>

    <ul>
      <li><a href="#module-definition">Module Definition</a>
        <ul>
          <li><a href="#define">define</a>
            <ul>
              <li><a href="#define-id">id</a></li>
              <li><a href="#define-dependencies">dependencies</a></li>
              <li><a href="#define-factory">factory</a></li>
            </ul>
          </li>
          <li><a href="#exports">exports</a></li>
          <li><a href="#require">require</a>
            <ul>
              <li><a href="#require-async">require.async</a></li>
              <li><a href="#require-resolve">require.resolve</a></li>
              <li><a href="#require-load">require.load</a></li>
              <li><a href="#require-constructor">require.constructor</a></li>
            </ul>
          </li>
          <li><a href="#module">module</a>
            <ul>
              <li><a href="#module-id">module.id</a></li>
              <li><a href="#module-dependencies">module.dependencies</a></li>
              <li><a href="#module-exports">module.exports</a></li>
              <li><a href="#module-constructor">module.constructor</a></li>
            </ul>
          </li>
        </ul>
      </li>
    </ul>
    <hr/>
  </div>


  <h2 id="module-definition">Module Definition</h2>

  <p>
    In SeaJS, any JavaScript file should be written in module format, and files
    and modules are in one-to-one correspondence.
  </p>

  
  <h3 id="define">define</h3>

  <p>
    A global function "define" is available to define modules. The signature of
    this function is:
  </p>

<pre>
define(id?, dependencies?, factory);
</pre>


  <h4 id="define-id">id</h4>

  <p>
    The unique identifier for the current module. This argument is optional,
    and if it is not present, the loader will set the module id to the request
    uri of this module file. When present, the module id MUST be a top-level
    or absolute id (relative ids are NOT allowed).
  </p>


  <h4 id="define-dependencies">dependencies</h4>

  <p>
    The module’s dependency array which is an array of module identifiers. This
    argument is optional. If it is not present, the loader will parse the
    <code>factory.toString()</code> to extract the dependency.
  </p>


  <p>
    ** NOTICE: It is highly recommended to ignore the <code>id</code> and
    <code>dependencies</code> arguments in the define statement. The
    optimization tool will generate these arguments automatically in the
    deployment phase.
  </p>


  <h4 id="define-factory">factory</h4>

  <p>
    A function that will be executed only once to initialize the module. In
    addition to a function, the factory argument can also be an object, a
    string, or any other value, and in those case, the module exports are set to
    the factory value directly.
  </p>

  <p>
    Three symbols are available in the function body of factory to every module:
    <code>require</code>, <code>exports</code>, and <code>module</code>.
  </p>

<pre>
define(function(require, exports, module) {

  // The module code goes here
  
});
</pre>


  <h3 id="exports">exports</h3>

  <p>
    The <code>exports</code> object is used to export the API of the module.
  </p>

<pre>
define(function(require, exports) {
  // snip...
  exports.foo = 'bar';
  exports.doSomething = function() {};
});
</pre>

  <p>
    Except adding members to the <code>exports</code> object, you can also use
    <code>return</code> to provide the API directly.
  </p>

<pre>
define(function(require) {
  // snip...
  return {
    foo: 'bar'，
    doSomething: function() {};
  };
});
</pre>

  <p>
    If the <code>return</code> statement is the only code in the module code,
    it can be simplified to:
  </p>

<pre>
define({
  foo: 'bar'，
  doSomething: function() {};
});
</pre>

  <p>
    The above authoring format is especially suited for defining JSON data.
  </p>

  <p>
    ** ATTENTION: The following code DOES NOT work!
  </p>

<pre class="wrong">
define(function(require, exports) {
  // snip...
  exports = { // WRONG!
    foo: 'bar'，
    doSomething: function() {};
  };
});
</pre>

  <p>
    The module loader cannot obtain the new value assigned to the
    <code>exports</code> variable. Please use <code>return</code> or
    <code>module.exports</code> to expose the API in this case.
  </p>


  <h3 id="require">require</h3>

  <p>
    The <code>require</code> function is used to access the exported API of
    foreign modules.
  </p>

<pre>
define(function(require) {
  var a = require('./a');
  a.doSomething();
});
</pre>

  <p>
    It accepts a single <a href="module-identifier.html">module identifier</a>
    as parameter.
  </p>

  <p>
    Keep in mind that you'll need to follow a few simple
    <a href="rules.html">rules</a> to make sure that static analysis
    will be able to detect the dependencies within your module in the
    development phase.
  </p>


  <h4 id="require-async">require.async</h4>

  <p>
    Use this function to load the specified modules asynchronously and execute
    the optional callback when complete.
  </p>

<pre>
define(function(require, exports) {
  // load one module
  require.async('./b', function(b) {
    b.doSomething();
  });
  
  // load multiple modules
  require.async(['./c', './d'], function(c, d) {
    // do something
  });
});
</pre>


  <h4 id="require-resolve">require.resolve</h4>

  <p>
    Use the internal <code>require()</code> machinery to look up the location
    of a module, but rather than loading the module, just return the resolved
    uri.
  </p>


  <h4 id="require-load">require.load</h4>

  <p>
    Use this function to fetch the specified uris asynchronously and execute
    the optional callback when complete. You can override this function to
    implement custom fetching method.
  </p>


  <h4 id="require-constructor">require.constructor</h4>

  <p>
    Occasionally, we want to add some members to the <code>require</code>
    argument in all module factories. In this case, using
    <code>require.constructor</code> is very convenient.
  </p>


  <h3 id="module">module</h3>

  <p>
    The module object contains metadata about the module. It contains the
    following members:
  </p>


  <h4 id="module-id">module.id</h4>

  <p>
    The unique identifier for the current module.
    <code>require(module.id)</code> must return this module’s exports object.
  </p>

<pre>
define(function(require, exports, module) {
  console.log(module.id); // http://path/to/this/file.js
  console.log(require(module.id) === exports); // true
});
</pre>


  <h4 id="module-dependencies">module.dependencies</h4>

  <p>
    <code>module.dependencies</code> is a reference to the module’s dependency
    array.
  </p>

  <p>This array is informative only: modification of this array has no
    effect on the module once the module has been provided to the environment.
  </p>


  <h4 id="module-exports">module.exports</h4>

  <p>
    The <code>exports</code> object is created by the module system. Sometimes
    this is not acceptable, many want their module to be an instance of some
    class. To do this assign the desired export object to
    <code>module.exports</code>.
  </p>

<pre>
define(function(require, exports, module) {
  console.log(module.exports === exports); // true
  module.exports = new SomeClass();
  console.log(module.exports === exports); // false
});
</pre>

  <p>
    Note that assignment to <code>module.exports</code> must be done
    immediately. It cannot be done in any callbacks. This does not work:
  </p>

  <p>x.js:</p>

<pre>
define(function(require, exports, module) {
  setTimeout(function() {
    module.exports = { a: "hello" };
  }, 0);
});
</pre>

  <p>y.js:</p>

<pre>
define(function(require, exports, module) {
  var x = require('./x');
  console.log(x.a); // undefined
});
</pre>


  <h4 id="module-constructor">module.constructor</h4>

  <p>
    Occasionally, we want to add some members to all <code>module</code>
    objects. In this case, using <code>module.constructor</code> is very
    convenient.
  </p>

  <p>extend.js:</p>

<pre>
define(function(require, exports, module) {
  var Module = module.constructor;

  Module.prototype.filename = function() {
    var id = this.id;
    var parts = id.split('/');
    return parts[parts.length - 1];
  };
});
</pre>

  <p>a.js:</p>

<pre>
define(function(require, exports, module) {
  exports.filename = module.filename();
});
</pre>


</div>

<script src="../build/sea.js" data-main="assets/init"></script>

</body>
</html>