1 |
|
2 | <img src="https://s3.amazonaws.com/temp.techpines.com/asset-rack-white.png">
|
3 |
|
4 |
|
5 | # API Reference
|
6 |
|
7 | ## Install
|
8 |
|
9 | ```bash
|
10 | npm install asset-rack
|
11 | ```
|
12 |
|
13 | ## Asset
|
14 |
|
15 | This is the base class from which all assets derive. It can represent both a single asset or a collection of assets.
|
16 |
|
17 | ```js
|
18 | asset = new Asset({
|
19 | url: '/fun.txt',
|
20 | contents: 'I am having fun!'
|
21 | })
|
22 | ```
|
23 |
|
24 | ### Use with Express
|
25 |
|
26 | Generally, you should wrap your assets in a rack, but for quick and dirty smaller projects you can just use the asset directly.
|
27 |
|
28 | ```
|
29 | app.use(asset);
|
30 | ```
|
31 |
|
32 | ### Options
|
33 | * `url`: The url where our resource will be served.
|
34 | * `contents`: The actual contents to be deliverd by the url.
|
35 | * `headers`: Any specific headers you want associated with this asset.
|
36 | * `mimetype`: The content type for the asset.
|
37 | * `hash`: (defaults to undefined) Serves both hashed and unhashed urls. If set to `true` then it only serves the hashed version, and if false then it only serves the unhashed version.
|
38 | * `allowNoHashCache`: By default unhashed urls will not be cached. To allow them to be hashed, set this option to `true`.
|
39 | * `maxAge`: How long to cache the resource, defaults to 1 year for hashed urls, and no cache for unhashed urls.
|
40 | * `specificUrl`: The hashed version of the url.
|
41 | * `assets`: If the asset is actually a collection of assets, then this is where all of it's assets are.
|
42 |
|
43 | ### Methods
|
44 | * `tag()`: Returns the tag that should be used in HTML. (js and css assets only)
|
45 | * `respond(req,res)`: Given an express request and response object, this will respond with the contents and headers for the asset.
|
46 |
|
47 | ### Events
|
48 | * `complete`: Triggered once the asset is fully initialized with contents or assets, and has headers, hashed url etc.
|
49 | * `created`: Emitted when just the contents or assets have been created, before headers and hashing.
|
50 | * `error`: Emitted if there is an error with the asset.
|
51 |
|
52 | ### Extending the Asset Class
|
53 |
|
54 | It is easy to extend the base Asset class. The procedure for javascript is similar to that of Backbone.js. You must override the create method for your asset.
|
55 |
|
56 | ```js
|
57 | MyCoolAsset = rack.Asset.extend({
|
58 | create: function(options) {
|
59 | this.contents = 'hey there'
|
60 | this.emit 'created'
|
61 | }
|
62 | })
|
63 | ```
|
64 |
|
65 | In coffescript it is a little simpler:
|
66 |
|
67 | ```coffee
|
68 | class MyCoolAsset extends rack.Asset
|
69 | create: (options) ->
|
70 | @contents = 'yea!'
|
71 | @emit 'created'
|
72 | ```
|
73 |
|
74 | Whenever you finish creating your contents you emit a __created__ event.
|
75 |
|
76 | The options object passed to create is the same options object that gets passed to the constructor of new objects.
|
77 |
|
78 | ```coffee
|
79 | asset = new MyCoolAsset(options)
|
80 | ```
|
81 |
|
82 | You can also create create a collection of assets by extending the `Asset` class, but instead of setting the contents, you would set an array of assets.
|
83 |
|
84 | ```js
|
85 | LotsOfAssets = rack.Asset.extend({
|
86 | create: function(options) {
|
87 | this.assets = []
|
88 |
|
89 | // add assets to the collection
|
90 |
|
91 | this.emit('created')
|
92 | }
|
93 | })
|
94 | ```
|
95 |
|
96 | This is pretty self-explanatory, the only caveat is that you need to wait for the assets that you create to `complete` or else you will probably run into some strange behavior.
|
97 |
|
98 | ## Rack
|
99 |
|
100 | Manage your assets more easily with a rack.
|
101 |
|
102 | ```js
|
103 | new rack.Rack(assets)
|
104 | ```
|
105 | #### Options
|
106 |
|
107 | * `assets`: A collection of assets.
|
108 |
|
109 | #### Methods
|
110 | * `tag(url)`: Given a url, returns the tag that should be used in HTML.
|
111 | * `url(url)`: Get the hashed url from the unhashed url.
|
112 | * `deploy(options, callback)`: Deploy to the cloud see below.
|
113 |
|
114 | #### Events
|
115 |
|
116 | * `complete`: Emitted after all assets have been created.
|
117 | * `error`: Emitted for any errors.
|
118 |
|
119 | ### With Express
|
120 |
|
121 | ```javascript
|
122 | app.use(assets);
|
123 | ```
|
124 | __Important__: You have to call `app.use(assets)` before `app.use(app.router)` or else the `assets` markup functions will not be available in your templates. The assets middleware needs to come first.
|
125 |
|
126 | ### Deploying
|
127 |
|
128 | #### Amazon S3
|
129 |
|
130 | ```js
|
131 | assets.deploy({
|
132 | provider: 'amazon',
|
133 | container: 'some-bucket',
|
134 | accessKey: 'aws-access-key',
|
135 | secretKey: 'aws-secret-key',
|
136 | }, function(error) {})
|
137 | ```
|
138 |
|
139 | #### Rackspace Cloud Files
|
140 | ```js
|
141 | assets.deploy(
|
142 | provider: 'rackspace',
|
143 | container: 'some-container',
|
144 | username: 'rackspace-username',
|
145 | apiKey: 'rackspace-api-key',
|
146 | }, function(error) {})
|
147 | ```
|
148 |
|
149 | #### Azure Storage
|
150 | ```js
|
151 | assets.deploy(
|
152 | provider: 'azure',
|
153 | container: 'some-container',
|
154 | storageAccount: 'test-storage-account',
|
155 | storageAccessKey: 'test-storage-access-key'
|
156 | }, function(error) {})
|
157 | ```
|
158 |
|
159 | ## Javascript/Coffeescript
|
160 |
|
161 | ### BrowserifyAsset (js/coffeescript)
|
162 |
|
163 | Browserify is an awesome node project that converts node-style requires
|
164 | to requirejs for the frontend. For more details, check it out,
|
165 | [here](https://github.com/substack/node-browserify).
|
166 |
|
167 | ```javascript
|
168 | new BrowserifyAsset({
|
169 | url: '/app.js',
|
170 | filename: __dirname + '/client/app.js',
|
171 | compress: true
|
172 | });
|
173 | ```
|
174 |
|
175 | #### Options
|
176 |
|
177 | * `url`: The url that should retrieve this resource.
|
178 | * `filename`: A filename or list of filenames to be executed by the browser.
|
179 | * `require`: A filename or list of filenames to require, should not be necessary
|
180 | as the `filename` argument should pull in any requires you need.
|
181 | * `debug` (defaults to false): enables the browserify debug option.
|
182 | * `compress` (defaults to false): whether to run the javascript through a minifier.
|
183 | * `extensionHandlers` (defaults to []): an array of custom extensions and associated handler function. eg: `[{ ext: 'handlebars', handler: handlebarsCompilerFunction }]`
|
184 |
|
185 | ### SnocketsAsset (js/coffeescript)
|
186 |
|
187 | Snockets is a JavaScript/CoffeeScript concatenation tool for Node.js inspired by Sprockets. Used by connect-assets to create a Rails 3.1-style asset pipeline. For more details, check it out,
|
188 | [here](https://github.com/TrevorBurnham/snockets).
|
189 |
|
190 | ```javascript
|
191 | new SnocketsAsset({
|
192 | url: '/app.js',
|
193 | filename: __dirname + '/client/app.js',
|
194 | compress: true
|
195 | });
|
196 | ```
|
197 |
|
198 | #### Options
|
199 |
|
200 | * `url`: The url that should retrieve this resource.
|
201 | * `filename`: A filename or list of filenames to be executed by the browser.
|
202 | * `compress` (defaults to false): whether to run the javascript through a minifier.
|
203 | * `extensionHandlers` (defaults to []): an array of custom extensions and associated handler function. eg: `[{ ext: 'handlebars', handler: handlebarsCompilerFunction }]`
|
204 | * `debug` (defaults to false): output scripts via eval with trailing //@ sourceURL
|
205 |
|
206 |
|
207 | ## Stylesheets
|
208 |
|
209 | ### LessAsset
|
210 |
|
211 | The less asset basically compiles up and serves your less files as css. You
|
212 | can read more about less [here](https://github.com/cloudhead/less.js).
|
213 |
|
214 | ```javascript
|
215 | new LessAsset({
|
216 | url: '/style.css',
|
217 | filename: __dirname + '/style/app.less'
|
218 | });
|
219 | ```
|
220 |
|
221 | #### Options
|
222 |
|
223 | * `url`: The url that should retrieve this resource.
|
224 | * `filename`: Filename of the less file you want to serve.
|
225 | * `compress` (defaults to false): Whether to minify the css.
|
226 | * `paths`: List of paths to search for `@import` directives.
|
227 |
|
228 | ### StylusAsset
|
229 |
|
230 | The stylus asset serves up your stylus assets.
|
231 |
|
232 | ```javascript
|
233 | new LessAsset({
|
234 | url: '/style.css',
|
235 | filename: __dirname + '/style/fun.styl'
|
236 | });
|
237 | ```
|
238 |
|
239 | #### Options
|
240 |
|
241 | * `url`: The url that should retrieve this resource.
|
242 | * `filename`: Filename of the less file you want to serve.
|
243 | * `compress` (defaults to false, or true in production mode): Whether to minify the css.
|
244 | * `config`: A function that allows custom configuration of the stylus object:
|
245 | ```coffee
|
246 | new StylusAsset
|
247 | url: '/style.css'
|
248 | filename: __dirname + '/style/fun.styl'
|
249 | config: ->
|
250 | @use bootstrap()
|
251 | @define 'setting', 90
|
252 | ```
|
253 |
|
254 | And javascript:
|
255 | ```js
|
256 | new StylusAsset({
|
257 | url: '/style.css',
|
258 | filename: __dirname + '/style/fun.styl',
|
259 | config: function (stylus) {
|
260 | stylus // using "this" here seems a little unnatural
|
261 | .use(bootstrap())
|
262 | .define('setting', 90);
|
263 | }
|
264 | });
|
265 | ```
|
266 |
|
267 |
|
268 | ## Templates
|
269 |
|
270 | ### JadeAsset
|
271 | This is an awesome asset. Ever wanted the simplicity of jade templates
|
272 | on the browser with lightning fast performance. Here you go.
|
273 |
|
274 | ```javascript
|
275 | new JadeAsset({
|
276 | url: '/templates.js',
|
277 | dirname: './templates'
|
278 | });
|
279 | ```
|
280 |
|
281 | So if your template directory looked like this:
|
282 |
|
283 | ```
|
284 | index.jade
|
285 | contact.jade
|
286 | user/
|
287 | profile.jade
|
288 | info.jade
|
289 | ```
|
290 |
|
291 | Then reference your templates on the client like this:
|
292 |
|
293 | ```javascript
|
294 | $('body').append(Templates['index']());
|
295 | $('body').append(Templates['user/profile']({username: 'brad', status: 'fun'}));
|
296 | $('body').append(Templates['user/info']());
|
297 | ```
|
298 | #### Options
|
299 |
|
300 | * `url`: The url that should retrieve this resource.
|
301 | * `dirname`: Directory where template files are located, will grab them recursively.
|
302 | * `separator` (defaults to '/'): The character that separates directories.
|
303 | * `compress` (defaults to false): Whether to minify the javascript or not.
|
304 | * `clientVariable` (defaults to 'Templates'): Client side template
|
305 | variable.
|
306 | * `beforeCompile`: A function that takes the jade template as a string and returns a new jade template string before it's compiled into javascript.
|
307 |
|
308 | ### AngularTemplatesAsset
|
309 |
|
310 | The angular templates asset packages all .html templates ready to be injected into the client side angularjs template cache.
|
311 | You can read more about angularjs [here](http://angularjs.org/).
|
312 |
|
313 | ```javascript
|
314 | new AngularTemplatesAsset({
|
315 | url: '/js/templates.js',
|
316 | dirname: __dirname + '/templates'
|
317 | });
|
318 | ```
|
319 |
|
320 | Then see the following example client js code which loads templates into the template cache, where `angularTemplates` is the function provided by AngularTemplatesAsset:
|
321 |
|
322 | ```javascript
|
323 | //replace this with your module initialization logic
|
324 | var myApp = angular.module("myApp", []);
|
325 |
|
326 | //use this line to add the templates to the cache
|
327 | myApp.run(['$templateCache', angularTemplates]);
|
328 | ```
|
329 |
|
330 | #### Options
|
331 |
|
332 | * `url`: The url that should retrieve this resource.
|
333 | * `dirname`: Directory where the .html templates are stored.
|
334 | * `compress` (defaults to false): Whether to unglify the js.
|
335 |
|
336 | ## Other
|
337 |
|
338 | ### StaticAssets
|
339 |
|
340 | ```js
|
341 | new StaticAssets({
|
342 | dirname: '/path/to/static'
|
343 | urlPrefix: '/static'
|
344 | })
|
345 | ```
|
346 |
|
347 | #### Options
|
348 | * `dirname`: The folder to recursively pull assets from.
|
349 | * `urlPrefix`: Base url where all assets will be available from.
|
350 |
|
351 | ### DynamicAssets
|
352 |
|
353 | ```js
|
354 | new DyanmicAssets({
|
355 | type: LessAsset
|
356 | urlPrefix: '/style'
|
357 | dirname: './style'
|
358 | })
|
359 | ```
|
360 |
|
361 | Then this would be the equivalent of going through every file in `/style` and doing this:
|
362 |
|
363 | ```js
|
364 | new LessAsset({
|
365 | filename: './style/some-file.less'
|
366 | url: '/style/some-file.css'
|
367 | })
|
368 | ```
|
369 |
|
370 | #### Options
|
371 | * `dirname`: The folder to recursively grab files from.
|
372 | * `type`: The type of Asset to use for each file.
|
373 | * `urlPrefix`: The url prefix to serve the assets from.
|
374 | * `options`: Other options to pass to the individual assets.
|