Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 662 lines (507 sloc) 23.48 kB
9bdd554 more about AMD and CommonJS
John Hann authored
1 curl (Cujo Resource Loader)
e14209e clarified README
John Hann authored
2 =====================
fccc4e9 the start of a README
unscriptable authored
3
1d8f14b pdated to latest version and removed all references to the old public…
unscriptable authored
4 version 0.4.4
20fbf55 added notes about CommonJS Modules 1.1 support
unscriptable authored
5
6 What's New?
7
1d8f14b pdated to latest version and removed all references to the old public…
unscriptable authored
8 * `require` is no longer an lias for `curl` unless you set the
9 apiName:'require' config param
10 * dojo 1.6 support was moved to a separate module and/or built curl.js
d9de6ea fixed !order option for js! plugin (all browsers except firefox) and …
unscriptable authored
11 * Fixed !order option for js! plugin in non-Firefox browsers (0.4.3)
a8f7f9d bumped to version 0.4.2 and added version notes
unscriptable authored
12 * Fixed the compiled version in 0.4.2 (dist/ folder)
4a92fee notes about Packages 1.1 support and updates to What's New and size
unscriptable authored
13 * Several fixes to path and package mapping were made in 0.4.1
20fbf55 added notes about CommonJS Modules 1.1 support
unscriptable authored
14 * CommonJS Modules 1.1
d5d4eb3 updated to latest features
unscriptable authored
15 * CommonJS Packages 1.1
4a92fee notes about Packages 1.1 support and updates to What's New and size
unscriptable authored
16 * dojo 1.6 support (dojo relies on non-standard RequireJS features)
17 * node.js support (when module is wrapped in a define())
18 * require(dep) as an RValue (needed or dojo and node)
ae6d718 bumped version to 0.3.3
unscriptable authored
19 * !noexec suffix for js! plugin (load, but don't execute)
d5d4eb3 updated to latest features
unscriptable authored
20 * !wait suffix was renamed to !order (and semantics were changed)
21 * async=false
bb87447 more README cleanup
unscriptable authored
22
23 TODO:
24
d5d4eb3 updated to latest features
unscriptable authored
25 * finish i18n plugin (eta: 2011-04-21)
e8b5ef1 Edited README.md via GitHub
John Hann authored
26 * move the dojo 1.6 shim code into it's own module (dojo16Compat.js)
27 (in progress)
28 * notes about using JSONP (it works for objects, arrays, functions, numbers
6558745 corrected: JSONP works for fetching remote strings, too
John Hann authored
29 and strings! use ?callback=define)
a8f7f9d bumped to version 0.4.2 and added version notes
unscriptable authored
30 * use CommonJS file structure (lib/ instead of src/)
fccc4e9 the start of a README
unscriptable authored
31
32 ----------------------------------------
33
34 What is curl.js?
c1519b8 more tests
unscriptable authored
35 ================
fccc4e9 the start of a README
unscriptable authored
36
39b5e54 updated README to reflect latest features
unscriptable authored
37 curl.js is a small, but very fast AMD-compliant asynchronous loader.
1d8f14b pdated to latest version and removed all references to the old public…
unscriptable authored
38 Size: 4.2KB (2.1KB gzipped) using Google's Closure Compiler.
fc8f801 updated to version 0.3!
unscriptable authored
39
d5d4eb3 updated to latest features
unscriptable authored
40 If you'd like to use curl.js for non-AMD modules (ordinary javascript files),
41 you'll want to use the version with the js! plugin built in. You may also
42 want to build-in the domReady module. The combined curl+js+domReady loader
43 is still only 6.0KB (2.7KB gzipped).
fc8f801 updated to version 0.3!
unscriptable authored
44
d5d4eb3 updated to latest features
unscriptable authored
45 What the heck is "cujo"? cujo.js is a web app development platform.
46 See the bottom of this file for more info.
f778b1f Edited README.md via GitHub
John Hann authored
47
fccc4e9 the start of a README
unscriptable authored
48 ----------------------------------------
49
39b5e54 updated README to reflect latest features
unscriptable authored
50 Features at a glance:
51 =====================
52
f125b8c Edited README.md via GitHub
John Hann authored
53 * Loads CommonJS AMD-formatted javascript modules in parallel (fast!)
20fbf55 added notes about CommonJS Modules 1.1 support
unscriptable authored
54 * Loads CommonJS Modules (v1.1 when wrapped in a `define()`) (fast!)
d5d4eb3 updated to latest features
unscriptable authored
55 * Loads CommonJS Packages (v1.1 modules wrapped in a `define()`) (fast!)
f125b8c Edited README.md via GitHub
John Hann authored
56 * Loads non-AMD javascript files in parallel, too (fast! via js! plugin)
57 * Loads CSS files and text files in parallel (fast! via plugins)
39b5e54 updated README to reflect latest features
unscriptable authored
58 * Waits for dependencies (js, css, text, etc) before executing javascript
f125b8c Edited README.md via GitHub
John Hann authored
59 * Waits for domReady, if/when desired
60 * Allows for virtually limitless combinations of files and dependencies
39b5e54 updated README to reflect latest features
unscriptable authored
61 * Tested with Chrome, FF3+, Safari 3.2+, IE6-8, Opera 9.5+
62
f125b8c Edited README.md via GitHub
John Hann authored
63 Oh, did we mention? It's fast!
64
39b5e54 updated README to reflect latest features
unscriptable authored
65 ----------------------------------------
66
67 API at a glance
68 ===============
69
70
c1ee8af we can haz markdown!
unscriptable authored
71 curl(['dep1', 'dep2', 'dep3' /* etc */], callback);
39b5e54 updated README to reflect latest features
unscriptable authored
72
c1ee8af we can haz markdown!
unscriptable authored
73 Loads dependencies and the executes callback.
20fd1ca Edited README.md via GitHub
John Hann authored
74
34ceaec cleaned up some API definitions
John Hann authored
75 * ['dep1', 'dep2', 'dep3']: Module names or plugin-prefixed resource files
d5d4eb3 updated to latest features
unscriptable authored
76 * callback: Function to receive modules or resources. This is where you'd
77 typically start up your app.
39b5e54 updated README to reflect latest features
unscriptable authored
78
11a6dc1 Edited README.md via GitHub
John Hann authored
79 ---------
c1ee8af we can haz markdown!
unscriptable authored
80 curl(['dep1', 'dep2', 'dep3' /* etc */])
81 .then(callback, errorback);
39b5e54 updated README to reflect latest features
unscriptable authored
82
c1ee8af we can haz markdown!
unscriptable authored
83 Promises-based API for executing callbacks.
20fd1ca Edited README.md via GitHub
John Hann authored
84
34ceaec cleaned up some API definitions
John Hann authored
85 * ['dep1', 'dep2', 'dep3']: Module names or plugin-prefixed resource files
86 * callback: Function to receive modules or resources
87 * errorback: Function to call if an exception occurred while loading
39b5e54 updated README to reflect latest features
unscriptable authored
88
11a6dc1 Edited README.md via GitHub
John Hann authored
89 ---------
c1ee8af we can haz markdown!
unscriptable authored
90 curl(config, ['dep1', 'dep2', 'dep3' /* etc */], callback);
39b5e54 updated README to reflect latest features
unscriptable authored
91
c1ee8af we can haz markdown!
unscriptable authored
92 Specify configuration options, load dependencies, and execute callback.
20fd1ca Edited README.md via GitHub
John Hann authored
93
34ceaec cleaned up some API definitions
John Hann authored
94 * config: Object containing curl configuration options (paths, etc.)
95 * ['dep1', 'dep2', 'dep3']: Module names or plugin-prefixed resource files
96 * callback: Function to receive modules or resources
39b5e54 updated README to reflect latest features
unscriptable authored
97
11a6dc1 Edited README.md via GitHub
John Hann authored
98 ---------
c1ee8af we can haz markdown!
unscriptable authored
99 curl(['domReady', 'dep2', 'dep3' /* etc */])
100 .then(
cf5fb83 curl() now looks for promises returned from define()s -- either direc…
unscriptable authored
101 callback,
c1ee8af we can haz markdown!
unscriptable authored
102 errorback
103 );
67c1345 Edited README.md via GitHub
John Hann authored
104 curl(['dep1', 'dep2', 'domReady' /* etc */], function (dep1, dep2) {
b46b353 changed the name of (and fixed) the dependency-chaining API to .next(…
unscriptable authored
105 // do something here
c1ee8af we can haz markdown!
unscriptable authored
106 });
2f2a139 added an example to the README
unscriptable authored
107
c1ee8af we can haz markdown!
unscriptable authored
108 Executes the callback when the dom is ready for manipulation AND
109 all dependencies have loaded.
20fd1ca Edited README.md via GitHub
John Hann authored
110
34ceaec cleaned up some API definitions
John Hann authored
111 * callback: No parameters except the domReady object
112 * errorback: Function to call if an exception occurred while loading
2f2a139 added an example to the README
unscriptable authored
113
11a6dc1 Edited README.md via GitHub
John Hann authored
114 ---------
d5d4eb3 updated to latest features
unscriptable authored
115 curl(['domReady', 'js!nonAMD.js!order', 'js!another.js!order']), function (domReady) {
cf5fb83 curl() now looks for promises returned from define()s -- either direc…
unscriptable authored
116 /* do something cool here */
c1ee8af we can haz markdown!
unscriptable authored
117 });
fc8f801 updated to version 0.3!
unscriptable authored
118
cf5fb83 curl() now looks for promises returned from define()s -- either direc…
unscriptable authored
119 Executes the function when the non-AMD javascript files are loaded and
120 the dom is ready. The another.js file will wait for the nonAMD.js file
121 before executing.
fc8f801 updated to version 0.3!
unscriptable authored
122
11a6dc1 Edited README.md via GitHub
John Hann authored
123 ---------
b46b353 changed the name of (and fixed) the dependency-chaining API to .next(…
unscriptable authored
124 curl(['js!nonAMD.js'])
125 .next(['dep1', 'dep2', 'dep3'], function (dep1, dep2, dep3) {
126 // do something before the dom is ready
127 })
128 .next(['domReady'])
129 .then(
130 function () {
131 // do something after the dom is ready
132 },
133 function (ex) {
134 // show an error to the user
135 }
136 );
137
20fbf55 added notes about CommonJS Modules 1.1 support
unscriptable authored
138 Executes callbacks in stages using `.next(deps, callback)`.
b46b353 changed the name of (and fixed) the dependency-chaining API to .next(…
unscriptable authored
139
11a6dc1 Edited README.md via GitHub
John Hann authored
140 ---------
949c3d3 Edited README.md via GitHub
John Hann authored
141
142 curl = {
143 baseUrl: '/path/to/my/js',
9e6e1a7 Updated TODO items and added more info about configuration paramaters
John Hann authored
144 pluginPath: 'for/some/reason/plugins/r/here',
949c3d3 Edited README.md via GitHub
John Hann authored
145 paths: {
146 curl: 'curl/src/curl',
147 cssx: 'cssx/src/cssx'
148 my: '../../my-lib/'
9e6e1a7 Updated TODO items and added more info about configuration paramaters
John Hann authored
149 },
150 apiName: 'someOtherName'
949c3d3 Edited README.md via GitHub
John Hann authored
151 };
152
d5d4eb3 updated to latest features
unscriptable authored
153 If called before the `<script>` that loads curl.js, configures curl.js. All of
154 the configuration parameters are optional. curl.js tries to do something sensible
9e6e1a7 Updated TODO items and added more info about configuration paramaters
John Hann authored
155 in their absence. :)
156
157 * baseUrl: the root folder to find all modules, default is the document's folder
158 * paths: a mapping of module paths to relative paths (from baseUrl)
159 * pluginPath: the place to find plugins when they are specified without a path
160 (e.g. "css!myCssFile" vs. "cssx/css!myCssFile") and there is no paths
161 mapping that applies.
d5d4eb3 updated to latest features
unscriptable authored
162 * apiName: an alternate name to `curl` and `require` for curl.js's global
163 variable
949c3d3 Edited README.md via GitHub
John Hann authored
164
165 ---------
20fbf55 added notes about CommonJS Modules 1.1 support
unscriptable authored
166
c1ee8af we can haz markdown!
unscriptable authored
167 define(['dep1', 'dep2', 'dep3' /* etc */], definition);
168 define(['dep1', 'dep2', 'dep3' /* etc */], module);
cf5fb83 curl() now looks for promises returned from define()s -- either direc…
unscriptable authored
169 define(['dep1', 'dep2', 'dep3' /* etc */], promise);
c1ee8af we can haz markdown!
unscriptable authored
170 define(module);
cf5fb83 curl() now looks for promises returned from define()s -- either direc…
unscriptable authored
171 define(promise);
c1ee8af we can haz markdown!
unscriptable authored
172 define(name, ['dep1', 'dep2', 'dep3' /* etc */], definition);
173 define(name, ['dep1', 'dep2', 'dep3' /* etc */], module);
cf5fb83 curl() now looks for promises returned from define()s -- either direc…
unscriptable authored
174 define(name, ['dep1', 'dep2', 'dep3' /* etc */], promise);
c1ee8af we can haz markdown!
unscriptable authored
175 define(name, module);
cf5fb83 curl() now looks for promises returned from define()s -- either direc…
unscriptable authored
176 define(name, promise);
39b5e54 updated README to reflect latest features
unscriptable authored
177
c1ee8af we can haz markdown!
unscriptable authored
178 Defines a module per the CommonJS AMD proposed specification.
20fd1ca Edited README.md via GitHub
John Hann authored
179
20fbf55 added notes about CommonJS Modules 1.1 support
unscriptable authored
180 * ['dep1', 'dep2', 'dep3']: Module names or plugin-prefixed resource files.
181 Dependencies may be named 'require', 'exports', or 'module' and will behave
182 as defined in the CommonJS Modules 1.1 proposal.
34ceaec cleaned up some API definitions
John Hann authored
183 * definition: Function called to define the module
184 * module: Any javascript object, function, constructor, or primitive
185 * promise: Object compatible with CommonJS Promises/A. Useful for further
cf5fb83 curl() now looks for promises returned from define()s -- either direc…
unscriptable authored
186 deferring resolution of the module.
34ceaec cleaned up some API definitions
John Hann authored
187 * name: String used to name a module (not necessary nor recommended)
39b5e54 updated README to reflect latest features
unscriptable authored
188
189 ----------------------------------------
190
2f2a139 added an example to the README
unscriptable authored
191 Very Simple Example
192 ===================
193
194 <script>
195
196 // configure curl
197 curl = {
198 paths: {
199 cssx: 'cssx/src/cssx/',
e8b5ef1 Edited README.md via GitHub
John Hann authored
200 stuff: 'my/stuff/
2f2a139 added an example to the README
unscriptable authored
201 }
202 };
203
204 </script>
205 <script src="../js/curl.js" type="text/javascript"></script>
206 <script type="text/javascript">
207
208 curl(
209 // fetch all of these resources ("dependencies")
210 [
211 'stuff/three', // an AMD module
212 'cssx/css!stuff/base', // a css file
213 'i18n!stuff/nls/strings', // a translation file
b46b353 changed the name of (and fixed) the dependency-chaining API to .next(…
unscriptable authored
214 'text!stuff/template.html', // an html template
215 'curl/domReady'
2f2a139 added an example to the README
unscriptable authored
216 ]
217 )
c1ee8af we can haz markdown!
unscriptable authored
218 // when they are loaded
2f2a139 added an example to the README
unscriptable authored
219 .then(
220 // execute this callback, passing all dependencies as params
b46b353 changed the name of (and fixed) the dependency-chaining API to .next(…
unscriptable authored
221 function (three, link, strings, template) {
cf5fb83 curl() now looks for promises returned from define()s -- either direc…
unscriptable authored
222 var body = document.body;
223 if (body) {
224 body.appendChild(document.createTextNode('three == ' + three.toString() + ' '));
225 body.appendChild(document.createElement('br'));
226 body.appendChild(document.createTextNode(strings.hello));
227 body.appendChild(document.createElement('div')).innerHTML = template;
228 }
2f2a139 added an example to the README
unscriptable authored
229 },
230 // execute this callback if there was a problem
231 function (ex) {
232 var msg = 'OH SNAP: ' + ex.message;
c1ee8af we can haz markdown!
unscriptable authored
233 alert(msg);
2f2a139 added an example to the README
unscriptable authored
234 }
235 );
236
237 </script>
238
e8b5ef1 Edited README.md via GitHub
John Hann authored
239 The file structure for this example would look as follows:
240
241 js/
242 curl/
243 plugin/
244 i18n.js
245 text.js
246 domReady.js
247 cssx/
248 src/
249 cssx/
250 css.js
251 my/
252 stuff/
253 nls/
254 strings.js
255 base.css
256 template.html
257 three.js
258 curl.js
259
2f2a139 added an example to the README
unscriptable authored
260 ----------------------------------------
261
fccc4e9 the start of a README
unscriptable authored
262 What is an asynchronous loader?
c1519b8 more tests
unscriptable authored
263 ===============================
fccc4e9 the start of a README
unscriptable authored
264
265 Web apps, especially large ones, require many modules and resources. Most of
266 these modules and resources need to be loaded at page load, but some may be
7d97cca minor tweaks
John Hann authored
267 loaded later, either in the background or "just in time". They also need to be
fccc4e9 the start of a README
unscriptable authored
268 loaded as quickly as possible.
269
bb87447 more README cleanup
unscriptable authored
270 The traditional way to load javascript modules is via a `<SCRIPT>` element in
271 an HTML page. Similarly, CSS files are loaded via a `<LINK>` element, and
fccc4e9 the start of a README
unscriptable authored
272 text resources are either loaded in the page or via XHR calls.
273
bb87447 more README cleanup
unscriptable authored
274 The problem with `<SCRIPT>` and `<LINK>` elements is that a browser must execute
fccc4e9 the start of a README
unscriptable authored
275 them sequentially since it has no idea if one may depend on another. It just
276 assumes the developer has placed them in the correct order and that there are
277 dependencies. (The term "synchronous loading" is used to describe this process
278 since the elements are executed in a single timeline.)
279
280 If there are no dependencies between two files, loading them sequentially is
281 a waste of time. These files could be loaded and executed in parallel (i.e
282 at the same time).
283
e14209e clarified README
John Hann authored
284 An asynchronous loader does just that: it loads javascript files (and
7d97cca minor tweaks
John Hann authored
285 other types of files) in parallel whenever possible.
fccc4e9 the start of a README
unscriptable authored
286
20f0204 minor clarififcations to README
unscriptable authored
287 curl.js has lots of company. Other async loaders include LABjs, Steal.js,
34a83a2 more tweaks
unscriptable authored
288 yepnope.js, $script.js, the Backdraft loader (bdLoad), and RequireJS.
fccc4e9 the start of a README
unscriptable authored
289
d5d4eb3 updated to latest features
unscriptable authored
290 [(a more complete list)](https://spreadsheets.google.com/ccc?key=0Aqln2akPWiMIdERkY3J2OXdOUVJDTkNSQ2ZsV3hoWVE&hl=en#gid=2)
949c3d3 Edited README.md via GitHub
John Hann authored
291
fccc4e9 the start of a README
unscriptable authored
292 ----------------------------------------
293
294 What is AMD?
c1519b8 more tests
unscriptable authored
295 ============
fccc4e9 the start of a README
unscriptable authored
296
297 Asynchronous Module Definition is the CommonJS proposed standard for
9bdd554 more about AMD and CommonJS
John Hann authored
298 javascript modules that can be loaded by asynchronous loaders. It defines
299 a simple API that developers can use to write their javascript modules so
300 that they may be loaded by any AMD-compliant loader.
301
302 [CommonJS AMD Proposal](http://wiki.commonjs.org/wiki/Modules/AsynchronousDefinition)
303
304 The AMD proposal follows the [CommonJS Modules](http://wiki.commonjs.org/wiki/Modules/1.1)
305 proposal as much as possible. Because of the way browsers load and
306 evaluate scripts, AMD can't follow it completely without causing significant
307 processing overhead. Instead, AMD allows us to place a lightweight wrapper
308 around javascript modules to help work around the shortcomings.
309
310 Ultimately, both proposals (AMD and Modules 1.1) are in preparation for an
311 official [javascript modules](http://wiki.ecmascript.org/doku.php?id=harmony:modules)
312 specification and eventual implementation in browsers.
313
314 If you don't want to wait for official javascript modules, then don't. The future
315 is now. AMD works now -- and it's awesome.
fccc4e9 the start of a README
unscriptable authored
316
317 AMD's API focuses on two globally-available functions: require() and define().
318 require() specifies a list of dependent modules or resources that must be
319 loaded before running a set of code. This code resides in a callback function
320 that is executed asynchronously, i.e. it runs later, not in the current
e14209e clarified README
John Hann authored
321 "thread". Specifically, it executes when all of the dependencies are loaded
322 and ready.
323
1d8f14b pdated to latest version and removed all references to the old public…
unscriptable authored
324 Actually, the proposal says that the public require() function could have a
325 different name -- or could even be implemented differently. To keep confusion to
326 a minimum curl.js uses `curl()` for the public API. You may rename this API
327 back to `require()` by supplying the `apiName` config param (apiName: "require").
e14209e clarified README
John Hann authored
328
1d8f14b pdated to latest version and removed all references to the old public…
unscriptable authored
329 It's only important that the define() method be consistent. This is the method
e14209e clarified README
John Hann authored
330 that tells the loader what modules have been loaded by a script. define() also
331 specifies a list of dependencies and a callback function that defines and/or
332 creates the resource when the dependencies are ready. Optionally, define()
333 also takes a name parameter, but this is mainly for build tools and optimizers.
fccc4e9 the start of a README
unscriptable authored
334
1d8f14b pdated to latest version and removed all references to the old public…
unscriptable authored
335 Inside the `define()`, the `require()` method acts like other AMD loaders.
336
fccc4e9 the start of a README
unscriptable authored
337 AMD's API also helps code reuse by providing compatibility with CommonJS
338 server modules. AMD-compliant loaders support the same require() syntax and
339 argument signatures as server-side javascript (ssjs) modules.
340
341 Not all async loaders are AMD-compliant. Of the list above, only the following
342 are AMD-compliant:
343
851d03e getting the hang of this markdown stuff
unscriptable authored
344 curl.js <http://github.com/unscriptable/curl>
34a83a2 more tweaks
unscriptable authored
345
851d03e getting the hang of this markdown stuff
unscriptable authored
346 RequireJS <http://requirejs.org/>
34a83a2 more tweaks
unscriptable authored
347
851d03e getting the hang of this markdown stuff
unscriptable authored
348 backdraft loader <http://http://bdframework.org/bdLoad>
e14209e clarified README
John Hann authored
349
350 The beauty of AMD loaders is their ability to remove the drudgery of manually
351 managing dependencies. Since all dependencies are listed within the
352 modules, the loader will ensure that everything is loaded into the browser --
353 and in the right order.
fccc4e9 the start of a README
unscriptable authored
354
355 ----------------------------------------
356
357 What makes curl different from other AMD loaders?
c1519b8 more tests
unscriptable authored
358 =================================================
fccc4e9 the start of a README
unscriptable authored
359
949c3d3 Edited README.md via GitHub
John Hann authored
360 curl.js is much smaller than other AMD loaders. Less than 1/2 the size of the
ca44d3b updated docs to reflect new feature: require() returns a Promise
unscriptable authored
361 others in the list above. It's able to achieve this via a Promises-based
949c3d3 Edited README.md via GitHub
John Hann authored
362 design. (Promises are another [CommonJS proposed standard](http://wiki.commonjs.org/wiki/Promises).)
fccc4e9 the start of a README
unscriptable authored
363
ca44d3b updated docs to reflect new feature: require() returns a Promise
unscriptable authored
364 curl.js communicates with it's plugins via Promises, rather than a simple
fccc4e9 the start of a README
unscriptable authored
365 callback function. This allows proactive error handling, rather than detecting
366 problems via a timeout, which can be tricky to set correctly. curl does this in
367 a backwards-compatible way so AMD-compliant plugins will still work in curl.
368
1d8f14b pdated to latest version and removed all references to the old public…
unscriptable authored
369 curl.js will also return a promise from curl() calls. This allows you to
ca44d3b updated docs to reflect new feature: require() returns a Promise
unscriptable authored
370 write code like this:
371
1d8f14b pdated to latest version and removed all references to the old public…
unscriptable authored
372 curl(
c1ee8af we can haz markdown!
unscriptable authored
373 [
374 'myApp/moduleA',
375 'myApp/moduleB'
376 ],
377 ).then(
378 function success (A, B) {
379 // load myApp here!
380 },
381 function failure (ex) {
382 alert('myApp didn't load. reason: ' + ex.message);
383 }
384 );
ca44d3b updated docs to reflect new feature: require() returns a Promise
unscriptable authored
385
fccc4e9 the start of a README
unscriptable authored
386 ----------------------------------------
387
6c0f0fe bumped version to 0.2 and added some content about non-AMD files
unscriptable authored
388 Can curl.js work with non-AMD javascript files?
389 ===============================================
390
391 Yes, but why would you? Once you start using AMD, you'll never go back! :)
392
393 You may use non-AMD javascript files by specifying the js! plugin prefix
394 like this:
395
1d8f14b pdated to latest version and removed all references to the old public…
unscriptable authored
396 curl(
c1ee8af we can haz markdown!
unscriptable authored
397 [
d5d4eb3 updated to latest features
unscriptable authored
398 'js!plainOldJsFile1.js!order',
399 'js!anotherPlainOldJsFile.js!order'
c1ee8af we can haz markdown!
unscriptable authored
400 ]
401 ).then(
402 function () {
403 /* do something with your plain, boring javascript files */
404 },
405 function () {
406 /* do something if any fail to load */
407 }
408 );
409
d5d4eb3 updated to latest features
unscriptable authored
410 The !order suffix instructs curl.js to wait for previous scripts to execute
411 before executing. It downloads in parallel with the previous scripts,
c1ee8af we can haz markdown!
unscriptable authored
412 unless you specify jsPrefetch:false in the config. Be sure to have proper
413 cache headers set if you plan to use jsPrefetch:true or scripts will get
414 downloaded twice.
6c0f0fe bumped version to 0.2 and added some content about non-AMD files
unscriptable authored
415
416 ----------------------------------------
417
39b5e54 updated README to reflect latest features
unscriptable authored
418 Can curl.js load non-javascript files?
419 =======================
420
421 Yes, curl.js follows the CommonJS Loader Plugin specification, so you can use
422 any compatible plugin. The following plugins are included:
423
424 js! -- loads non-AMD javascript files
34a83a2 more tweaks
unscriptable authored
425
39b5e54 updated README to reflect latest features
unscriptable authored
426 text! -- loads text files
427
428 You can also load css files by using the AMD plugin at the following repo:
851d03e getting the hang of this markdown stuff
unscriptable authored
429 <https://github.com/unscriptable/cssx/blob/master/src/cssx/css.js>
39b5e54 updated README to reflect latest features
unscriptable authored
430
431 The following plugins are planned:
432
433 i18n! -- loads text strings and other locale-specific constants
34a83a2 more tweaks
unscriptable authored
434
39b5e54 updated README to reflect latest features
unscriptable authored
435 cssx! -- loads and automatically shims css files for older browsers
436
437 ----------------------------------------
438
ee4b740 moar text in the README
unscriptable authored
439 How are modules loaded?
c1519b8 more tests
unscriptable authored
440 =======================
ee4b740 moar text in the README
unscriptable authored
441
949c3d3 Edited README.md via GitHub
John Hann authored
442 curl.js uses `<script>` element injection rather than XHR. This allows curl.js to
443 load cross-domain scripts as well as local scripts.
444
d5d4eb3 updated to latest features
unscriptable authored
445 To find scripts and other resources, curl uses module names. A module name
446 looks just like a file path, but typically without the file extension. If a
447 module requires a plugin in order to load correctly, it will have a prefix
448 delimited by a "!" and will also often have a file extension when a plugin
449 may load different types of files.
949c3d3 Edited README.md via GitHub
John Hann authored
450
451 Some examples of module names:
452
453 * dojo/store/JsonRest
454 * my/lib/string/format
455 * js!my/lib/js/plain-old-js.js
456 * css!my/styles/reset.css
457 * http://some-cdn/uber/module
458
459 By default, curl.js will look in the same folder as the current document's location.
460 For instance, if your web page is located at `http://my-domain/apps/myApp.html`,
461 curl.js will look for the JsonRest module at `http://my-domain/apps/dojo/store/JsonRest.js`.
462
463 You can tell curl.js to find modules in other locations by specifying a baseUrl or
464 individual paths for each of your libraries. For example, if you specify a baseUrl of
465 `/resources/` and the following paths:
466
467 paths: {
468 dojo: "third-party/dojo",
469 css: "third-party/cssx/css",
470 my: "my-cool-app-v1.3",
471 "my/lib/js": "old-js-libs"
472 }
473
474 Then the modules listed above will be sought in the following locations:
475
476 * /resources/third-party/dojo/store/JsonRest.js
477 * /resources/my-cool-app-v1.3/lib/string/format.js
478 * /resources/old-js-libs/plain-old-js.js
479 * /resources/my-cool-app-v1.3/styles/reset.css
480 * http://some-cdn/uber/module.js
481
d5d4eb3 updated to latest features
unscriptable authored
482 Note: you will need to create a path to curl's plugins and other modules if the
483 curl folder isn't directly under the same folder as your web page. curl.js uses
484 the same mechanism to find its own modules.
949c3d3 Edited README.md via GitHub
John Hann authored
485
486 TODO: explain the pluginPath configuration parameter.
ee4b740 moar text in the README
unscriptable authored
487
488 ----------------------------------------
489
490 What are AMD plugins?
c1519b8 more tests
unscriptable authored
491 =====================
ee4b740 moar text in the README
unscriptable authored
492
493 AMD supports the notion of plugins. Plugins are AMD modules that can be used to
494 load javascript modules -- or other types of resources. curl comes with several
495 plugins already, including a text plugin (for templates or other text
496 resources), a css plugin, a sync plugin (for loading modules synchronously),
497 and a debug plugin (for collecting and logging details of the inner workings of
498 curl).
499
500 Plugins are designated by a prefix on the name of the module or resource to be
501 loaded. They are delineated by a ! symbol. The following example shows the use
502 of some plugins:
503
c1ee8af we can haz markdown!
unscriptable authored
504 define(
505 [
506 'text!myTemplate.html',
507 'css!myCssFile'
508 ],
509 function (templateString, cssLinkNode) {
510 // do something with the template and css here
511 }
512 );
ee4b740 moar text in the README
unscriptable authored
513
514 Since plugins are just AMD modules, they would typically be referenced using
515 their fully-pathed names. curl provides a pluginPath configuration option that
516 allows you to specify the folder where [most of] your plugins reside so you
517 don't have to specify their full paths. This also helps with compatibility
518 with other AMD loaders that assume that certain plugins are bundled and
519 internally mapped.
520
521 If one or more of your plugins does not reside in the folder specified by the
522 pluginPath config option, you can use its full path or you can specify a path
523 for it in curl's paths config object.
524
c1ee8af we can haz markdown!
unscriptable authored
525 // example of a fully-pathed plugin under the cssx folder
526 define(['cssx/cssx!myCssFile'], function (cssxDef) {
527 // do some awesome css stuff here
528 });
ee4b740 moar text in the README
unscriptable authored
529
530 (cssx is the Cujo Style Sheet eXtender AMD plugin that repairs browser css
531 deficiencies on-the-fly.)
532
533 Plugins can also have configuration options. Global options can be specified
534 on curl's configuration object. Options can also be supplied to plugins via
535 suffixes. Suffixes are also delineated by the ! symbol. Here's an example of
536 a plugin using options:
537
c1ee8af we can haz markdown!
unscriptable authored
538 // don't try to repair IE6-8 opacity issues in my css file
539 define(['cssx/cssx!myCssFile!ignore:opacity'], function (cssxDef) {
540 // do some awesome css stuff here
541 });
ee4b740 moar text in the README
unscriptable authored
542
543 ----------------------------------------
544
fccc4e9 the start of a README
unscriptable authored
545 How do I use curl.js?
c1519b8 more tests
unscriptable authored
546 =====================
ee4b740 moar text in the README
unscriptable authored
547
1d8f14b pdated to latest version and removed all references to the old public…
unscriptable authored
548 1. Optional: Learn about AMD-formatted javascript modules if you don't already
549 know how.
949c3d3 Edited README.md via GitHub
John Hann authored
550 2. Clone or download curl to your local machine or server.
1d8f14b pdated to latest version and removed all references to the old public…
unscriptable authored
551 3. Figure out the baseUrl and paths configuration that makes sense for your
552 project.
553 4. Check out the "API at a glance" section above to figure out which loading
554 methodology you want to use.
949c3d3 Edited README.md via GitHub
John Hann authored
555 5. Study the "Very Simple Example" and some of the test files.
556 6. Try it on your own files.
39b5e54 updated README to reflect latest features
unscriptable authored
557
ee4b740 moar text in the README
unscriptable authored
558 ----------------------------------------
559
e14209e clarified README
John Hann authored
560 Too Many Modules!
c1519b8 more tests
unscriptable authored
561 =================
e14209e clarified README
John Hann authored
562
ee4b740 moar text in the README
unscriptable authored
563 I have dozens (or hundreds) of modules. Even with parallel loading, the
20f0204 minor clarififcations to README
unscriptable authored
564 performance sucks! What can I do about that?
ee4b740 moar text in the README
unscriptable authored
565
566 True! No parallel loader can lessen the latency required to create an HTTP
567 connection. If you have dozens or hundreds of files to download, it's going to
568 take time to initiate each of the connections.
569
570 However, there are tools to that are designed to fix this problem! There are
571 builders and compilers. dojo users are probably already familiar with dojo's
572 build tool and optimizer. RequireJS comes with a build tool and Google's
573 Closure compiler.
574
575 The build tool is used to concatenate several modules (and/or resources)
576 into just a few files. It does this by following the dependency chain
1d8f14b pdated to latest version and removed all references to the old public…
unscriptable authored
577 specified in the curl(), define(), and require() calls. You can specify which
578 top-level modules or resources are in each file and the build tool finds the
579 rest.
ee4b740 moar text in the README
unscriptable authored
580
581 After the build tool creates the concatenated files, the files can be passed
582 into a compiler (also called a shrinker or compressor).
583
584 We're writing curl to be compatible with RequireJS's build tool, but there's
585 also another cujo project in the pipeline: cram. Cram is the Cujo Resource
949c3d3 Edited README.md via GitHub
John Hann authored
586 Assembler. cram will be ready by mid 2011, so use another build tool or a
ee4b740 moar text in the README
unscriptable authored
587 custom shell script in the mean time.
20f0204 minor clarififcations to README
unscriptable authored
588
589 ----------------------------------------
0e0a920 added kudos for Bryan and James
unscriptable authored
590
4a92fee notes about Packages 1.1 support and updates to What's New and size
unscriptable authored
591 CommonJS Package Support
592 ========================
593
594 cujo.js supports the CommonJS Packages 1.1 specification. Packages are
595 defined in the packages configuration parameter:
596
597 cujo = {
598 baseUrl: 'path/to/js',
599 packages: {
600 'my-package': {
601 path: 'path/to/my-package',
602 main: 'main/main-module-file',
603 lib: 'location/of/other/modules'
604 }
605 }
606 };
607
608 The path property describes where to find the package in relation to the
609 baseUrl parameter. The main and lib properties describe where to find modules
610 inside the package. The main property gives the relative path to the pacage's
611 main module. The lib property reflects the path to all other modules in the
612 package.
613
614 The main module is always executed before any other modules are executed in
615 the package. Essentially, the main module becomes an automatic dependency.
616
617 In the example above, the main module of the package can be obtained as follows
618
1d8f14b pdated to latest version and removed all references to the old public…
unscriptable authored
619 curl(['my-package'], callback);
4a92fee notes about Packages 1.1 support and updates to What's New and size
unscriptable authored
620
621 and will be fetched from the following path:
622
623 path/to/js/path/to/my-package/main/main-module-file.js
624
625 Some other file in the package would be obtained as follows:
626
1d8f14b pdated to latest version and removed all references to the old public…
unscriptable authored
627 curl(['my-package/other-module'], callback);
4a92fee notes about Packages 1.1 support and updates to What's New and size
unscriptable authored
628
629 and will be fetched from the following path:
630
631 path/to/js/path/to/my-package/location/of/other/modules/other-module.js
632
633 ----------------------------------------
634
f778b1f Edited README.md via GitHub
John Hann authored
635 What is cujo?
636 =====================
637
638 cujo.js is a web app development platform. It employs MVC, IOC, AMD
639 and lots of other TLAs. :) curl.js is one of the many micro-libs we're pulling
640 out of cujo.js. Our goal is to make the advanced concepts in cujo.js more
641 palatable by breaking them down into easier-to-grok chunks. Other cujo.js
642 libs include:
643
644 [canhaz](https://github.com/briancavalier/canhaz): a project and code bootstrapping tool that will save you tons of typing.
645 [wire](https://github.com/briancavalier/wire): an application bootstrap, configuration, and assembly tool based on the principles of Inversion of Control, and Dependency Injection.
646 [cssx](https://github.com/unscriptable/cssx): library for extending css in older browsers
647 [cram](https://github.com/unscriptable/cram): a [forthcoming] javascript compressor, concatenator, and optimizer meant to be used with curl.js
648
649 Kudos
650 =================
651
b46b353 changed the name of (and fixed) the dependency-chaining API to .next(…
unscriptable authored
652 Many thanks to Bryan Forbes (@bryanforbes) for helping to clean up my code and
653 for making cujo's domReady much more robust.
851d03e getting the hang of this markdown stuff
unscriptable authored
654 More about Bryan: <http://www.reigndropsfall.net/>
12c2516 some more credit where credit is due
unscriptable authored
655
b46b353 changed the name of (and fixed) the dependency-chaining API to .next(…
unscriptable authored
656 Kudos also to James Burke (@jrburke) who instigated the CommonJS AMD proposal
657 and paved the way to create AMD-style loaders.
851d03e getting the hang of this markdown stuff
unscriptable authored
658 More about James: <http://tagneto.blogspot.com/>
c1ee8af we can haz markdown!
unscriptable authored
659
846ab07 updated README
unscriptable authored
660 Shout out to Kris Zyp (@kriszyp) for excellent ideas and feedback and to Kyle
b46b353 changed the name of (and fixed) the dependency-chaining API to .next(…
unscriptable authored
661 Simpson (@getify) who is inarguably the godfather of javascript loading.
Something went wrong with that request. Please try again.