Skip to content

Commit fe33dbc

Browse files
jrburkejrburke
committed
Update docs for new namespacing feature in optimizer.
1 parent 88c1723 commit fe33dbc

File tree

5 files changed

+99
-4
lines changed

5 files changed

+99
-4
lines changed

‎docs/faq-advanced.html‎

Lines changed: 63 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,71 @@ <h1>FAQ: RequireJS Advanced Usage</h1>
88
</div>
99

1010
<div class="section">
11-
<h2><a name="rename">How can I rename require?</a><span class="sectionMark">&sect; 1</span></h2>
11+
<h2><a name="rename">How can I rename require/define/requirejs?</a><span class="sectionMark">&sect; 1</span></h2>
1212

13-
<p>RequireJS and its optimization tool need to be version 0.11 or higher for this to work.</p>
13+
<p>RequireJS and its optimization tool need to be version 0.26.0 or higher for this to work.</p>
1414

15-
<p>Why would you want to do this? You may have very strict global namespace requirements or you may be using code that already defines a require and you want to avoid interference. There are two steps to use the require defined by RequireJS with a different name:</p>
15+
<p>Why would you want to do this? You may have very strict global namespace requirements
16+
or you may be using code that already defines require/define and you want to avoid interference.</p>
17+
18+
<p>Some notes on this capability:</p>
19+
20+
<ul>
21+
<li>Make sure to use a source version of require.js, not a minified version.</li>
22+
<li>Make sure that version of require.js is included in the optimization because the require.js
23+
file contents are altered for the namespacing to work.</li>
24+
<li>Code your modules using require/define as normal, then do a build to namespace the values.
25+
Do not code your modules using the namespaced require/define. It will make your code less
26+
portable and usable by others.</li>
27+
<li>This transformation/optimization only works once. Do not use the output of this optimization as
28+
input to another optimization/build stage.</li>
29+
</ul>
30+
31+
<p>The following example optimization config is based on the directory structure
32+
used in the example on the <a href="optimization.html"> optimization page</a>. This config combines
33+
require.js with main.js into a new <strong>foo.js</strong>. file. define() is renamed to <strong>foo.define()</strong>
34+
and require() is renamed to <strong>foo.require()</strong>:</p>
35+
36+
<pre><code>
37+
{
38+
appDir: "../",
39+
baseUrl: "scripts",
40+
dir: "../../appdirectory-build",
41+
42+
//Put in a mapping so that 'requireLib' in the
43+
//modules section below will refer to the require.js
44+
//contents.
45+
paths: {
46+
requireLib: 'require'
47+
},
48+
49+
//Indicates the namespace to use for require/requirejs/define.
50+
namespace: "foo",
51+
52+
modules: [
53+
{
54+
name: "foo",
55+
include: ["requireLib", "main"],
56+
//True tells the optimizer it is OK to create
57+
//a new file foo.js. Normally the optimizer
58+
//wants foo.js to exist in the source directory.
59+
create: true
60+
}
61+
]
62+
}
63+
</code></pre>
64+
65+
66+
<p>Once this optimization is done, the HTML that used to refer to require.js would
67+
need to be modified to refer to foo.js.</p>
68+
69+
<p>Thanks to <a href="http://ryanflorence.com">Ryan Florence</a> for help on the namespace design.</p>
70+
71+
<hr>
72+
73+
<p>Another approach to renaming, if you prefer to have more direct control of the content, and
74+
want to commit source code with the modifications. This approach <strong>should not be used</strong>
75+
with the "namespace" optimization demonstrated above.</p>
1676

1777
<div class="subSection">
1878
<h4>1) Modify the source of require.js</h4>

‎tasks.txt‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,6 @@ Docs:
6464

6565
- If any other info: IE checkLoaded recursion? https://github.com/jrburke/requirejs/issues/82
6666

67-
- build tool to rename require and define calls to other names?
6867
- Confirm: From Richard Backhouse: As an FYI I have been doing my own investigation of using UglifyJS for compression
6968
and one thing I found when trying to compress dojo 1.5 code was that I had ensure that "make_seqs"
7069
flag was set to false when calling ast_squeeze. If I left this flag set to true the code would not load.

‎tests/NAMESPACE.html‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<title>require.js: NAMESPACE Test</title>
5+
<script type="text/javascript" src="NAMESPACE.js"></script>
6+
<script type="text/javascript" src="doh/runner.js"></script>
7+
<script type="text/javascript" src="doh/_browserRunner.js"></script>
8+
<script type="text/javascript">
9+
NAMESPACE.require(['one', 'dimple'], function(one, dimple) {
10+
doh.register(
11+
"namespaceTest",
12+
[
13+
function namespaceTest(t){
14+
t.is("large", one.size);
15+
t.is("dimple-blue", dimple.color);
16+
}
17+
]
18+
);
19+
doh.run();
20+
21+
});
22+
</script>
23+
</head>
24+
<body>
25+
<h1>require.js: NAMESPACE Test</h1>
26+
27+
<p>Only works after doing a build using the simpleNamespace.build.js file
28+
in the r.js project.</p>
29+
30+
<p>Check console for messages</p>
31+
</body>
32+
</html>

‎tests/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ Go to r.js project and run the following:
2626

2727
Try manual testing:
2828

29+
* node ../../r.js -o simpleNamespace.build.js - load builds/simpleNamespace/NAMESPACE.html to test namespacing.
2930
* node ../../r.js -o indexBuilder.build.js - confirm plugin write calls are done.
3031
* node ../../r.js -o text.build.js - confirm plugin write calls are done.
3132
* node ../../r.js -o textExclude.build.js - confirm that 'text!subwidget2.html' is excluded.

‎tests/dimple.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
//
2+
// this is a comment
3+
//
14
define("dimple",
25
{
36
color: "dimple-blue"

0 commit comments

Comments
 (0)