assetly v0.1.2
node-assetly
Utilities for working with assets, especially assets' URIs (right now, this is all it does, heh).
If you want an easier way to set your assets' URIs, being able to change
them in a single place, assetly
may come in handy. It helps creating
builder functions for generating URIs. Like this:
var assets;
assets = assetly('//cdn.example.net')
.provides('js', {v : 1})
.provides('css')
.provides('img');
assets.img.provides('brand');
assets.express(app);
Then in your jade templates you could use:
html
head
title= Example
script(src=assets.js('main.js'))
link(type='text/css', rel='stylesheet', href=assets.css('base.css'))
body
img(src=assets.img.brand('navbar.png'), alt='Example')
Giving you...
<html>
<head>
<title>Example</title>
<script src="//cdn.example.com/js/main.js"></script>
<link type="text/css" rel="stylesheet" href="//cdn.example.com/css/base.css" />
</head>
<body>
<img src="//cdn.example.com/img/b/medium.png" alt="Example" />
</body>
</html>
Should you ever need to change your assets folders, all you have to do is
change your assetly
setup.
Installation
From NPM.
npm install assetly
Usage
Require it.
var assetly = require('assetly');
Creating a builder is very straight forward. A simple builder would look like this:
var assets = assetly('//cdn.example.com');
assets('main.js'); // '//cdn.example.com/main.js'
assets('css/base.css'); // '//cdn.example.com/css/base.css'
You can see more complex examples in under "Sub-builders", read on.
Sub-builders
Usually you'll want to organize your assets in sub-directories or some
file structure. To help you handle this, assetly
supports sub-builders.
They append to their parent's path, going deeper into your folder
structure.
But it is NOT required that a sub-builder advances to a deeper folder in
your file structure. If you pass null
as your sub-builder base path, it
will stay in the same folder as its parent.
Note that there's a difference between setting null
and undefined
as
your sub-buider's base path: the former will make it use the same path as
its parent, while the later makes the new builder use a folder with the
same name as the builder.
var assets = assetly('//cdn.example.com');
assets
.provides('scripts', null) // stays in the same folder
.provides('styles', 'css') // advances to the 'css' folder
.provides('images'); // advances to the 'images' folder
assets.scripts('main.min.js'); // '//cdn.example.com/main.min.js'
assets.styles('base.min.css'); // '//cdn.example.com/css/base.min.css'
assets.images('foo.jpg'); // '//cdn.example.com/img/foo.jpg'
You can use sub-builders to set a multi-root structure by starting with a
call to assetly()
with no args.
assets = assetly();
assets
.provides('scripts', '//s.example.com')
.provides('images', '//img.example.com');
assets.scripts('base.js'); // '//s.example.com/base.js'
assets.images('logo.png'); // '//img.example.com/logo.png'
Builders can be nested as needed:
var assets = assetly('//example.com');
assets.provides('sub');
assets.sub.provides('subsub');
assets.sub.subsub('subsubsub.txt'); // '//example.com/sub/subsub/subsubsub.txt'
Querystrings
assetly
allows you to set query string data in your builders. This way
you don't need to set it to every URI and, when a query param changes, you
can update your code very quickly.
var assets = assetly('//cdn.example.com', {v : 1, s : 'm'});
assets('foo.jpg'); // '//cdn.example.com/foo.jpg?v=1&s=m'
// Query data can be updated on a case by case basis.
assets('bar.jpg', {v : 2}); // '//cdn.example.com/bar.jpg?v=2&s=m'
// If you need to unset a previously defined query param, set it to
// undefined.
assets('baz.jpg', {s : undefined}); // '//cdn.example.com/baz.jpg?v=1'
Note that query string data defined in the root builder, will be inheritted by all sub-builders.
var assets = assetly('//cdn.example.com', {v : 1});
// Inherits {v : 1} from assets.
assets.provides('js');
assets.js('main.js'); // '//cdn.example.com/js/main.js?v=1'
// Inherits 'v' from parent and sets new data
assets.provides('css', {min : true});
assets.css('base.css'); // '//cdn.example.com/css/base.css?v=1&min=true'
// Updates 'v'
assets.provides('img', {v : 3});
assets(img('logo.png')); // '//cdn.example.com/img/logo.png?v=3'
express.js
If you are working with express, there's a helper method for making your root builder available to your application and in your templates.
var assets = assetly('//cdn.example.com');
assets.express(app);
app.assets === assets; // true
app.locals.assets === assets; // true
Now your builder is available in your templates thanks to the locals
object:
img(src=assets('logo.png'))
If you think 'assets' is not a good property, you can change it with the
propertyName
option of #express()
:
var assets = assetly('//cdn.example.com');
assets.express(app, {propertyName : 'static'});
app.static === assets; // true
app.locals.static === assets; // true
And in your templates:
img(src=static('logo.png'))
Testing
Testing should be as simple as running:
npm test
Contributing
All contributions are welcome. If you find any bugs or grammar mistakes, please, open an issue. Any kind of help to improve this code or documentation is greatly appreciated.
Feel free to submit pull requests too, for both code and grammar. I promess I'll check it as quick as possible (usually in a few days). When submitting a patch, please, add your name + contact to the authors section below.
Authors
Created by Mathias Kretschek (mkretschek).