Merge pull request #959 from engelfrost/feature/handlebars-helpers

Feature/handlebars helpers

Author: bmuenzenmeyer

packages/development-edition-engine-handlebars/helpers/test.js

@@ -0,0 +1,5 @@
+module.exports = function(Handlebars) {
+  Handlebars.registerHelper('test', function() {
+    return 'This is a test helper';
+  });
+};

packages/development-edition-engine-handlebars/patternlab-config.json

@@ -85,5 +85,10 @@
       "excludedPatternStates": [],
       "excludedTags": []
     }
-  ]
+  ],
+  "engines": {
+    "handlebars": {
+      "extend": "helpers/*.js"
+    }
+  }
 }

packages/development-edition-engine-handlebars/source/_patterns/atoms/text/helper.hbs

@@ -0,0 +1 @@
+{{test}}

packages/engine-handlebars/README.md

@@ -1,6 +1,6 @@
 # The Handlebars PatternEngine for Pattern Lab / Node
 
-To install the Handlebars PatternEngine in your edition, `npm install @pattern-lab/engine-handlebars` should do the trick.
+To install the Handlebars PatternEngine in your edition, `npm install --save @pattern-lab/engine-handlebars` should do the trick.
 
 ## Supported features
 
@@ -11,3 +11,34 @@ To install the Handlebars PatternEngine in your edition, `npm install @pattern-l
 * [x] [Pattern States](http://patternlab.io/docs/pattern-states.html)
 * [ ] [Pattern Parameters](http://patternlab.io/docs/pattern-parameters.html) (Accomplished instead using [native Handlebars partial arguments](http://handlebarsjs.com/partials.html))
 * [ ] [Style Modifiers](http://patternlab.io/docs/pattern-stylemodifier.html) (Accomplished instead using [native Handlebars partial arguments](http://handlebarsjs.com/partials.html))
+
+## Helpers
+
+To add custom [helpers](http://handlebarsjs.com/#helpers) or otherwise interact with Handlebars directly, create a file named `patternlab-handlebars-config.js` in the root of your Pattern Lab project, or override the default location by specifying one or several glob patterns in the Pattern Lab config:
+
+```json
+  {
+    ...
+    "engines": {
+      "handlebars": {
+        "extend": [
+          "handlebars-helpers.js",
+          "helpers/**/*.js"
+        ]
+      }
+    }
+  }
+```
+
+Each file should export a function which takes Handlebars as an argument.
+
+```js
+module.exports = function(Handlebars) {
+  // Put helpers here
+
+  Handlebars.registerHelper('fullName', function(person) {
+    // Example: person = {firstName: "Alan", lastName: "Johnson"}
+    return person.firstName + " " + person.lastName;
+  });
+};
+```

packages/engine-handlebars/lib/engine_handlebars.js

@@ -25,21 +25,30 @@
 const fs = require('fs-extra');
 const path = require('path');
 const Handlebars = require('handlebars');
+const glob = require('glob');
 
 // regexes, stored here so they're only compiled once
 const findPartialsRE = /{{#?>\s*([\w-\/.]+)(?:.|\s+)*?}}/g;
 const findListItemsRE = /({{#( )?)(list(I|i)tems.)(one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve|thirteen|fourteen|fifteen|sixteen|seventeen|eighteen|nineteen|twenty)( )?}}/g;
 const findAtPartialBlockRE = /{{#?>\s*@partial-block\s*}}/g;
 
 function escapeAtPartialBlock(partialString) {
-  var partial = partialString.replace(
+  const partial = partialString.replace(
     findAtPartialBlockRE,
     '{{> @partial-block }}'
   );
   return partial;
 }
 
-var engine_handlebars = {
+function loadHelpers(helpers) {
+  helpers.forEach(globPattern => {
+    glob.sync(globPattern).forEach(filePath => {
+      require(path.join(process.cwd(), filePath))(Handlebars);
+    });
+  });
+}
+
+const engine_handlebars = {
   engine: Handlebars,
   engineName: 'handlebars',
   engineFileExtension: ['.hbs', '.handlebars'],
@@ -54,7 +63,7 @@ var engine_handlebars = {
       Handlebars.registerPartial(partials);
     }
 
-    var compiled = Handlebars.compile(escapeAtPartialBlock(pattern.template));
+    const compiled = Handlebars.compile(escapeAtPartialBlock(pattern.template));
 
     return Promise.resolve(compiled(data));
   },
@@ -68,7 +77,7 @@ var engine_handlebars = {
 
   // find and return any {{> template-name }} within pattern
   findPartials: function findPartials(pattern) {
-    var matches = pattern.template.match(findPartialsRE);
+    const matches = pattern.template.match(findPartialsRE);
     return matches;
   },
   findPartialsWithStyleModifiers: function() {
@@ -85,14 +94,14 @@ var engine_handlebars = {
     return [];
   },
   findListItems: function(pattern) {
-    var matches = pattern.template.match(findListItemsRE);
+    const matches = pattern.template.match(findListItemsRE);
     return matches;
   },
 
   // given a pattern, and a partial string, tease out the "pattern key" and
   // return it.
   findPartial: function(partialString) {
-    var partial = partialString.replace(findPartialsRE, '$1');
+    const partial = partialString.replace(findPartialsRE, '$1');
     return partial;
   },
 
@@ -122,6 +131,36 @@ var engine_handlebars = {
     this.spawnFile(config, '_00-head.hbs');
     this.spawnFile(config, '_01-foot.hbs');
   },
+
+  /**
+   * Accept a Pattern Lab config object from the core and use the settings to
+   * load helpers.
+   *
+   * @param {object} config - the global config object from core
+   */
+  usePatternLabConfig: function(config) {
+    let helpers;
+
+    try {
+      // Look for helpers in the config
+      helpers = config.engines.handlebars.extend;
+
+      if (typeof helpers === 'string') {
+        helpers = [helpers];
+      }
+    } catch (error) {
+      // Look for helpers in default location
+      const configPath = 'patternlab-handlebars-config.js';
+      if (fs.existsSync(path.join(process.cwd(), configPath))) {
+        helpers = [configPath];
+      }
+    }
+
+    // Load helpers if they were found
+    if (helpers) {
+      loadHelpers(helpers);
+    }
+  },
 };
 
 module.exports = engine_handlebars;

packages/engine-handlebars/package.json

@@ -5,7 +5,8 @@
   "main": "lib/engine_handlebars.js",
   "dependencies": {
     "fs-extra": "0.30.0",
-    "handlebars": "4.0.5"
+    "handlebars": "4.0.5",
+    "glob": "7.0.0"
   },
   "keywords": [
     "Pattern Lab",

packages/engine-nunjucks/README.md

@@ -17,16 +17,34 @@ Level of Support is more or less full. Partial calls and lineage hunting are sup
 
 ## Extending the Nunjucks instance
 
-To add custom filters or make customizations to the nunjucks instance, create a file named `patternlab-nunjucks-config.js` in the root of your Pattern Lab project. `patternlab-nunjucks-config.js` should export a function with the Nunjucks environment as parameter.
+To add custom filters or make customizations to the nunjucks instance, add the following to `patternlab-config.json`:
 
+```json
+  {
+    ...
+    "engines": {
+      "nunjucks": {
+        "extend": [
+          "nunjucks-extensions/*.js"
+        ]
+      }
+    }
+  }
 ```
+
+...or use the default file name: `patternlab-nunjucks-config.js` (in the root of your Pattern Lab project).
+
+Each file providing extensions should export a function with the Nunjucks environment as parameter.
+
+```js
 module.exports = function (env) {
   [YOUR CUSTOM CODE HERE]
 };
 ```
 
 Example: `patternlab-nunjucks-config.js` file that uses lodash and adds three custom filters.
-```
+
+```js
 var _shuffle = require('lodash/shuffle'),
   _take = require('lodash/take');
 

packages/engine-nunjucks/lib/engine_nunjucks.js

@@ -22,39 +22,10 @@
 
 const fs = require('fs-extra');
 const path = require('path');
-const plPath = process.cwd();
-const plConfig = require(path.join(plPath, 'patternlab-config.json'));
 const nunjucks = require('nunjucks');
 const partialRegistry = [];
 
-// Create Pattern Loader
-// Since Pattern Lab includes are not path based we need a custom loader for Nunjucks.
-function PatternLoader() {}
-
-PatternLoader.prototype.getSource = function(name) {
-  const fullPath = path.resolve(
-    plConfig.paths.source.patterns,
-    partialRegistry[name]
-  );
-  return {
-    src: fs.readFileSync(fullPath, 'utf-8'),
-    path: fullPath,
-    noCache: true,
-  };
-};
-
-const env = new nunjucks.Environment(new PatternLoader());
-
-// Load any user Defined configurations
-try {
-  const nunjucksConfig = require(path.join(
-    plPath,
-    'patternlab-nunjucks-config.js'
-  ));
-  if (typeof nunjucksConfig === 'function') {
-    nunjucksConfig(env);
-  }
-} catch (err) {}
+let env;
 
 // Nunjucks Engine
 const engine_nunjucks = {
@@ -153,6 +124,72 @@ const engine_nunjucks = {
     this.spawnFile(config, '_00-head.njk');
     this.spawnFile(config, '_01-foot.njk');
   },
+
+  /**
+   * Accept a Pattern Lab config object from the core and use the settings to
+   * load helpers.
+   *
+   * @param {object} config - the global config object from core
+   */
+  usePatternLabConfig: function(config) {
+    // Create Pattern Loader
+    // Since Pattern Lab includes are not path based we need a custom loader for Nunjucks.
+    function PatternLoader() {}
+
+    PatternLoader.prototype.getSource = function(name) {
+      const fullPath = path.resolve(
+        config.paths.source.patterns,
+        partialRegistry[name]
+      );
+      return {
+        src: fs.readFileSync(fullPath, 'utf-8'),
+        path: fullPath,
+        noCache: true,
+      };
+    };
+
+    env = new nunjucks.Environment(new PatternLoader());
+
+    let extensions;
+
+    try {
+      // Look for helpers in the config
+      extensions = config.engines.nunjucks.extend;
+
+      if (typeof extensions === 'string') {
+        extensions = [extensions];
+      }
+    } catch (error) {
+      // No defined path(s) found, look in default location
+
+      const configPath = 'patternlab-nunjucks-config.js';
+      if (fs.existsSync(path.join(process.cwd(), configPath))) {
+        extensions = [configPath];
+      }
+    }
+
+    if (extensions) {
+      extensions.forEach(extensionPath => {
+        // Load any user Defined configurations
+        const nunjucksConfigPath = path.join(process.cwd(), extensionPath);
+
+        try {
+          const nunjucksConfig = require(nunjucksConfigPath);
+          if (typeof nunjucksConfig === 'function') {
+            nunjucksConfig(env);
+          } else {
+            console.error(
+              `Failed to load Nunjucks extension: Expected ${extensionPath} to export a function.`
+            );
+          }
+        } catch (err) {
+          console.error(
+            `Failed to load Nunjucks extension ${nunjucksConfigPath}.`
+          );
+        }
+      });
+    }
+  },
 };
 
 module.exports = engine_nunjucks;