2014-03-28

yeoman-generator's template() now accept a forth parameter being the _.templateSettings

We are talking about yeoman generators with custom _templateSettings rules.

Sometimes when you are using underscore.js or lodash templates you have to change how parameters and expressions will be interpolated.

You might want to do so because the syntax of your generated file does not fit the templateSettings defaults (example: you get a lodash/underscore template error like "SyntaxError: Unexpected token :") or you just want to use another syntax to interpolate vars or expressions.

How can you do that with yeoman?

Starting from 0.17.0-pre.1 prerelease version the yeoman-generator's template() accept a forth parameter being the _.templateSettings (see https://github.com/yeoman/generator/releases/tag/v0.17.0-pre.1).

Here you can find an example about how to use custom _.templateSettings rules in a custom yeoman generator created with generator-generator (see http://yeoman.io/generators.html).

Note well: this post won't talk about how to create a custom generator. You can find more information about this topic following the official yeoman guide. Anyway installing generator-generator is as simple as typing the following command:
$ npm install -g yo generator-generator
(after doing that you can have a coffee and/or brush your cat’s fur since it might requires a long time depending on your network or machine)

So let's see how it works!

app/index.js

The template method usage is similar to the older versions of yeoman-generator except a richer signature:
function template(source, destination, data, options)
where the fourth parameter is an object to be used as _.templateSettings. For example here it is a working example:
this.template('_buildout.cfg',
              'buildout.cfg',
               this,
    {
        evaluate: /\{\{([\s\S]+?)\}\}/g,
        interpolate: /\{\{=([\s\S]+?)\}\}/g,
        escape: /\{\{-([\s\S]+?)\}\}/g
    });

app/templates/_buildout.cfg

This is our _buildout.cfg template, you can populate values using the {{}} syntax. In this particular case we are building the download url of mongodb depending on the user input (mongodbVersion). For example:
[buildout]
...
# Do not remove this: <%= mongodbVersion %>
recipe = rod.recipe.mongodb
darwin-32bit-url = http://downloads.mongodb.org/...-{{=mongodbVersion}}.tgz
You might wonder why there is still a line with <%= mongodbVersion %>. It seems to be necessary because without this line this prerelease version of yeoman-generator will produce the unrendered output. See https://github.com/yeoman/generator/issues/517.

With this workaround all works fine, probably it won't be necessary in future versions.

Example usage


Results

The resulting buildout.cfg contents will be similar to the following lines, depending on the user input:
[buildout]
...
[mongodb]
...
# Do not remove this: <%= mongodbVersion %>
recipe = rod.recipe.mongodb
darwin-32bit-url = http://downloads.mongodb.org/osx/mongodb-osx-i386-2.4.9.tgz
The rendered file will be used to install and configure automatically the given version of mongodb.

Done

First of all: feedback, please!

And... I think to write a second part of this blog post talking about how this particular generator works under the hood (a yeoman based mongodb installer based internally on a widely used build system for creating, assembling, configuring and deploying applications). So if you are pretty curious stay tuned on @davidemoro for future write ups.

20140407: see http://davidemoro.blogspot.com/2014/04/yeoman-generator-mongodb-installer.html fur further information.

No comments:

Post a Comment