-
Notifications
You must be signed in to change notification settings - Fork 16
/
Copy pathrequirejs.javascript.txt
257 lines (221 loc) · 17.1 KB
/
requirejs.javascript.txt
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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
┏━━━━━━━━━━━━━━━┓
┃ REQUIREJS ┃
┗━━━━━━━━━━━━━━━┛
VERSION ==> #2.1.17
GOAL ==> #See UMD documentation file
<script src="require.js" #Loads require.js (synchronously), then MAINFILE (async.).
data-main="MAINFILE"> #Implies <script async> so cannot assume that rest of page has access to MDL:
# - if rest of page (other <script>, including inline) need to use require(), should not
# use data-main nor async.
# - but at best, should not put any other <script>
require(PATH_ARR, FUNC([MDL...])) #Loads all MDL from PATH_ARR (managing dependencies order) then fires FUNC()
CONFVAR deps PATH_ARR #Calls require(PATH_ARR) as soon as "require.js" is loaded
#Can also use CONFVAR callback([MDL...]), which will fire just after require() is done.
define([["MDL_ID", ]PATH_ARR,] #Same as require(...) but also define a new MDL2, i.e. FUNC return value, must be an OBJ.
FUNC([MDL...])) #If cannot use define() (e.g. external libraries), must use CONFVAR shim.PATH OBJ|ARR:
# - exports "VAR": variable to export as MDL (relative to WINDOW)
# - deps PATH_ARR, init([MDL2...]): like define()
# - ARR means { deps ARR }.
#Should not change global variable.
#Should define() only once per file (unless using "MDL_ID")
define([..., ]MDL) #Same as define(..., FUNC()->MDL)
CONFVAR #Set up by either:
# - require.config(OBJ), which must be in beginning of MAINFILE, or before loading it
# - var require = OBJ, which must be before loading require.js
# - if CONFVAR.context STR specified (can be any STR), can call several times, and each
# returned "require" will have different CONFVAR.
PATH # - ending ".js" is optional
# - relative paths resolved to:
# - $PWD
# - CONFVAR baseUrl:
# - def. is the DIR of:
# - MAINFILE if data-main="MAINFILE" is used
# - the HTML page loading requireJS otherwise
# - cannot be a different domain if using "text!" plugins and not using r.js
# - with CONFVAR paths.SUBDIR STR[_ARR], if SUBDIR === [parent DIRs of] PATH:
# - matching part will be substituted by STR
# - if STR is absolute, baseUrl is prepended
# - if ARR, tries each one after another (last ones being fallbacks)
# - "MDL_ID":
# - must use CONFVAR bundles.PATH "MDL_ID"_ARR, which will load PATH when requiring
# any "MDL_ID", with PATH being the file which define() it.
# - can use CONFVAR map.PATH2.MDL_ID "MDL_ID2", so that the file designated by PATH2
# gets "MDL_ID2" when requiring "MDL_ID".
# - usage: several files requiring same library, but different versions of it
# - PATH2 can be "*" meaning any other, if no map.PATH2 matches
# - should be avoided
#Possible organization:
# - baseUrl "js/lib/"
# - CONFVAR paths.app "../app"
# - then:
# - js/ MAINFILE and require.js
# - js/lib/ libraries (PATH "*")
# - js/app/ user code (PATH "app/*")
#It is best if PATH files don't have version in filename.
require.toUrl(PATH) #Returns PATH relative to baseUrl.
#Must be in a define() FUNC, with "require" and PATH as dependencies.
MODULE.config() #When called in a file PATH, returns CONFVAR config.PATH OBJ
#MODULE is "module" MDL
CIRCULAR DEPENDENCIES ==> #Must use require(PATH)->MDL or [module.]exports as MDL (see below)
COMMONJS ==> #Can load CommonJS packages with CONFVAR packages OBJ_ARR|PATH_ARR:
# - name PATH and main STR: require("PATH") will load PATH/STR
# - PATH_ARR: like { name PATH, main "main" }
#define(["MDL_ID", ]FUNC(require, exports, module)):
# - alternate syntax (arguments must be exactly like this), which allows using:
# - require(PATH)->MDL
# - or defining [module.]exports as MDL
# - can also use require(PATH)->MDL by having "require" and PATH as dependencies
ERRORS CALLBACKS ==> #Check for script loading errors. ERROR is OBJ:
# - requireModules PATH_ARR
# - requireType STR, among:
# - "timeout": after CONFVAR waitSeconds NUM (def: 7)
# - "nodefine": 404, or dependencies failed
# - "scripterror": error in loaded script
#By:
# - CONFVAR.paths.SUBDIR ARR fallbacks (see above)
# - using last arg FUNC(ERROR) to require():
# - with CONFVAR enforceDefine true
# - must then call requirejs.undef(PATH)
# - requirejs.onError(ERROR)
#CONFVAR.shim.PATH.exports must exist for this to work on a shim
OTHERS ==> # - CONFVAR xhtml true: if using XHTML
# - CONFVAR urlArgs STR: extra query parameter to URL fetched
┌──────────┐
│ R.JS │
└──────────┘
r.js -o [VARR=VAL] #Node binary (2.1.18), that:
# - concanates and Uglifies JavaScript
# - inline modules using RequireJS plugins (text!, i18n!)
# - CSS minification
# - when using other projects like Almond, to minify RequireJS runtime size from
# 83K to less than 1K
#Must:
# - use only global require() call, with "PATH" (not PATH variables)
# - if a PATH is a URL, replace it with fake protocol "empty:", so it keep loading it
# at runtime (CDN) not compile time
#VARR are below:
mainConfigFile #FILE:
# - file holding require.config(OBJ), defining r.js VARR
# - can also use a FILE called app.build.js as the "out FILE" instead
baseUrl|paths|packages|map|shim|
waitSeconds #Same as CONFVAR
modules #OBJ_ARR: MDL to optimize. If only one OBJ, can specify directly as VARR.
# - name PATH
# - include|deps PATH_ARR: also optimize those MDL2 along the same build
# - exclude[Shallow] PATH_ARR: exclude also dependencies [or not]
# - override.VARR
out #FILE (can also be last r.js argument)
appDir #What baseUrl is relative to
dir #DIR (def: "build"): copies all appDir files to DIR
keepBuildDir #BOOL (def: false): if true, does not remove dir DIR before recreating it.
#Should be false if onBuildRead|Write used.
fileExclusionRegExp #(def: /^\./): do not copy files whose filename matches it, to DIR
removeCombined #BOOL (def: false): if true, remove files that are also concanated in another file
optimize #STR, among "none" (no minification), "uglify" (def), "uglify2" or "closure[.keepLines]"
uglify[2]|closure #OBJ: UglifyJS|Closure options.
skipDirOptimize #BOOL: if true, only minify "modules"
optimizeCss #STR: CSS minification (@import inlining, remove comments, remove whitespaces/newlines)
#among "none" or "standard[.keepComments][.keepLines][.keepWhitespace]" (def)
generateSourceMaps #BOOL (def: false): must use preserveLicenseComments false
cssImportIgnore #"FILE[,...]": no CSS @import inlining
cssIn #"FILE.css": only does CSS minification, and of this FILE
cssPrefix #DIR: prefixed to URL in CSS @import
inlineText #BOOL: inlines text! plugin
locale #LANG: inlines i18n! plugin
wrap #OBJ|BOOL:
# - start|endFile FILE[_ARR] or start|end STR: header|footer for concanation
# Can be used for UMD.
# - true: same as start "(function(){", end "}())"
wrapShim #BOOL: if true, wrap shimmed dependencies with define()
useStrict #BOOL: if false (def), remove "use strict;"
preserveLicenseComments #(def: true)
pragmas[OnSave].VAR true #include|exclude blocks of code between comments:
# //>>exclude|includeStart("VAR", pragmas.VAR);
# ...
# //>>exclude|includeEnd("VAR");
skipPragmas #BOOL (def: false)
logLevel #0-4 (def: 0): TRACE|INFO|WARN|ERROR|SILENT
REQUIREJS.optimize
(OBJ[, FUNC(STR)][, FUNC2(ERROR)])#r.js as Node module
grunt-contrib-requirejs #Grunt plugin (0.4.4), use r.js
# - TASK "requirejs"
# - TARGET none
# - options:
# - OBJ.VARR (same as above)
# - done(FUNC(), STR)
KARMA ==> #Must:
# - frameworks "requirejs" (module karma-requirejs 0.2.2)
# - make test files use require()
# - baseUrl must start with "/base/" (where Karma serves files)
# - only include one file (but others must be served):
# - require.config(OBJ):
# - CONFVAR deps|paths|shim must include:
# - app files
# - tests files, which can be found by iterating over window.__karma__.files
# - call window.__karma__.start() once tests are loaded, i.e. in CONFVAR callback
ALMOND ==> #Version 0.3.1:
# - replace AMD with much smaller runtime
# - must use r.js with VARR:
# - name pointing to almond
# - insertRequire|include PATH_ARR (use both)
# - wrap true
# - limitations:
# - no dynamic loading
# - only one require.config(), and not using var require = OBJ
# - no require.toUrl(), CONFVAR packages|context
┌─────────────┐
│ PLUGINS │
└─────────────┘
PLUGINS ==> #MDL that is used as "PLUGIN!PATH":
# - is { version STR, load(PATH, require, FUNC, config), ... } (see online doc)
# - when loaded, augment loading capabilities
text #Version 2.0.14
#Allow using "text!PATH[!strip]":
# - will load file as a STR. Useful for HTML templates.
# - if !strip and is HTML, only loads the <body>
domReady #Version 2.0.1
#Define a MDL "domReady" that can be used to listen for DOMContentLoaded, but also on IE8:
# domReady(FUNC())
#Can also use MDL "domReady!", which waits for DOMContentLoaded for require|define() FUNC
#to fire.
i18n #Version 2.0.5
#Allow using "i18n!PATH", where PATH second-to-last DIR must be "nls" and contain
#OBJ.LANG true, which will fetches instead PATH with "nls/" -> "nls/LANG2/":
# - LANG2:
# - NAVIGATOR.[user]language[s], lower-cased, can be longer/shorter
# - CONFVAR i18n.locale
# - or "root"
# - if OBJ.LANG2 true
requirejs-plugins #Version 1.0.3
#Plugins:
# - "image!PATH": loads image as STR
# - "json!PATH": loads JSON file as OBJ
# - "mdown!PATH": loads Markdown file as compiled HTML_STR
# - "font!PATH": load web fonts
#"json!" and "mdown!" requires "text" plugin.
#Must define CONFVAR paths.image|json|mdown|font PATH_TO_JS (e.g. "lib/require/image")
require-css #Version 0.1.8
#"css!PATH" loads CSS file. Goal is to dynamically load them, when they depend on dynamically
#loaded templates.
#Must add CONFVAR map."*".css PATH_TO_JS
require-jade #Version 0.0.3
#"jade!PATH" loads Jade file as FUNC(OBJ)->HTML_STR
require-handlebars-plugin #Version 0.11.2
#"hbs!PATH" loads Handlebars template as FUNC(OBJ)->STR
#Must use CONFVAR paths.hbs PATH_TO_JS
#CONFVAR hbs OBJ:
# - helpers BOOL (def: true): use templates/helpers/ as base URL
# - templateExtension STR (def: "hbs")
# - partialsUrl STR: partials base URL
requirejs-tpl #Version 0.2 (ZeeAgency) or fork version 0.3 (dawsontoth)
#"tpl!PATH" loads Underscore template as FUNC(OBJ)->STR
lodash-template-loader #Version 1.0.0
#"ldsh!PATH" loads Underscore/Lodash template as FUNC(OBJ)->STR
#CONFVAR lodashLoader OBJ:
# - ext STR (def: ".html")
# - root STR: templates base URL
# - templateSettings OBJ
#Must use CONFVAR paths.ldsh PATH_TO_JS
#To use Underscore, must use CONFVAR map."*".lodash "underscore"
requirejs-hogan-plugin #Version 0.3.1
#"hgn!PATH" loads Mustache/Hogan template as FUNC(OBJ[, OBJ2])->STR