Skip to content
This repository
Newer
Older
100644 662 lines (506 sloc) 23.817 kb
9bdd5541 »
2011-03-25 more about AMD and CommonJS
1 curl (Cujo Resource Loader)
e14209e2 »
2011-02-17 clarified README
2 =====================
fccc4e98 »
2011-02-06 the start of a README
3
1d8f14b5 »
2011-05-18 pdated to latest version and removed all references to the old public…
4 version 0.4.4
20fbf55b »
2011-03-31 added notes about CommonJS Modules 1.1 support
5
6 What's New?
7
085ba809 »
2011-05-18 typo
8 * `require` is no longer an alias for `curl` unless you set the
1d8f14b5 »
2011-05-18 pdated to latest version and removed all references to the old public…
9 apiName:'require' config param
10 * dojo 1.6 support was moved to a separate module and/or built curl.js
d9de6eaa »
2011-04-22 fixed !order option for js! plugin (all browsers except firefox) and …
11 * Fixed !order option for js! plugin in non-Firefox browsers (0.4.3)
a8f7f9d1 »
2011-04-22 bumped to version 0.4.2 and added version notes
12 * Fixed the compiled version in 0.4.2 (dist/ folder)
4a92fee2 »
2011-04-19 notes about Packages 1.1 support and updates to What's New and size
13 * Several fixes to path and package mapping were made in 0.4.1
20fbf55b »
2011-03-31 added notes about CommonJS Modules 1.1 support
14 * CommonJS Modules 1.1
d5d4eb3c »
2011-04-16 updated to latest features
15 * CommonJS Packages 1.1
4a92fee2 »
2011-04-19 notes about Packages 1.1 support and updates to What's New and size
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)
ae6d718e »
2011-03-31 bumped version to 0.3.3
19 * !noexec suffix for js! plugin (load, but don't execute)
d5d4eb3c »
2011-04-16 updated to latest features
20 * !wait suffix was renamed to !order (and semantics were changed)
21 * async=false
bb874472 »
2011-03-23 more README cleanup
22
23 TODO:
24
085ba809 »
2011-05-18 typo
25 * finish i18n plugin (eta: June)
26 * create dojo 1.6 tests
e8b5ef1b »
2011-04-23 Edited README.md via GitHub
27 * notes about using JSONP (it works for objects, arrays, functions, numbers
65587451 »
2011-04-15 corrected: JSONP works for fetching remote strings, too
28 and strings! use ?callback=define)
a8f7f9d1 »
2011-04-22 bumped to version 0.4.2 and added version notes
29 * use CommonJS file structure (lib/ instead of src/)
fccc4e98 »
2011-02-06 the start of a README
30
31 ----------------------------------------
32
33 What is curl.js?
c1519b89 »
2011-02-17 more tests
34 ================
fccc4e98 »
2011-02-06 the start of a README
35
17ceecb0 »
2011-06-07 cuz it's fast man
36 curl.js is a small and very fast AMD-compliant asynchronous loader.
1d8f14b5 »
2011-05-18 pdated to latest version and removed all references to the old public…
37 Size: 4.2KB (2.1KB gzipped) using Google's Closure Compiler.
fc8f801a »
2011-03-23 updated to version 0.3!
38
d5d4eb3c »
2011-04-16 updated to latest features
39 If you'd like to use curl.js for non-AMD modules (ordinary javascript files),
40 you'll want to use the version with the js! plugin built in. You may also
41 want to build-in the domReady module. The combined curl+js+domReady loader
42 is still only 6.0KB (2.7KB gzipped).
fc8f801a »
2011-03-23 updated to version 0.3!
43
d5d4eb3c »
2011-04-16 updated to latest features
44 What the heck is "cujo"? cujo.js is a web app development platform.
45 See the bottom of this file for more info.
f778b1fd »
2011-03-25 Edited README.md via GitHub
46
fccc4e98 »
2011-02-06 the start of a README
47 ----------------------------------------
48
39b5e548 »
2011-03-14 updated README to reflect latest features
49 Features at a glance:
50 =====================
51
f125b8c9 »
2011-03-25 Edited README.md via GitHub
52 * Loads CommonJS AMD-formatted javascript modules in parallel (fast!)
20fbf55b »
2011-03-31 added notes about CommonJS Modules 1.1 support
53 * Loads CommonJS Modules (v1.1 when wrapped in a `define()`) (fast!)
d5d4eb3c »
2011-04-16 updated to latest features
54 * Loads CommonJS Packages (v1.1 modules wrapped in a `define()`) (fast!)
f125b8c9 »
2011-03-25 Edited README.md via GitHub
55 * Loads non-AMD javascript files in parallel, too (fast! via js! plugin)
56 * Loads CSS files and text files in parallel (fast! via plugins)
39b5e548 »
2011-03-14 updated README to reflect latest features
57 * Waits for dependencies (js, css, text, etc) before executing javascript
f125b8c9 »
2011-03-25 Edited README.md via GitHub
58 * Waits for domReady, if/when desired
59 * Allows for virtually limitless combinations of files and dependencies
39b5e548 »
2011-03-14 updated README to reflect latest features
60 * Tested with Chrome, FF3+, Safari 3.2+, IE6-8, Opera 9.5+
61
17ceecb0 »
2011-06-07 cuz it's fast man
62 Oh, did we mention? It's fast! It's even faster than the leading non-AMD
63 script loaders.
f125b8c9 »
2011-03-25 Edited README.md via GitHub
64
39b5e548 »
2011-03-14 updated README to reflect latest features
65 ----------------------------------------
66
67 API at a glance
68 ===============
69
70
c1ee8af9 »
2011-03-23 we can haz markdown!
71 curl(['dep1', 'dep2', 'dep3' /* etc */], callback);
39b5e548 »
2011-03-14 updated README to reflect latest features
72
c1ee8af9 »
2011-03-23 we can haz markdown!
73 Loads dependencies and the executes callback.
20fd1caa »
2011-03-25 Edited README.md via GitHub
74
34ceaecf »
2011-03-25 cleaned up some API definitions
75 * ['dep1', 'dep2', 'dep3']: Module names or plugin-prefixed resource files
d5d4eb3c »
2011-04-16 updated to latest features
76 * callback: Function to receive modules or resources. This is where you'd
77 typically start up your app.
39b5e548 »
2011-03-14 updated README to reflect latest features
78
11a6dc14 »
2011-03-25 Edited README.md via GitHub
79 ---------
c1ee8af9 »
2011-03-23 we can haz markdown!
80 curl(['dep1', 'dep2', 'dep3' /* etc */])
81 .then(callback, errorback);
39b5e548 »
2011-03-14 updated README to reflect latest features
82
c1ee8af9 »
2011-03-23 we can haz markdown!
83 Promises-based API for executing callbacks.
20fd1caa »
2011-03-25 Edited README.md via GitHub
84
34ceaecf »
2011-03-25 cleaned up some API definitions
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
39b5e548 »
2011-03-14 updated README to reflect latest features
88
11a6dc14 »
2011-03-25 Edited README.md via GitHub
89 ---------
c1ee8af9 »
2011-03-23 we can haz markdown!
90 curl(config, ['dep1', 'dep2', 'dep3' /* etc */], callback);
39b5e548 »
2011-03-14 updated README to reflect latest features
91
c1ee8af9 »
2011-03-23 we can haz markdown!
92 Specify configuration options, load dependencies, and execute callback.
20fd1caa »
2011-03-25 Edited README.md via GitHub
93
34ceaecf »
2011-03-25 cleaned up some API definitions
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
39b5e548 »
2011-03-14 updated README to reflect latest features
97
11a6dc14 »
2011-03-25 Edited README.md via GitHub
98 ---------
c1ee8af9 »
2011-03-23 we can haz markdown!
99 curl(['domReady', 'dep2', 'dep3' /* etc */])
100 .then(
cf5fb83f »
2011-03-23 curl() now looks for promises returned from define()s -- either direc…
101 callback,
c1ee8af9 »
2011-03-23 we can haz markdown!
102 errorback
103 );
67c13458 »
2011-03-24 Edited README.md via GitHub
104 curl(['dep1', 'dep2', 'domReady' /* etc */], function (dep1, dep2) {
b46b3532 »
2011-03-23 changed the name of (and fixed) the dependency-chaining API to .next(…
105 // do something here
c1ee8af9 »
2011-03-23 we can haz markdown!
106 });
2f2a1395 »
2011-03-15 added an example to the README
107
c1ee8af9 »
2011-03-23 we can haz markdown!
108 Executes the callback when the dom is ready for manipulation AND
109 all dependencies have loaded.
20fd1caa »
2011-03-25 Edited README.md via GitHub
110
34ceaecf »
2011-03-25 cleaned up some API definitions
111 * callback: No parameters except the domReady object
112 * errorback: Function to call if an exception occurred while loading
2f2a1395 »
2011-03-15 added an example to the README
113
11a6dc14 »
2011-03-25 Edited README.md via GitHub
114 ---------
d5d4eb3c »
2011-04-16 updated to latest features
115 curl(['domReady', 'js!nonAMD.js!order', 'js!another.js!order']), function (domReady) {
cf5fb83f »
2011-03-23 curl() now looks for promises returned from define()s -- either direc…
116 /* do something cool here */
c1ee8af9 »
2011-03-23 we can haz markdown!
117 });
fc8f801a »
2011-03-23 updated to version 0.3!
118
cf5fb83f »
2011-03-23 curl() now looks for promises returned from define()s -- either direc…
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.
fc8f801a »
2011-03-23 updated to version 0.3!
122
11a6dc14 »
2011-03-25 Edited README.md via GitHub
123 ---------
b46b3532 »
2011-03-23 changed the name of (and fixed) the dependency-chaining API to .next(…
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
20fbf55b »
2011-03-31 added notes about CommonJS Modules 1.1 support
138 Executes callbacks in stages using `.next(deps, callback)`.
b46b3532 »
2011-03-23 changed the name of (and fixed) the dependency-chaining API to .next(…
139
11a6dc14 »
2011-03-25 Edited README.md via GitHub
140 ---------
949c3d33 »
2011-03-25 Edited README.md via GitHub
141
142 curl = {
143 baseUrl: '/path/to/my/js',
9e6e1a7e »
2011-03-30 Updated TODO items and added more info about configuration paramaters
144 pluginPath: 'for/some/reason/plugins/r/here',
949c3d33 »
2011-03-25 Edited README.md via GitHub
145 paths: {
146 curl: 'curl/src/curl',
147 cssx: 'cssx/src/cssx'
148 my: '../../my-lib/'
9e6e1a7e »
2011-03-30 Updated TODO items and added more info about configuration paramaters
149 },
150 apiName: 'someOtherName'
949c3d33 »
2011-03-25 Edited README.md via GitHub
151 };
152
d5d4eb3c »
2011-04-16 updated to latest features
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
9e6e1a7e »
2011-03-30 Updated TODO items and added more info about configuration paramaters
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.
d5d4eb3c »
2011-04-16 updated to latest features
162 * apiName: an alternate name to `curl` and `require` for curl.js's global
163 variable
949c3d33 »
2011-03-25 Edited README.md via GitHub
164
165 ---------
20fbf55b »
2011-03-31 added notes about CommonJS Modules 1.1 support
166
c1ee8af9 »
2011-03-23 we can haz markdown!
167 define(['dep1', 'dep2', 'dep3' /* etc */], definition);
168 define(['dep1', 'dep2', 'dep3' /* etc */], module);
cf5fb83f »
2011-03-23 curl() now looks for promises returned from define()s -- either direc…
169 define(['dep1', 'dep2', 'dep3' /* etc */], promise);
c1ee8af9 »
2011-03-23 we can haz markdown!
170 define(module);
cf5fb83f »
2011-03-23 curl() now looks for promises returned from define()s -- either direc…
171 define(promise);
c1ee8af9 »
2011-03-23 we can haz markdown!
172 define(name, ['dep1', 'dep2', 'dep3' /* etc */], definition);
173 define(name, ['dep1', 'dep2', 'dep3' /* etc */], module);
cf5fb83f »
2011-03-23 curl() now looks for promises returned from define()s -- either direc…
174 define(name, ['dep1', 'dep2', 'dep3' /* etc */], promise);
c1ee8af9 »
2011-03-23 we can haz markdown!
175 define(name, module);
cf5fb83f »
2011-03-23 curl() now looks for promises returned from define()s -- either direc…
176 define(name, promise);
39b5e548 »
2011-03-14 updated README to reflect latest features
177
c1ee8af9 »
2011-03-23 we can haz markdown!
178 Defines a module per the CommonJS AMD proposed specification.
20fd1caa »
2011-03-25 Edited README.md via GitHub
179
20fbf55b »
2011-03-31 added notes about CommonJS Modules 1.1 support
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.
34ceaecf »
2011-03-25 cleaned up some API definitions
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
cf5fb83f »
2011-03-23 curl() now looks for promises returned from define()s -- either direc…
186 deferring resolution of the module.
34ceaecf »
2011-03-25 cleaned up some API definitions
187 * name: String used to name a module (not necessary nor recommended)
39b5e548 »
2011-03-14 updated README to reflect latest features
188
189 ----------------------------------------
190
2f2a1395 »
2011-03-15 added an example to the README
191 Very Simple Example
192 ===================
193
194 <script>
195
196 // configure curl
197 curl = {
198 paths: {
199 cssx: 'cssx/src/cssx/',
e8b5ef1b »
2011-04-23 Edited README.md via GitHub
200 stuff: 'my/stuff/
2f2a1395 »
2011-03-15 added an example to the README
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
b46b3532 »
2011-03-23 changed the name of (and fixed) the dependency-chaining API to .next(…
214 'text!stuff/template.html', // an html template
215 'curl/domReady'
2f2a1395 »
2011-03-15 added an example to the README
216 ]
217 )
c1ee8af9 »
2011-03-23 we can haz markdown!
218 // when they are loaded
2f2a1395 »
2011-03-15 added an example to the README
219 .then(
220 // execute this callback, passing all dependencies as params
b46b3532 »
2011-03-23 changed the name of (and fixed) the dependency-chaining API to .next(…
221 function (three, link, strings, template) {
cf5fb83f »
2011-03-23 curl() now looks for promises returned from define()s -- either direc…
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 }
2f2a1395 »
2011-03-15 added an example to the README
229 },
230 // execute this callback if there was a problem
231 function (ex) {
232 var msg = 'OH SNAP: ' + ex.message;
c1ee8af9 »
2011-03-23 we can haz markdown!
233 alert(msg);
2f2a1395 »
2011-03-15 added an example to the README
234 }
235 );
236
237 </script>
238
e8b5ef1b »
2011-04-23 Edited README.md via GitHub
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
2f2a1395 »
2011-03-15 added an example to the README
260 ----------------------------------------
261
fccc4e98 »
2011-02-06 the start of a README
262 What is an asynchronous loader?
c1519b89 »
2011-02-17 more tests
263 ===============================
fccc4e98 »
2011-02-06 the start of a README
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
7d97cca3 »
2011-03-06 minor tweaks
267 loaded later, either in the background or "just in time". They also need to be
fccc4e98 »
2011-02-06 the start of a README
268 loaded as quickly as possible.
269
bb874472 »
2011-03-23 more README cleanup
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
fccc4e98 »
2011-02-06 the start of a README
272 text resources are either loaded in the page or via XHR calls.
273
bb874472 »
2011-03-23 more README cleanup
274 The problem with `<SCRIPT>` and `<LINK>` elements is that a browser must execute
fccc4e98 »
2011-02-06 the start of a README
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
e14209e2 »
2011-02-17 clarified README
284 An asynchronous loader does just that: it loads javascript files (and
7d97cca3 »
2011-03-06 minor tweaks
285 other types of files) in parallel whenever possible.
fccc4e98 »
2011-02-06 the start of a README
286
20f02044 »
2011-02-07 minor clarififcations to README
287 curl.js has lots of company. Other async loaders include LABjs, Steal.js,
34a83a22 »
2011-03-23 more tweaks
288 yepnope.js, $script.js, the Backdraft loader (bdLoad), and RequireJS.
fccc4e98 »
2011-02-06 the start of a README
289
d5d4eb3c »
2011-04-16 updated to latest features
290 [(a more complete list)](https://spreadsheets.google.com/ccc?key=0Aqln2akPWiMIdERkY3J2OXdOUVJDTkNSQ2ZsV3hoWVE&hl=en#gid=2)
949c3d33 »
2011-03-25 Edited README.md via GitHub
291
fccc4e98 »
2011-02-06 the start of a README
292 ----------------------------------------
293
294 What is AMD?
c1519b89 »
2011-02-17 more tests
295 ============
fccc4e98 »
2011-02-06 the start of a README
296
297 Asynchronous Module Definition is the CommonJS proposed standard for
9bdd5541 »
2011-03-25 more about AMD and CommonJS
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.
fccc4e98 »
2011-02-06 the start of a README
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
e14209e2 »
2011-02-17 clarified README
321 "thread". Specifically, it executes when all of the dependencies are loaded
322 and ready.
323
1d8f14b5 »
2011-05-18 pdated to latest version and removed all references to the old public…
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").
e14209e2 »
2011-02-17 clarified README
328
1d8f14b5 »
2011-05-18 pdated to latest version and removed all references to the old public…
329 It's only important that the define() method be consistent. This is the method
e14209e2 »
2011-02-17 clarified README
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.
fccc4e98 »
2011-02-06 the start of a README
334
1d8f14b5 »
2011-05-18 pdated to latest version and removed all references to the old public…
335 Inside the `define()`, the `require()` method acts like other AMD loaders.
336
fccc4e98 »
2011-02-06 the start of a README
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
851d03e6 »
2011-03-23 getting the hang of this markdown stuff
344 curl.js <http://github.com/unscriptable/curl>
34a83a22 »
2011-03-23 more tweaks
345
851d03e6 »
2011-03-23 getting the hang of this markdown stuff
346 RequireJS <http://requirejs.org/>
34a83a22 »
2011-03-23 more tweaks
347
9cdc2280 »
2011-05-27 Trivial README edits. Fixed Backdraft links and added links to @twitt…
348 backdraft loader <http://bdframework.org/bdLoad>
e14209e2 »
2011-02-17 clarified README
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.
fccc4e98 »
2011-02-06 the start of a README
354
355 ----------------------------------------
356
357 What makes curl different from other AMD loaders?
c1519b89 »
2011-02-17 more tests
358 =================================================
fccc4e98 »
2011-02-06 the start of a README
359
949c3d33 »
2011-03-25 Edited README.md via GitHub
360 curl.js is much smaller than other AMD loaders. Less than 1/2 the size of the
ca44d3b5 »
2011-02-16 updated docs to reflect new feature: require() returns a Promise
361 others in the list above. It's able to achieve this via a Promises-based
949c3d33 »
2011-03-25 Edited README.md via GitHub
362 design. (Promises are another [CommonJS proposed standard](http://wiki.commonjs.org/wiki/Promises).)
fccc4e98 »
2011-02-06 the start of a README
363
ca44d3b5 »
2011-02-16 updated docs to reflect new feature: require() returns a Promise
364 curl.js communicates with it's plugins via Promises, rather than a simple
fccc4e98 »
2011-02-06 the start of a README
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
1d8f14b5 »
2011-05-18 pdated to latest version and removed all references to the old public…
369 curl.js will also return a promise from curl() calls. This allows you to
ca44d3b5 »
2011-02-16 updated docs to reflect new feature: require() returns a Promise
370 write code like this:
371
1d8f14b5 »
2011-05-18 pdated to latest version and removed all references to the old public…
372 curl(
c1ee8af9 »
2011-03-23 we can haz markdown!
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 );
ca44d3b5 »
2011-02-16 updated docs to reflect new feature: require() returns a Promise
385
4996694a »
2011-04-29 Edited README.md via GitHub
386 (When using `require` as a dependency, it does not return a promise.
387 This is so that 100% CommonJS compliance is assured inside modules.)
ca44d3b5 »
2011-02-16 updated docs to reflect new feature: require() returns a Promise
388
fccc4e98 »
2011-02-06 the start of a README
389 ----------------------------------------
390
6c0f0fee »
2011-03-13 bumped version to 0.2 and added some content about non-AMD files
391 Can curl.js work with non-AMD javascript files?
392 ===============================================
393
394 Yes, but why would you? Once you start using AMD, you'll never go back! :)
395
396 You may use non-AMD javascript files by specifying the js! plugin prefix
397 like this:
398
1d8f14b5 »
2011-05-18 pdated to latest version and removed all references to the old public…
399 curl(
c1ee8af9 »
2011-03-23 we can haz markdown!
400 [
d5d4eb3c »
2011-04-16 updated to latest features
401 'js!plainOldJsFile1.js!order',
402 'js!anotherPlainOldJsFile.js!order'
c1ee8af9 »
2011-03-23 we can haz markdown!
403 ]
404 ).then(
405 function () {
406 /* do something with your plain, boring javascript files */
407 },
408 function () {
409 /* do something if any fail to load */
410 }
411 );
412
d5d4eb3c »
2011-04-16 updated to latest features
413 The !order suffix instructs curl.js to wait for previous scripts to execute
4996694a »
2011-04-29 Edited README.md via GitHub
414 before executing the current script. All scripts download in parallel, though,
c1ee8af9 »
2011-03-23 we can haz markdown!
415 unless you specify jsPrefetch:false in the config. Be sure to have proper
416 cache headers set if you plan to use jsPrefetch:true or scripts will get
4996694a »
2011-04-29 Edited README.md via GitHub
417 downloaded twice in browsers that don't support async=false (only Firefox 4
418 supports it so far).
6c0f0fee »
2011-03-13 bumped version to 0.2 and added some content about non-AMD files
419
420 ----------------------------------------
421
39b5e548 »
2011-03-14 updated README to reflect latest features
422 Can curl.js load non-javascript files?
423 =======================
424
425 Yes, curl.js follows the CommonJS Loader Plugin specification, so you can use
426 any compatible plugin. The following plugins are included:
427
428 js! -- loads non-AMD javascript files
34a83a22 »
2011-03-23 more tweaks
429
39b5e548 »
2011-03-14 updated README to reflect latest features
430 text! -- loads text files
431
432 You can also load css files by using the AMD plugin at the following repo:
851d03e6 »
2011-03-23 getting the hang of this markdown stuff
433 <https://github.com/unscriptable/cssx/blob/master/src/cssx/css.js>
39b5e548 »
2011-03-14 updated README to reflect latest features
434
4996694a »
2011-04-29 Edited README.md via GitHub
435 The following plugins are in progress:
39b5e548 »
2011-03-14 updated README to reflect latest features
436
437 i18n! -- loads text strings and other locale-specific constants
34a83a22 »
2011-03-23 more tweaks
438
39b5e548 »
2011-03-14 updated README to reflect latest features
439 cssx! -- loads and automatically shims css files for older browsers
440
441 ----------------------------------------
442
ee4b740e »
2011-02-06 moar text in the README
443 How are modules loaded?
c1519b89 »
2011-02-17 more tests
444 =======================
ee4b740e »
2011-02-06 moar text in the README
445
949c3d33 »
2011-03-25 Edited README.md via GitHub
446 curl.js uses `<script>` element injection rather than XHR. This allows curl.js to
447 load cross-domain scripts as well as local scripts.
448
d5d4eb3c »
2011-04-16 updated to latest features
449 To find scripts and other resources, curl uses module names. A module name
450 looks just like a file path, but typically without the file extension. If a
451 module requires a plugin in order to load correctly, it will have a prefix
452 delimited by a "!" and will also often have a file extension when a plugin
453 may load different types of files.
949c3d33 »
2011-03-25 Edited README.md via GitHub
454
455 Some examples of module names:
456
457 * dojo/store/JsonRest
458 * my/lib/string/format
459 * js!my/lib/js/plain-old-js.js
460 * css!my/styles/reset.css
461 * http://some-cdn/uber/module
462
463 By default, curl.js will look in the same folder as the current document's location.
464 For instance, if your web page is located at `http://my-domain/apps/myApp.html`,
465 curl.js will look for the JsonRest module at `http://my-domain/apps/dojo/store/JsonRest.js`.
466
467 You can tell curl.js to find modules in other locations by specifying a baseUrl or
468 individual paths for each of your libraries. For example, if you specify a baseUrl of
469 `/resources/` and the following paths:
470
471 paths: {
472 dojo: "third-party/dojo",
473 css: "third-party/cssx/css",
474 my: "my-cool-app-v1.3",
475 "my/lib/js": "old-js-libs"
476 }
477
478 Then the modules listed above will be sought in the following locations:
479
480 * /resources/third-party/dojo/store/JsonRest.js
481 * /resources/my-cool-app-v1.3/lib/string/format.js
482 * /resources/old-js-libs/plain-old-js.js
483 * /resources/my-cool-app-v1.3/styles/reset.css
484 * http://some-cdn/uber/module.js
485
d5d4eb3c »
2011-04-16 updated to latest features
486 Note: you will need to create a path to curl's plugins and other modules if the
487 curl folder isn't directly under the same folder as your web page. curl.js uses
488 the same mechanism to find its own modules.
949c3d33 »
2011-03-25 Edited README.md via GitHub
489
490 TODO: explain the pluginPath configuration parameter.
ee4b740e »
2011-02-06 moar text in the README
491
492 ----------------------------------------
493
494 What are AMD plugins?
c1519b89 »
2011-02-17 more tests
495 =====================
ee4b740e »
2011-02-06 moar text in the README
496
497 AMD supports the notion of plugins. Plugins are AMD modules that can be used to
498 load javascript modules -- or other types of resources. curl comes with several
499 plugins already, including a text plugin (for templates or other text
500 resources), a css plugin, a sync plugin (for loading modules synchronously),
501 and a debug plugin (for collecting and logging details of the inner workings of
502 curl).
503
504 Plugins are designated by a prefix on the name of the module or resource to be
505 loaded. They are delineated by a ! symbol. The following example shows the use
506 of some plugins:
507
c1ee8af9 »
2011-03-23 we can haz markdown!
508 define(
509 [
510 'text!myTemplate.html',
511 'css!myCssFile'
512 ],
513 function (templateString, cssLinkNode) {
514 // do something with the template and css here
515 }
516 );
ee4b740e »
2011-02-06 moar text in the README
517
518 Since plugins are just AMD modules, they would typically be referenced using
519 their fully-pathed names. curl provides a pluginPath configuration option that
520 allows you to specify the folder where [most of] your plugins reside so you
521 don't have to specify their full paths. This also helps with compatibility
522 with other AMD loaders that assume that certain plugins are bundled and
523 internally mapped.
524
525 If one or more of your plugins does not reside in the folder specified by the
526 pluginPath config option, you can use its full path or you can specify a path
527 for it in curl's paths config object.
528
c1ee8af9 »
2011-03-23 we can haz markdown!
529 // example of a fully-pathed plugin under the cssx folder
530 define(['cssx/cssx!myCssFile'], function (cssxDef) {
531 // do some awesome css stuff here
532 });
ee4b740e »
2011-02-06 moar text in the README
533
534 (cssx is the Cujo Style Sheet eXtender AMD plugin that repairs browser css
535 deficiencies on-the-fly.)
536
537 Plugins can also have configuration options. Global options can be specified
538 on curl's configuration object. Options can also be supplied to plugins via
539 suffixes. Suffixes are also delineated by the ! symbol. Here's an example of
540 a plugin using options:
541
c1ee8af9 »
2011-03-23 we can haz markdown!
542 // don't try to repair IE6-8 opacity issues in my css file
543 define(['cssx/cssx!myCssFile!ignore:opacity'], function (cssxDef) {
544 // do some awesome css stuff here
545 });
ee4b740e »
2011-02-06 moar text in the README
546
547 ----------------------------------------
548
fccc4e98 »
2011-02-06 the start of a README
549 How do I use curl.js?
c1519b89 »
2011-02-17 more tests
550 =====================
ee4b740e »
2011-02-06 moar text in the README
551
949c3d33 »
2011-03-25 Edited README.md via GitHub
552 1. Optional: Learn about AMD-formatted javascript modules if you don't already know how.
553 2. Clone or download curl to your local machine or server.
554 3. Figure out the baseUrl and paths configuration that makes sense for your project.
555 4. Check out the "API at a glance" section above to figure out which loading methodology you want to use.
556 5. Study the "Very Simple Example" and some of the test files.
557 6. Try it on your own files.
39b5e548 »
2011-03-14 updated README to reflect latest features
558
ee4b740e »
2011-02-06 moar text in the README
559 ----------------------------------------
560
e14209e2 »
2011-02-17 clarified README
561 Too Many Modules!
c1519b89 »
2011-02-17 more tests
562 =================
e14209e2 »
2011-02-17 clarified README
563
ee4b740e »
2011-02-06 moar text in the README
564 I have dozens (or hundreds) of modules. Even with parallel loading, the
20f02044 »
2011-02-07 minor clarififcations to README
565 performance sucks! What can I do about that?
ee4b740e »
2011-02-06 moar text in the README
566
567 True! No parallel loader can lessen the latency required to create an HTTP
568 connection. If you have dozens or hundreds of files to download, it's going to
569 take time to initiate each of the connections.
570
571 However, there are tools to that are designed to fix this problem! There are
572 builders and compilers. dojo users are probably already familiar with dojo's
573 build tool and optimizer. RequireJS comes with a build tool and Google's
574 Closure compiler.
575
576 The build tool is used to concatenate several modules (and/or resources)
577 into just a few files. It does this by following the dependency chain
578 specified in the define() and require() calls. You can specify which top-level
579 modules or resources are in each file and the build tool finds the rest.
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
949c3d33 »
2011-03-25 Edited README.md via GitHub
586 Assembler. cram will be ready by mid 2011, so use another build tool or a
ee4b740e »
2011-02-06 moar text in the README
587 custom shell script in the mean time.
20f02044 »
2011-02-07 minor clarififcations to README
588
589 ----------------------------------------
0e0a920f »
2011-03-14 added kudos for Bryan and James
590
4a92fee2 »
2011-04-19 notes about Packages 1.1 support and updates to What's New and size
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
1d8f14b5 »
2011-05-18 pdated to latest version and removed all references to the old public…
619 curl(['my-package'], callback);
4a92fee2 »
2011-04-19 notes about Packages 1.1 support and updates to What's New and size
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
1d8f14b5 »
2011-05-18 pdated to latest version and removed all references to the old public…
627 curl(['my-package/other-module'], callback);
4a92fee2 »
2011-04-19 notes about Packages 1.1 support and updates to What's New and size
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
f778b1fd »
2011-03-25 Edited README.md via GitHub
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
9cdc2280 »
2011-05-27 Trivial README edits. Fixed Backdraft links and added links to @twitt…
652 Many thanks to Bryan Forbes ([@bryanforbes](http://www.twitter.com/bryanforbes)) for helping to clean up my code and
b46b3532 »
2011-03-23 changed the name of (and fixed) the dependency-chaining API to .next(…
653 for making cujo's domReady much more robust.
851d03e6 »
2011-03-23 getting the hang of this markdown stuff
654 More about Bryan: <http://www.reigndropsfall.net/>
12c25166 »
2011-03-15 some more credit where credit is due
655
9cdc2280 »
2011-05-27 Trivial README edits. Fixed Backdraft links and added links to @twitt…
656 Kudos also to James Burke ([@jrburke](http://www.twitter.com/jrburke)) who instigated the CommonJS AMD proposal
b46b3532 »
2011-03-23 changed the name of (and fixed) the dependency-chaining API to .next(…
657 and paved the way to create AMD-style loaders.
851d03e6 »
2011-03-23 getting the hang of this markdown stuff
658 More about James: <http://tagneto.blogspot.com/>
c1ee8af9 »
2011-03-23 we can haz markdown!
659
9cdc2280 »
2011-05-27 Trivial README edits. Fixed Backdraft links and added links to @twitt…
660 Shout out to Kris Zyp ([@kriszyp](http://www.twitter.com/kriszyp)) for excellent ideas and feedback and to Kyle
661 Simpson ([@getify](http://www.twitter.com/getify)) who is inarguably the godfather of javascript loading.
Something went wrong with that request. Please try again.