Skip to content
This repository
Browse code

More doc updates.

  • Loading branch information...
commit 80772e8cc8338e7546990f07c896161410a3b7c9 1 parent f833882
James Burke authored
30 docs/api.html
@@ -16,6 +16,7 @@
16 16 <li class="hbox"><a href="#modulenotes">Other Module Notes</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1.2.7</span></li>
17 17 <li class="hbox"><a href="#circular">Circular Dependencies</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1.2.8</span></li>
18 18 <li class="hbox"><a href="#jsonp">Specify a JSONP Service Dependency</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1.2.9</span></li>
  19 + <li class="hbox"><a href="#undef">Undefining a Module</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1.2.10</span></li>
19 20
20 21 </ul>
21 22 </ul>
@@ -402,6 +403,24 @@
402 403
403 404 </div>
404 405
  406 +
  407 +<div class="subSection">
  408 +<h4><a href="#undef" name="jsonp">Undefining a Module</a><span class="sectionMark">&sect; 1.2.10</span></h4>
  409 +
  410 +<p>There is a global function, <b>requirejs.undef()</b>, that allows undefining a module. It will reset the
  411 +loader's internal state to forget about the previous definition of the module.</p>
  412 +
  413 +<p><b>However</b>, it will not remove the module from other modules that are already defined and got a
  414 +handle on that module as a dependency when they executed.</p>. So it is really only useful to use in
  415 +error situations when no other modules have gotten a handle on a module value, or as part of any future
  416 +module loading that may use that module. See the <a href="#errbacks">errback section</a> for an example.</p>
  417 +
  418 +<p>If you want to do more sophisticated dependency graph analysis for undefining work, the semi-private
  419 +<a href="https://github.com/jrburke/requirejs/wiki/Internal-API:-onResourceLoad">onResourceLoad API</a> may be helpful.</p>
  420 +
  421 +</div>
  422 +
  423 +
