Permalink
Browse files

Doc updates.

  • Loading branch information...
1 parent 427f755 commit eedb718748ef242429d4951da987ff0e116d0684 @jrburke jrburke committed Sep 30, 2011
Showing with 77 additions and 36 deletions.
  1. +15 −14 README.md
  2. +10 −5 docs/api.html
  3. +43 −2 docs/faq-optimization.html
  4. +2 −0 docs/optimization.html
  5. +7 −15 tasks.txt
View
@@ -2,35 +2,35 @@
RequireJS loads plain JavaScript files as well as more defined modules. It is
optimized for in-browser use, including in
-[a Web Worker](requirejs/tree/master/docs/api.md#webworker), but it can be used
+[a Web Worker](http://requirejs.org/docs/api.html#webworker), but it can be used
in other JavaScript environments, like Rhino and
-[Node](requirejs/tree/master/docs/node.md). It implements the
-[Asynchronous Module](http://wiki.commonjs.org/wiki/Modules/AsynchronousDefinition)
+[Node](http://requirejs.org/docs/node.html). It implements the
+[Asynchronous Module](https://github.com/amdjs/amdjs-api/wiki/AMD)
API.
RequireJS uses plain script tags to load modules/files, so it should allow for
easy debugging. It can be used
-[simply to load existing JavaScript files](requirejs/tree/master/docs/api.md#jsfiles),
+[simply to load existing JavaScript files](http://requirejs.org/docs/api.html#jsfiles),
so you can add it to your existing project without having to re-write your
JavaScript files.
-RequireJS includes [an optimization tool](requirejs/tree/master/docs/optimization.md)
+RequireJS includes [an optimization tool](http://requirejs.org/docs/optimization.html)
you can run as part of your packaging steps for deploying your code. The
optimization tool can combine and minify your JavaScript files to allow for
better performance.
If the JavaScript file defines a JavaScript module via
-[define()](requirejs/tree/master/docs/api.md#define), then there are other benefits
-RequireJS can offer: [better CommonJS support](requirejs/tree/master/docs/commonjs.md)
-and [loading multiple versions](requirejs/tree/master/docs/api.md#multiversion)
+[define()](http://requirejs.org/docs/api.html#define), then there are other benefits
+RequireJS can offer: [improvements over traditional CommonJS modules](http://requirejs.org/docs/commonjs.html)
+and [loading multiple versions](http://requirejs.org/docs/api.html#multiversion)
of a module in a page. RequireJS also has a plugin system that supports features like
-[i18n string bundles](requirejs/tree/master/docs/api.md#i18n), and
-[text file dependencies](requirejs/tree/master/docs/api.md#text).
+[i18n string bundles](http://requirejs.org/docs/api.html#i18n), and
+[text file dependencies](http://requirejs.org/docs/api.html#text).
RequireJS does not have any dependencies on a JavaScript framework.
It is dual-licensed -- new BSD or MIT.
-The standard require.js file is around 5KB when minified via Closure Compiler
+The standard require.js file is around 5.5KB when minified via Closure Compiler
and gzipped.
RequireJS works in IE 6+, Firefox 2+, Safari 3.2+, Chrome 3+, and Opera 10+.
@@ -55,6 +55,7 @@ from each other and from require.js. They are included in this repo because
some of the tests depend on them. At some point they may be separated out into
separate projects.
-*i18n.js
-*order.js
-*text.js
+* i18n.js
+* order.js
+* text.js
+* domReady.js
View
@@ -125,8 +125,6 @@ <h3>
<p>There should only be <strong>one</strong> module definition per file on disk. The modules can be grouped into optimized bundles by the <a href="optimization.html">optimization tool</a>.</p>
-<span class="note">Note: As of RequireJS 0.14.3, the function <strong>define()</strong> is preferred to create modules. Previously it was <strong>require.def()</strong>. require.def is still available, but define() is encouraged because it conforms to the <a href="http://wiki.commonjs.org/wiki/Modules/AsynchronousDefinition">Asynchronous Module Proposal</a>. You are free to continue using require.def() if you only want RequireJS to load the modules, but if you want your code to be potentially interoperable with other Async Module script loaders, you should consider using define(). Any API examples that use define() will work the same if require.def() is used instead.</span>
-
<div class="subSection">
<h4>
<a name="defsimple">Simple Name/Value Pairs</a>
@@ -260,9 +258,9 @@ <h4><a name="modulename">Define a Module with a Name</a><span class="sectionMark
<h4><a name="modulenotes">Other Module Notes</a><span class="sectionMark">&sect; 1.2.7</span></h4>
-<p><strong>One module per file.</strong>: Only one module should be defined per JavaScript file, given the nature of the module name-to-file-path lookup algorithm. Multiple modules will be grouped into optimized files by the <a href="optimization.html">optimization tool</a>, but you should only use the optimization tool to place more than one module in a file.</p>
+<p id="modulenotes-onemodule"><strong>One module per file.</strong>: Only one module should be defined per JavaScript file, given the nature of the module name-to-file-path lookup algorithm. Multiple modules will be grouped into optimized files by the <a href="optimization.html">optimization tool</a>, but you should only use the optimization tool to place more than one module in a file.</p>
-<p><strong>Relative module names inside define()</strong>: For require("./relative/name") calls that can happen inside a define() function call, be sure to ask for "require" as a dependency, so that the relative name is resolved correctly:</p>
+<p id="modulenotes-relative"><strong>Relative module names inside define()</strong>: For require("./relative/name") calls that can happen inside a define() function call, be sure to ask for "require" as a dependency, so that the relative name is resolved correctly:</p>
<pre><code>define(["require", "./relative/name"], function(require) {
var mod = require("./relative/name");
@@ -278,7 +276,14 @@ <h4><a name="modulenotes">Other Module Notes</a><span class="sectionMark">&sect;
<p>This form will use Function.prototype.toString() to find the require() calls, and add them to the dependency array, along with "require", so the code will work correctly with relative paths.</p>
-<p><strong>Console debugging</strong>: If you need to work with a module you already loaded via a require(["module/name"], function(){}) call in the JavaScript console, then you can use the require() form that just uses the string name of the module to fetch it:</p>
+<p id="modulenotes-urls"><strong>Generate URLs relative to module</strong>: You may need to generate an URL that is relative to a module. To do so, ask for "require" as a dependency and then use require.toUrl() to generate the URL:</p>
+
+<pre><code>define(["require"], function(require) {
+ var cssUrl = require.toUrl("./style.css");
+});
+</code></pre>
+
+<p id="modulenotes-console"><strong>Console debugging</strong>: If you need to work with a module you already loaded via a require(["module/name"], function(){}) call in the JavaScript console, then you can use the require() form that just uses the string name of the module to fetch it:</p>
<pre><code>require("module/name").callSomeFunction()
</code></pre>
View
@@ -2,7 +2,9 @@
<h1>FAQ: RequireJS Optimizations</h1>
<ul class="index mono">
<li class="hbox"><a href="#usage">How do I use the Optimization Tool?</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1</span></li>
-<li class="hbox"><a href="#priority">How can I download all script dependencies in parallel?</a><span class="spacer boxFlex"></span><span class="sect">&sect; 2</span></li>
+<li class="hbox"><a href="#wrap">How can I provide a library to others that does not depend on RequireJS?</a><span class="spacer boxFlex"></span><span class="sect">&sect; 2</span></li>
+<li class="hbox"><a href="#namespace">How can I namespace my code to play well in other people's pages?</a><span class="spacer boxFlex"></span><span class="sect">&sect; 3</span></li>
+<li class="hbox"><a href="#priority">How can I download all script dependencies in parallel?</a><span class="spacer boxFlex"></span><span class="sect">&sect; 4</span></li>
</ul>
</div>
@@ -12,8 +14,47 @@ <h2><a name="usage">How do I use the Optimization Tool?</a><span class="sectionM
<p>See the <a href="optimization.html">general optimization page</a> for basic set-up. Also see the <a href="jquery.html">jQuery doc page</a> for a good way to set up your project, even if you are not using jQuery.</p>
</div>
+
+<div class="section">
+<h2><a name="wrap">How can I provide a library to others that does not depend on RequireJS?</a><span class="sectionMark">&sect; 2</span></h2>
+
+<p>If you are building a library for use on web pages that may not use RequireJS or an AMD loader, you can use the optimizer to combine
+all your modules into one file, then wrap them in a function and use an AMD API shim. This allows you to ship code that does not ship with all
+of RequireJS, and allows you to export any kind of API that works on a plain web page without an AMD loader.</p>
+
+<p><a href="https://github.com/jrburke/almond">almond</a> is an AMD API shim that is very small, so it can be used in place of require.js
+when all of your modules are built into one file using the RequireJS optimizer. The
+<a href="https://github.com/jrburke/r.js/blob/master/build/example.build.js#L244">wrap</a> build config option allows specifying a function
+wrapper around the code, or you can provide your own wrapper if you need to do extra logic.</p> See the almond project for details on how to
+build with the API shim and with wrap.</p>
+
+<p>If you need to dynamically load code even after a build, then using almond+wrap will not be sufficient as almond cannot dynamically
+load code. Instead, you mean want to namespace your use of require/define. See next section.</p>
+</div>
+
+<div class="section">
+<h2><a name="namespace">How can I namespace my code to play well in other people's pages?</a><span class="sectionMark">&sect; 3</span></h2>
+
+<p>You may want to provide your code to web sites that may or may not use an AMD loader, and you need to dynamically load code,
+so doing a simple <a href="#wrap">one file build with a wrapper</a> is not enough.</p>
+
+<p>There is a <a href="https://github.com/jrburke/r.js/blob/master/build/example.build.js#L159">namespace</a> build option that
+does the following:</p>
+
+<ul>
+ <li>Renames requirejs, require and define uses to have "namespace." in front of them.</li>
+ <li>If the file does an existence check for define, in the following form <code>typeof define === 'function' && define.amd</code>,
+ then it will prefix the define references with "namespace.".</li>
+ <li>If require.js is included in the built file, it will make sure it exposes the "namespace." versions of the API.</li>
+</ul>
+
+<p>Do not code your source with namespace.require()/namespace.define() calls, but rather use require()/define() as you
+normally would, then use the optimizer to do the renaming.</p>
+
+</div>
+
<div class="section">
-<h2><a name="priority">How can I download all script dependencies in parallel?</a><span class="sectionMark">&sect; 2</span></h2>
+<h2><a name="priority">How can I download all script dependencies in parallel?</a><span class="sectionMark">&sect; 4</span></h2>
<p>Using <a href="">require()</a> and <a href="api.html#define">define()</a> to define script modules and dependencies is an efficient syntax for indicating related code. However, for deploying code in the browser, it may not lead to the best overall performance. To find nested dependencies, a script has to be fetched, then a require() or define() call in that script might trigger other script downloads.</p>
View
@@ -161,6 +161,8 @@ <h2>
<p>Since "require" is a reserved dependency name, you create a "requireLib" dependency and map it to the require.js file.</p>
<p>Once that optimization is done, you can then rename the main-built.js file to require.js and your optimized project will only need to make one script request.</p>
+
+<p>If you want to wrap your built file so it can be used in pages that do not have an AMD loader like RequireJS, see the <a href="faq-optimization.html">Optimization FAQ</a>.</p>
</div>
<div class="section">
View
@@ -2,7 +2,8 @@ Release Notes
-------------------
- removed module.setExports support.
- removed require.def support
-- removed require.ready, domReady now.
+- removed require.ready, domReady plugin.
+- mention almond release?
Next release
--------------
@@ -12,30 +13,18 @@ Next release
- mix of types a problem? https://github.com/jrburke/require-cs/issues/5
-- Put in common error for r.js error:
-When I try to build my project (optimize with r.js), it fails with
-following error message: "Error: Path is not supported: http://some.path.org"
-Explain that mappings to empty: can be used.
-
-- clarify commonjs wrapping in amd api page.
-- add amd test for dynamic that uses commonjs wrapper, remove dynamic from list of APIs require.js supports.
+- almond release: look at splice change
- document wrap usage, faq-advanced, mention on optimization page for single file.
-- Fix README.md's links and formatting.
-
-- Document text.useXhr override, how it deals with xdomain resources.
-
-- New API section: how to generate URLs relative to a module.
-
- Update docs about plugins have dependencies, note that the dependencies
should be able to execute ideally in node and java environments, or whatever
env the developer is targeting for a build.
- For plugins: document writeFile and writeFile.asModule(moduleName, fileName, contents)
-- test rflorence changes to things like bonzo
+- test rflorence changes to things like bonzo: https://github.com/ded/bonzo/issues/32
- Overriding modules used in r.js? https://github.com/jrburke/r.js/issues/24
@@ -45,6 +34,9 @@ Explain that mappings to empty: can be used.
--------------
+- clarify commonjs wrapping in amd api page.
+- add amd test for dynamic that uses commonjs wrapper, remove dynamic from list of APIs require.js supports.
+
- has() source trimming, needs brace matching?

0 comments on commit eedb718

Please sign in to comment.