forked from seajs/seajs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
module-identifier.html
210 lines (169 loc) · 5.5 KB
/
module-identifier.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
<!doctype html>
<html>
<head>
<meta http-equiv="Pragma" content="no-cache"/>
<meta charset="utf-8"/>
<title>Module Identifier - Sea.js Manual & Documentation</title>
<link rel="stylesheet" href="assets/api.css"/>
</head>
<body>
<div id="container">
<header>
<h1>Sea.js Manual & 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-identifier">Module Identifier</a>
<ul>
<li><a href="#relative-id">Relative Identifier</a></li>
<li><a href="#top-level-id">Top-Level Identifier</a></li>
<li><a href="#normal-path">Normal Path</a></li>
</ul>
</li>
<li><a href="#tips">Tips About File Extensions</a></li>
</ul>
<hr/>
</div>
<h2 id="module-identifier">Module Identifier</h2>
<p>
Module identifiers can be used to identify the current module being defined.
Loading functions such as <code>require</code>, <code>require.async</code>
take module id as their first parameter, and module identifiers are
also used in the <code>dependencies</code> argument.
</p>
<p>
Module identifiers in SeaJS are a superset of what is allowed in
<a href="http://wiki.commonjs.org/wiki/Modules/1.1.1">CommonJS Module Identifiers</a>:
</p>
<blockquote>
<ol>
<li>
A module identifier is a String of "terms" delimited by forward
slashes.
</li>
<li>
A term must be a camelCase identifier, ".", or "..".
</li>
<li>
Module identifiers may not have file-name extensions like ".js".
</li>
<li>
Module identifiers may be "relative" or "top-level". A module
identifier is "relative" if the first term is "." or "..".
</li>
<li>
Top-level identifiers are resolved off the conceptual module name space
root.
</li>
<li>
Relative identifiers are resolved relative to the identifier of the
module in which "require" is written and called.
</li>
</ol>
</blockquote>
<h3 id="relative-id">Relative Identifier</h3>
<p>
Relative identifiers start with a dot (<code>"."</code>), and MUST be in
a module environment. They are resolved relative to the uri of the current
module:
</p>
<pre>
// In http://example.com/js/a.js:
require('./b');
// => http://example.com/js/b.js
</pre>
<h3 id="top-level-id">Top-Level Identifier</h3>
<p>
Top-level identifiers do not start with a dot (<code>"."</code>) or a slash
(<code>"/"</code>). They are resolved relative to the conceptual namespace
root. SeaJS will attempt to locate modules referenced with top-level paths
relative to the <code>base</code> path.
</p>
<pre>
// Assume base path is: http://example.com/js/libs/
// In some module factory:
require('jquery/1.7.1/jquery');
// => http://example.com/libs/jquery/1.7.1/jquery.js
</pre>
<p>
The default value of <code>base</code> is related to the path of
<code>sea.js</code>:
</p>
<pre>
If the sea.js path is:
http://example.com/js/libs/sea.js
Then the base path is:
http://example.com/js/libs/
</pre>
<p>
When the path of <code>sea.js</code> contains version number, the
default value of <code>base</code> will ignore <code>seajs/x.y.z</code>.
This way is more friendly for hosting multiple versions of libraries.
</p>
<pre>
If the sea.js path is:
http://example.com/libs/seajs/1.0.0/sea.js
Then the base path is:
http://example.com/libs/
</pre>
<p>Of course, you can config the base path manually.</p>
<pre>
seajs.config({
base: 'http://code.jquery.com/'
});
// In some module factory:
require('jquery');
// => http://code.jquery.com/jquery.js
</pre>
<h3 id="normal-path">Normal Path</h3>
<p>
All identifiers except relative and top-level identifiers are normal paths.
They are resolved just like the <code>script.src</code> in html files.
</p>
<pre>
// In http://example.com/js/main.js:
require('http://example.com/js/a');
// => http://example.com/js/a.js
// In http://example.com/js/a.js:
require('/js/b');
// => http://example.com/js/b.js
// In any where:
seajs.use('./c');
// => http://example.com/path/to/page/c.js
</pre>
<p>
The module identifiers in the <code>seajs.use(ids, ...)</code> and
<code>define(id, ...)</code> are always normal paths, because those
functions are designed to work in the global environment.
</p>
<h2 id="tips">Tips About File Extensions</h2>
<p>
SeaJS always adds the file extension (".js") when attempting to locate
JavaScript modules, except when a hash ("#") or question mark ("?") are
present in the path. An easy way to suppress the automatic file extension
is to add a hash ("#") to the end of the path.
</p>
<pre>
// The ".js" extension can be omitted:
require('http://example.com/js/a');
require('http://example.com/js/a.js');
// => http://example.com/js/a.js
// The ".css" extension can NOT be omitted:
require('http://example.com/css/a.css');
// => http://example.com/css/a.css
// When a question mark ("?") is present, nothing will be added to the path:
require('http://example.com/js/a.json?callback=define');
// => http://example.com/js/a.json?callback=define
// When the path ends with a hash ("#"), the hash will be ignored:
require('http://example.com/js/a.json#');
// => http://example.com/js/a.json
</pre>
</div>
<script src="../build/sea.js" data-main="assets/init"></script>
</body>
</html>