405 424 </div>
406 425
407 426 <div class="section">
@@ -539,6 +558,13 @@
539 558 });
540 559 </code></pre>
541 560
  561 +<p>Some important optimizer notes when using "shim" config:</p>
  562 +
  563 +<ul>
  564 + <li>You should use the [**mainConfigFile** build option](optimization.html#mainConfigFile) to specify the file where to find the shim config. Otherwise the optimizer will not know of the shim config. The other option is to duplicate the shim config in the build profile.</li>
  565 + <li>Do not mix CDN loading with shim config in a build. Example scenario: you load jQuery from the CDN but use the shim config to load something like the stock version of Backbone that depends on jQuery. When you do the build, be sure to inline jQuery in the built file and do not load it from the CDN. Otherwise, Backbone will be inlined in the built file and it will execute before the CDN-loaded jQuery will load. This is because the shim config just delays loading of the files until dependencies are loaded, but does not do any auto-wrapping of define. After a build, the dependencies are already inlined, the shim config cannot delay execution of the non-define()'d code until later. define()'d modules do work with CDN loaded code after a build because they properly wrap their source in define factory function that will not execute until dependencies are loaded. So the lesson: shim config is a stop-gap measure for for non-modular code, legacy code. define()'d modules are better.</li>
  566 +</ul>
  567 +
542 568 <p id="config-map"><strong><a href="config-map">map</a></strong>: For the given module prefix, instead of loading the module with the given ID, substitute a different module ID.</p>
543 569
544 570 <p>This sort of capability is really important for larger projects which may have
@@ -873,7 +899,7 @@
873 899
874 900 <p>So it is very difficult with IE to allow both anonymous AMD modules, which are a core benefit of AMD modules, and reliable detect errors.</p>
875 901
876   -<p>However, if you are in a project that you know uses define() to declare all of its modules, or it uses the <a href="#config-shim">shim</a> config to specify string exports for anything that does not use define(), then if you set the <b>enforceDefine</b> config value to true, the loader can confirm if a script load by checking for the define() call or the existence of the shim's exports global value.</p>
  902 +<p>However, if you are in a project that you know uses define() to declare all of its modules, or it uses the <a href="#config-shim">shim</a> config to specify string exports for anything that does not use define(), then if you set the <a href="#config-enforceDefine">enforceDefine</a> config value to true, the loader can confirm if a script load by checking for the define() call or the existence of the shim's exports global value.</p>
877 903
878 904 <p>So if you want to support Internet Explorer, catch load errors, and have modular code either through direct define() calls or shim config, always set <b>enforceDefine</b> to be true. See the next section for an example.</p>
879 905
@@ -882,7 +908,7 @@
882 908 <span class="sectionMark">&sect; 4.6.2</span>
883 909 </h4>
884 910
885   -<p>Errbacks, when used with requirejs.undef(), will allow you to detect if a module fails to load, undefine
  911 +<p>Errbacks, when used with <a href="#undef">requirejs.undef()</a>, will allow you to detect if a module fails to load, undefine
886 912 that module, reset the config to a another location, then try again.</p>
887 913
888 914 <p>A common use case for this is to use a CDN-hosted version of a library, but if
53 docs/errors.html
@@ -7,8 +7,10 @@
7 7 <li class="hbox"><a href="#defineerror">Error evaluating module ...</a><span class="spacer boxFlex"></span><span class="sect">&sect; 3</span></li>
8 8 <li class="hbox"><a href="#notloaded">Module name ... has not been loaded yet for context: ...</a><span class="spacer boxFlex"></span><span class="sect">&sect; 4</span></li>
9 9 <li class="hbox"><a href="#requireargs">Invalid require call</a><span class="spacer boxFlex"></span><span class="sect">&sect; 5</span></li>
10   -<li class="hbox"><a href="#interactive">No matching script interactive for ...</a><span class="spacer boxFlex"></span><span class="sect">&sect; 6</span></li>
11   -<li class="hbox"><a href="#pathnotsupported">Path is not supported: ...</a><span class="spacer boxFlex"></span><span class="sect">&sect; 7</span></li>
  10 +<li class="hbox"><a href="#nodefine">No define call for ...</a><span class="spacer boxFlex"></span><span class="sect">&sect; 6</span></li>
  11 +<li class="hbox"><a href="#scripterror">Script error</a><span class="spacer boxFlex"></span><span class="sect">&sect; 7</span></li>
  12 +<li class="hbox"><a href="#interactive">No matching script interactive for ...</a><span class="spacer boxFlex"></span><span class="sect">&sect; 8</span></li>
  13 +<li class="hbox"><a href="#pathnotsupported">Path is not supported: ...</a><span class="spacer boxFlex"></span><span class="sect">&sect; 8</span></li>
12 14 </ul>
13 15
14 16 <p>This page lists errors that are generated by RequireJS. If the following information does not fix the problem, you can ask on the <a href="https://groups.google.com/group/requirejs">RequireJS list</a> or <a href="https://github.com/jrburke/requirejs/issues">open an issue</a>. In either case it is best to have an example or detailed explanation of the problem, hopefully with steps to reproduce.</p>
@@ -101,7 +103,7 @@
101 103
102 104
103 105 <div class="section">
104   -<h2><a name="requireargs">Invalid require call</a><span class="sectionMark">&sect; 4</span></h2>
  106 +<h2><a name="requireargs">Invalid require call</a><span class="sectionMark">&sect; 5</span></h2>
105 107
106 108 <p>This occurs when there is is a call like:</p>
107 109
@@ -115,8 +117,49 @@
115 117
116 118 </div>
117 119
  120 +
  121 +<div class="section">
  122 +<h2><a name="nodefine">No define call for ...</a><span class="sectionMark">&sect; 6</span></h2>
  123 +
  124 +<p>This occurs when <a href="api.html##config-enforceDefine">enforceDefine is set to true</a>, and a script that is loaded either:</p>
  125 +
  126 +<ul>
  127 + <li>Did not call define() to declare a module.</li>
  128 + <li>Or was part of a <a href="api.html#config-shim">shim config</a> that specified
  129 + a global string property that can be checked for loading, and that check failed.</li>
  130 +</ul>
  131 +
  132 +<p>Or, if the error shows up only in IE and not in other browsers (which may generate a <a href="#scripterror">Script error</a>, the script probably:</p>
  133 +
  134 +<ul>
  135 + <li>Threw a JavaScript syntax/evaluation error.</li>
  136 + <li>Or there was a 404 error in IE where the script failed to load.</li>
  137 +</ul>
  138 +
  139 +<p>Those IE behaviors result in <a href="api.html#ieloadfail">IE's quirks in detecting script errors</a>.</p>
  140 +
  141 +<p>To fix it:</p>
  142 +
  143 +<ul>
  144 + <li>If the module calls define(), make sure the define call was reached by debugging in a script debugger.</li>
  145 + <li>If part of a shim config, make sure the shim config's exports check is correct.</li>
  146 + <li>If in IE, check for an HTTP 404 error or a JavaScript sytnax error by using a script debugger.</li>
  147 +</ul>
  148 +
  149 +</div>
  150 +
  151 +<div class="section">
  152 +<h2><a name="scripterror">Script error</a><span class="sectionMark">&sect; 7</span></h2>
  153 +
  154 +<p>This occurs when the script.onerror function is triggered in a browser. This usually means there is a JavaScript syntax error or other execution problem running the script. To fix it, examine the script that generated the error in a script debugger.</p>
  155 +
  156 +<p>This error may not show up in IE, just other browsers, and instead, in IE you may see the <a href="#nodefine">No define call for ...</a> error when you see "Script error". This is due to <a href="api.html#ieloadfail">IE's quirks in detecting script errors</a>.</p>
  157 +
  158 +</div>
  159 +
  160 +
118 161 <div class="section">
119   -<h2><a name="interactive">No matching script interactive for ...</a><span class="sectionMark">&sect; 6</span></h2>
  162 +<h2><a name="interactive">No matching script interactive for ...</a><span class="sectionMark">&sect; 8</span></h2>
120 163
121 164 <p>This error only shows up in some IE browsers. Most likely caused by loading a script that calls define() but was loaded in a plain script tag or via some other call, like an eval() of a JavaScript string.</p>
122 165
@@ -125,7 +168,7 @@
125 168 </div>
126 169
127 170 <div class="section">
128   -<h2><a name="pathnotsupported">Path is not supported: ...</a><span class="sectionMark">&sect; 7</span></h2>
  171 +<h2><a name="pathnotsupported">Path is not supported: ...</a><span class="sectionMark">&sect; 9</span></h2>
129 172
130 173 <p>This error occurs when the optimizer encounters a path to a module or script which is a network path. The optimizer only allows
131 174 building with local resources. To fix it:</p>
124 docs/faq-optimization.html
@@ -4,7 +4,6 @@
4 4 <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>
5 5 <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>
6 6 <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>
7   -<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>
8 7 </ul>
9 8 </div>
10 9
@@ -54,126 +53,3 @@
54 53 normally would, then use the optimizer to do the renaming.</p>
55 54
56 55 </div>
57   -
58   -<div class="section">
59   -<h2><a name="priority">How can I download all script dependencies in parallel?</a><span class="sectionMark">&sect; 4</span></h2>
60   -
61   -<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>
62   -
63   -<p>The <a href="optimization.html">Optimization Tool</a> allows a quick way to <a href="optimization.html#onejs">build all your scripts into one file</a>, so only one script download is needed for your page.</p>
64   -
65   -<p>However, if you have many pages in your web app, it may make more sense to optimize your scripts into a set of two or three optimized layers:</p>
66   -
67   -<ul>
68   -<li>One layer for common toolkit code, like jQuery, Dojo, Prototype or MooTools (toolkit.js). It may make sense to roll this layer in with the appcommon.js layer.</li>
69   -<li>One layer for common web app code (appcommon.js)</li>
70   -<li>One layer for page-specific code (page.js)</li>
71   -</ul>
72   -
73   -<p>Ideally you could do that layering after you finish development, and tune those layers for optimal, parallel download of the files, without having to change all your scripts.</p>
74   -
75   -<p>This is possible with RequireJS:</p>
76   -
77   -<ul>
78   -<li><a href="optimization.html#wholeproject">Optimize your project</a> to create the three script layers.</li>
79   -<li>Use the <a href="api.html#config"><strong>priority</strong> config value</a> to pass the list of layers to priority download to the top-level require() call in the HTML file(s).</li>
80   -</ul>
81   -
82   -<p>Script modules/files specified in the config's priority array will be downloaded in parallel before any other script dependencies are traced. <b>Note:</b> resources loaded by loader plugins (like 'text!template.html') <b>cannot</b> be specified in the priority array: the priority mechanism only works with regular JavaScript resources.</p>
83   -
84   -<p>This example builds on the <a href="download.html#samplejquery">sample jQuery project</a> to demonstrate the approach:</p>
85   -
86   -<p>Assume the project has the following structure:</p>
87   -
88   -<ul>
89   -<li>app.build.js (the build profile used by optimization tool)</li>
90   -<li>webapp
91   -<ul>
92   -<li>page1.html</li>
93   -<li>page2.html</li>
94   -<li>scripts
95   -<ul>
96   -<li>require.js (the loader)</li>
97   -<li>appcommon.js (used on both pages, "appcommon")</li>
98   -<li>jquery.js (used on both pages, "appcommon")</li>
99   -<li>page1.js (lists the dependencies for page 1)</li>
100   -<li>page2.js (lists the dependencies for page 2)</li>
101   -<li>object.js (used on both pages, "appcommon")</li>
102   -<li>event.js (used on both pages, "appcommon")</li>
103   -<li>widget.js (used on both pages, "appcommon")</li>
104   -<li>Dialog.js (used on both pages, "appcommon")</li>
105   -<li>Slider.js (used only on page 2)</li>
106   -<li>Tabs.js (used only on page 1)</li>
107   -</ul></li>
108   -</ul></li>
109   -<li>webapp-build
110   -<ul>
111   -<li>this directory will hold the optimized files</li>
112   -</ul></li>
113   -</ul>
114   -
115   -<p>page1.html might look like this:</p>
116   -
117   -<pre><code>&lt;!DOCTYPE html&gt;
118   -&lt;html&gt;
119   - &lt;head&gt;
120   - &lt;title&gt;Page 1&lt;/title&gt;
121   - &lt;script src="scripts/require.js"&gt;&lt;/script&gt;
122   - &lt;script&gt;
123   - require.config({
124   - priority: ["appcommon", "page1"]
125   - });
126   - &lt;/script&gt;
127   - &lt;/head&gt;
128   - &lt;body&gt;
129   - &lt;/body&gt;
130   -&lt;/html&gt;
131   -</code></pre>
132   -
133   -<p>with appcommon.js looking like this:</p>
134   -
135   -<pre><code>define(["jquery", "object", "event", "widget", "Dialog"],
136   -function () {
137   - //Just an empty function, this is a place holder
138   - //module that will be optimized to include the
139   - //common depenendencies listed in this module's dependency array.
140   -});
141   -</code></pre>
142   -
143   -<p>and page1.js looking like this:</p>
144   -
145   -<pre><code>define([ "jquery", "object", "event", "widget", "Dialog", "Tabs"],
146   -function ($, object, event, widget, Dialog, Tabs) {
147   - ...
148   -});
149   -</code></pre>
150   -
151   -<p>page2.html and page2.js would look similar, except referencing "page2" instead of "page1" and using "Slider" instead of "Tabs" in page2.js.</p>
152   -
153   -<p>The build profile, <strong>app.build.js</strong> would look like this:</p>
154   -
155   -<pre><code>({
156   - appDir: "webapp",
157   - baseUrl: "scripts",
158   - dir: "webapp-build",
159   - optimize: "none",
160   - modules: [
161   - {
162   - name: "appcommon"
163   - },
164   - {
165   - name: "page1",
166   - exclude: ["appcommon"]
167   - },
168   - {
169   - name: "page2",
170   - exclude: ["appcommon"]
171   - }
172   - ]
173   -})
174   -</code></pre>
175   -
176   -<p>Once the build is run, it will generate the contents of <strong>webapp-build</strong> that look similar to <strong>webapp</strong>, except that the contents are optimized. appcommon.js will contain the common modules, and page1.js will have all the modules page1 needs, excluding appcommon's modules and their nested dependencies.</p>
177   -
178   -<p>The <strong>priority</strong> config value tells RequireJS to load appcommon.js and page1.js in parallel and wait before both are loaded before tracing dependencies. With those two files, along with require.js, all the dependencies in the page will be loaded with three requests, with the appcommon.js and page1.js scripts being loaded asynchronously and in parallel.</p>
179   -</div>
2  docs/jquery.html
@@ -58,8 +58,6 @@
58 58 &lt;/html&gt;
59 59 </code></pre>
60 60
61   -<span class="note">The path rules used for data-main changed in RequireJS 0.23. Before that version, data-main="main" for the above example.</span>
62   -
63 61 <p>The data-main attribute on the script tag for require.js tells RequireJS to load the scripts/main.js file. RequireJS will load any dependency that is passed to require() without a ".js" file from the same directory as the one used for data-main. If you feel more comfortable specifying the whole path, you can also do the following:</p>
64 62
65 63 <pre><code>&lt;script data-main="scripts/main.js" src="scripts/require-jquery.js"&gt;&lt;/script&gt;
2  docs/optimization.html
@@ -383,7 +383,7 @@
383 383 <pre><code>node r.js -o build.js optimize=none
384 384 </code></pre>
385 385
386   -<p><strong>Config settings in your main JS file are not read by default by the optimizer</strong></p>
  386 +<p><strong name="mainConfigFile">Config settings in your main JS file are not read by default by the optimizer</strong></p>
387 387
388 388 <p>This is because the config settings for a build can be very different, with multiple optimization targets. So a separate set of config options need to be specified for the optimizer.</p>
389 389
3  docs/plugins.html
@@ -24,6 +24,9 @@ <h2 id="intro">
24 24 <p>RequireJS allows you to write loader plugins that can load different types of resources as dependencies, and even include the dependencies in optimized builds.</p>
25 25
26 26 <p>Examples of existing loader plugins are the <a href="api.html#text">text!</a> and <a href="api.html#i18n">i18n!</a> plugins. The text! plugin handles loading text, and the i18n plugin handles loading a JavaScript object that is made up from objects from a few different modules. The object contains localized strings.</p>
  27 +
  28 +<p>The RequireJS wiki has a longer <a href="https://github.com/jrburke/requirejs/wiki/Plugins">list of plugins on the RequireJS</a>.</p>
  29 +
27 30 </div>
28 31
29 32 <div class="section">
31 tasks.txt
... ... @@ -1,8 +1,10 @@
1 1 Release Notes
2 2 -------------------
3 3
4   -Things to mention about 1.1/TODOC:
5   -----------
  4 +After merge/release:
  5 +
  6 +
  7 +
6 8
7 9 Implementation notes
8 10 --------
@@ -18,32 +20,9 @@ with scripts.
18 20 -> Allow 'module': '' and 'module/': '' config instead of packages config.
19 21
20 22 DOC updates:
21   -- Talk about paths and baseUrl first,
22   -- Teach how to fail, how to debug first.
23 23 - Put in link to the 1.0.8 docs.
  24 +- Put in "upgrade info" on ai page.
24 25 - remove require() references, focus on doing data-main and define() instead.
25   -- Update api.html#errors to mention new local errors, requireType, requireModules.
26   -- plugins: load.error(). Once called, there is no resetting from it, no undef.
27   -- module.config()
28   -- shim: use, always need to use mainConfigFile.
29   -- map config with *
30   -- enforceDefine: true,
31   - - mention in error handling
32   - - create errors.html section for nodefine
33   - - ie9 cannot use error event listener because onreadystatechange fires first,
34   - and cannot use addEventListener (which has load fire after error) because
35   - of IE not firing onload right after script execution.
36   - - mention how it works with shim.exports string values.
37   - - paths array only works well if used with enforceDefine for IE.
38   -- #scripterror document on errors page.
39   -- mention https://github.com/jrburke/requirejs/wiki/Plugins on plugins page.
40   - - ask plugin authors to update if they work with 2.0
41   -- For undef mention that it only cleans up the current module. If you want to
42   - it and anything it depends on, and clear its dependencies, then need to know
43   - the graph, probably by listening to onResourceLoad.
44   -- building code with "shim" means that code cannot cdn load for instance jquery
45   - after a build since the non-amd code will expect jquery to already be there.
46   - Can just put a script tag in after require.js for it. or go full amd.
47 26 - scrub text references, in new repo
48 27 - scrub i18n references, in new repo
49 28 - scrub domReady references, in new repo

0 comments on commit 80772e8

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