register handlebars helpers (#95)

* allow meta.js file and custom handlebars helpers

* document meta.js and handlebars helper registration

* final doc tweaks

Author: queckezz

README.md

@@ -68,7 +68,7 @@ vue init ~/fs/path/to-custom-template my-project
 
 - A template repo **must** have a `template` directory that holds the template files.
 
-- A template repo **may** have a `meta.json` file that provides metadata for the template. The `meta.json` can contain the following fields:
+- A template repo **may** have a metadata file for the template which can be either a `meta.js` or `meta.json` file. It can contain the following fields:
 
   - `prompts`: used to collect user options data;
 
@@ -78,7 +78,7 @@ vue init ~/fs/path/to-custom-template my-project
 
 #### prompts
 
-The `prompts` field in `meta.json` should be an object hash containing prompts for the user. For each entry, the key is the variable name and the value is an [Inquirer.js question object](https://github.com/SBoudrias/Inquirer.js/#question). Example:
+The `prompts` field in the metadata file should be an object hash containing prompts for the user. For each entry, the key is the variable name and the value is an [Inquirer.js question object](https://github.com/SBoudrias/Inquirer.js/#question). Example:
 
 ``` json
 {
@@ -129,9 +129,27 @@ Two commonly used Handlebars helpers, `if_eq` and `unless_eq` are pre-registered
 {{#if_eq lintConfig "airbnb"}};{{/if_eq}}
 ```
 
+##### Custom Handlebars Helpers
+
+You may want to register additional Handlebars helpers using the `helpers` property in the metadata file. The object key is the helper name:
+
+``` js
+module.exports = {
+  helpers: {
+    lowercase: str => str.toLowerCase()
+  }
+}
+```
+
+Upon registration, they can be used as follows:
+
+``` handlebars
+{{ lowercase name }}
+```
+
 #### File filters
 
-The `filters` field in `meta.json` should be an object hash containing file filtering rules. For each entry, the key is a [minimatch glob pattern](https://github.com/isaacs/minimatch) and the value is a JavaScript expression evaluated in the context of prompt answers data. Example:
+The `filters` field in the metadata file should be an object hash containing file filtering rules. For each entry, the key is a [minimatch glob pattern](https://github.com/isaacs/minimatch) and the value is a JavaScript expression evaluated in the context of prompt answers data. Example:
 
 ``` json
 {

lib/generate.js

@@ -7,7 +7,7 @@ var getOptions = require('./options')
 var ask = require('./ask')
 var filter = require('./filter')
 
-// register hendlebars helper
+// register handlebars helper
 Handlebars.registerHelper('if_eq', function (a, b, opts) {
   return a === b
     ? opts.fn(this)
@@ -36,6 +36,9 @@ module.exports = function generate (name, src, dest, done) {
     destDirName: name,
     noEscape: true
   })
+  opts.helpers && Object.keys(opts.helpers).map(function (key) {
+    Handlebars.registerHelper(key, opts.helpers[key])
+  })
   metalsmith
     .use(askQuestions(opts.prompts))
     .use(filterFiles(opts.filters))

lib/options.js

@@ -12,10 +12,7 @@ var validateName = require('validate-npm-package-name')
  */
 
 module.exports = function options (name, dir) {
-  var file = path.join(dir, 'meta.json')
-  var opts = exists(file)
-    ? metadata.sync(file)
-    : {}
+  var opts = getMetadata(dir)
 
   setDefault(opts, 'name', name)
   setValidateName(opts)
@@ -28,6 +25,31 @@ module.exports = function options (name, dir) {
   return opts
 }
 
+/**
+ * Gets the metadata from either a meta.json or meta.js file.
+ *
+ * @param  {String} dir
+ * @return {Object}
+ */
+
+function getMetadata (dir) {
+  var json = path.join(dir, 'meta.json')
+  var js = path.join(dir, 'meta.js')
+  var opts = {}
+
+  if (exists(json)) {
+    opts = metadata.sync(json)
+  } else if (exists(js)) {
+    var req = require(js)
+    if (req !== Object(req)) {
+      throw new Error('meta.js needs to expose an object')
+    }
+    opts = req
+  }
+
+  return opts
+}
+
 /**
  * Set the default value for a prompt question
  *

test/e2e/mock-metadata-repo-js/meta.js

@@ -0,0 +1,15 @@
+
+module.exports = {
+  prompts: {
+    description: {
+      type: 'string',
+      required: true,
+      message: 'Project description'
+    }
+  },
+  helpers: {
+    uppercase: function (str) {
+      return str.toUpperCase()
+    }
+  }
+}

test/e2e/mock-metadata-repo-js/template/readme.md

@@ -0,0 +1 @@
+{{ uppercase name}}

test/e2e/test.js

@@ -9,6 +9,7 @@ const inquirer = require('inquirer')
 const async = require('async')
 const extend = Object.assign || require('util')._extend
 const generate = require('../../lib/generate')
+const metadata = require('../../lib/options')
 
 const MOCK_TEMPLATE_REPO_PATH = './test/e2e/mock-template-repo'
 const MOCK_TEMPLATE_BUILD_PATH = path.resolve('./test/e2e/mock-template-build')
@@ -41,6 +42,31 @@ describe('vue-cli', () => {
     noEscape: true
   }
 
+  it('read metadata from json', done => {
+    const meta = metadata('test-pkg', MOCK_TEMPLATE_REPO_PATH)
+    expect(meta).to.be.an('object')
+    expect(meta.prompts).to.have.property('description')
+    done()
+  })
+
+  it('read metadata from js', done => {
+    const meta = metadata('test-pkg', __dirname + '/mock-metadata-repo-js')
+    expect(meta).to.be.an('object')
+    expect(meta.prompts).to.have.property('description')
+    done()
+  })
+
+  it('helpers', done => {
+    monkeyPatchInquirer(answers)
+    const buildPath = __dirname + '/mock-metadata-repo-js'
+    generate('test', buildPath, MOCK_TEMPLATE_BUILD_PATH, err => {
+      if (err) done(err)
+      const contents = fs.readFileSync(`${MOCK_TEMPLATE_BUILD_PATH}/readme.md`, 'utf-8')
+      expect(contents).to.equal(answers.name.toUpperCase())
+      done()
+    })
+  })
+
   it('template generation', done => {
     monkeyPatchInquirer(answers)
     generate('test', MOCK_TEMPLATE_REPO_PATH, MOCK_TEMPLATE_BUILD_PATH, err => {