Weave your wefts betwixt the warps of loom generators and scaffolds.
Loom makes it easy to share best-practices and common patterns for app development.
- build a set of generators for public consumption based on some framework or library (like ember, angular, backbone, etc.)
- consume those sets of generators
- override those generators
- build your own generators for your specific app
Using generator packages from npm is easy:
npm install loom-ember --save
npm install loom-ember-qunit --save
generate controller user name:string age:number
Then refer to the documentation for the generators you've installed.
You must install with --save
or add the module to your package.json
instead (that's how loom knows how to use them).
If two generator sets respond to the same commands, they will both be run, allowing authors and consumers to compose them.
In addition to generator sets, full project scaffolds are a simple
command away when an author publishes a project to npm with a name
matching originate-*
.
For example:
npm install -g loom
originate ember my-new-app
Read more about originate.
Also, see the full generator API below
While using generators others have created for you is great, its awesome to have a simple way to make generators for our own apps. Even if you're using a set of generators from npm, defining your own generators will override them.
npm install loom -g
generate --init
Initializing loom simply creates some directories in your project. After
that, all you need is a template in ./loom/templates/
:
Lets say we have a lot of "meal" objects in our app, lets make a template for what one of these objects looks like:
loom/templates/app/meal.js.hbs
function {{objectName}}() {
this.food = '{{params.food}}';
this.venue = '{{params.venue}}';
}
And then you can generate files based on the template:
generate app/meal.js lunch food:taco venue:cart
This will create a file at app/lunch.js
that looks like:
function lunch() {
this.food = 'taco';
this.venue = 'cart';
}
Loom, by default, will save files to your app in the same relative location they were found in your templates directory.
We can define a generator to make everything a little nicer. First we'll
create a present
method that determines what data goes to the
template. Then we'll tell it where to find the template so we can
simplify the generator command.
loom/generators/meal.js
exports.present = function(next, env) {
var locals = env.params;
var name = env.args[0];
locals.constructorName = name.charAt(0).toUpperCase() + name.slice(1);
return locals;
};
exports.template = 'app/meal.js.hbs';
Now our template is simpler, no more {{params.food}}
and it
capitalizes our constructor like a proper lady or gent.
loom/templates/meal.js.hbs
function {{constructorName}}() {
this.food = '{{food}}';
this.venue = '{{venue}}';
}
And finally our command is simpler, it now just matches a generator
named meal
instead of a template found at app/meal.js
.
generate meal lunch food:taco venue:cart
The default generator uses handlebars, but we can swap it out for ejs by creating a very simple "engine":
loom/engines/ejs.js
var _ = require('underscore');
// module.exports = _.template
// that works, but for clarity:
module.exports = function(src, locals, callback) {
callback(_.template(src, locals));
};
Rename your template to meal.js.ejs
and edit it:
function <%= constructorName %>() {
this.food = '<%= food %>';
this.venue = '<%= venue %>';
}
Update your generator to point to the proper template:
exports.template = 'app/meal.js.ejs';
Loom looks at the file extension of the template (in this case ejs
)
and then tries to find a template engine named ejs.js
.
Now generate your newly configured template:
generate meal lunch food:taco venue:cart
Its very common for a generator to create several files, like unit tests and scaffoling. Lets add a unit test template to our meal generator.
loom/templates/test/unit/meal.spec.js.ejs
describe('<%= constructorName %>', function() {
it('sets food to "<%= food %>"', function() {
var meal = new <%= constructorName %>();
expect(meal.food).to.equal('<%= food %>');
});
});
And add the template path to your generator, note the rename from
exports.template
to export.templates
.
exports.templates = [
'app/meal.js.ejs',
'test/unit/meal.spec.js.ejs'
];
Both templates will get the same data from generator.present
and the
files will be saved to the same relative path in your app as they are
defined in your templates directory.
If you define loom/generators/default.js
, loom will use it when a
specific generator is not found.
Name your module loom-<name>
(like
loom-ember
), place generators, templates, and engines in
./loom
, and then publish. That's it. People can simply npm install loom-<name> --save
and start using them.
To add support for your favorite templating engine you can either add a
file to loom/engines
or publish a module to npm named
loom-engine-<ext>
. Loom will attempt to require the engine if it
doesn't find it in your project.
Loom has a generic generator that can be overridden to meet your specific use case. Generators can export a few methods that loom will use.
Your generator can implement as many methods as you need, loom will
merge in the generic_generator
methods that you don't provide.
Here's a generator that does nothing:
loom/generators/noop.js
exports.before = function(){};
exports.present = function(){};
exports.savePath = function(){};
exports.write = function(){};
exports.render = function(){};
exports.template = '';
// exports.template = function(){};
// exports.templates = [];
// exports.templates = function(){};
Below is documentation on generator API, also, check out the generic generator.
All methods share the first two arguments: next
, and env
.
next
- all methods are asynchronous, so when you're done doing what you need to do, callnext(val)
.env
- the loom environment, it contains all sorts of information about thegenerate
command the user ran.
Executes before anything else happens. Useful if you need to set or
change some things on env
before it moves through the other methods of
your generator.
function(next, env)
- next (Function) - the callback.
- env (Object) - the loom environment object.
You're probably going to want env.args
and env.params
.
function(next, env)
- next (Function) - the callback.
- env (Object) - the loom environment object.
Lets make a generator that logs the arguments to explore how this works.
loom/generators/user.js
exports.present = function(next, env) {
console.log(env);
};
The following are commands followed by what is logged for the arguments:
generate model user name:string age:number
{ args: ['user'], params: { name: 'string', age: 'number' } }
generate model foo bar baz qux:1 quux:2
{ args: ['foo', 'bar', 'baz' ]
params: { qux: '1', quux: '2' } }
As you can see, the space separated values become the args
and the
key:value pairs are wrapped up into the params
argument.
Determines which template to render.
exports.template
can simply be a string, or a function if you need to
compute it.
Paths are relative to the ./loom/templates
directory.
To use a template found at
loom/templates/spec/models/model.spec.js.hbs
:
exports.template = 'spec/models/model.spec.js.hbs';
exports.template = function(next) {
// some computation
next('spec/models/model.spec.js.hbs');
};
Unless you override generator.write
the generated file will be saved
in the mirrored location in loom/templates
, so the example above will
be saved to spec/models/<name>.spec.js
.
Same as template
but is an array of template paths that take
precendence over template
. Each template will receive the same locals
returned from present
. Can also be a function that calls back an array.
exports.templates = [
'app/models/model.js.ejs',
'spec/models/model.spec.js.ejs'
];
exports.templates = function(next) {
next([
'app/models/model.js.ejs',
'spec/models/model.spec.js.ejs'
]);
};
Determines the path in which to save a template.
function(next, env, template)
- next (Function) - callback with the savePath you want
- env (Object) - the loom environment object
- template (String) - the path of the template being rendered
Writes a rendered template to the file system, its unlikely you'll want to override this.
function(next, env, savePath, src)
Determines how to render the template, its unlinkely you'll want to override this.
function(next, env, engine, templatePath, locals)
- conflict resolution when two generators want to save to the same path
- --force option to overwrite files (better for scripting so you don't get the prompt)
MIT Style license
(c) 2013 Ryan Florence