Add Handlebars support for page generation

Author: Jeremie Patonnier

.gsk/docs/html/handlebars.md

@@ -0,0 +1,72 @@
+
+Handlebars
+===============================================================================
+
+Certains projets peuvent vouloir utiliser [Handlebars](handlebarsjs.com) pour
+générer les pages statiques du projet.
+
+Configuration:
+```json
+{
+  "html": {
+    "engine": "handlebars"
+  }
+}
+```
+
+
+Configuration standard
+-------------------------------------------------------------------------------
+
+### Data
+On notera que, par défaut, toutes les variables qui seront utiliser pour
+peupler les fichiers lors de la compilation sont dans le dossier `src/data`
+
+Ces données sont sous la forme de fichiers JSON avec un fichier générique
+(`src/data/data.json`), plus un fichier spécifique qui doit porter le même nom
+que le gabarit Handlebars correspondant (`src/data/mon/fichier/hbs.json`). Les
+deux sont amalgamés pour être utilisé par le gabarit Handlebars. Si les deux
+fichiers proposent les mêmes variables, celles du fichier spécifique écrase
+celles du fichier générique.
+
+### Layout
+Le layout par defaut des pages est `src/html/layout/_default.hbs`. Pour le
+changer, il suffit de changer la configuration du projet:
+```json
+{
+  "html": {
+    "layout": "_default.hbs"
+  }
+}
+```
+
+Un layout specific peut être appliqué à chaque page, il suffit de rajouter une
+clé `template` avec le nom du layout à utiliser dans le fichier de data de la
+page correspondante.
+
+> **NOTE:** _Tous les layouts doivent être placés dans le dossier
+  `src/html/layout`_
+
+Helpers
+-------------------------------------------------------------------------------
+Handlebars peut être etendu par l'usage de helpers.
+
+De manière général, pour rajouter un helpers, il suffit d'écrire un module
+CommonJS qui exposera une fonction definisant le helpers. Ce module doit être
+placé dans le dossier `.gsk/tools/handlebars/helpers`. Le nom du helper sera
+le nom du fichier (sans extention).
+
+Un helper definie de cette façon a cette forme:
+
+```javascript
+module.exports = function (/* context, */ options) {
+  return options.fn(this);
+};
+```
+Pour en savoir plus sur la création de helpers, la
+[documentation officiel de handlebars](http://handlebarsjs.com/block_helpers.html)
+est là pour vous aider
+
+Pour voir quelques exemples concrets vous pouvez jetez un coup d’œil dans le
+repertoire [.gsk/tools/handlebars/helpers](.gsk/tools/handlebars/helpers).
+

.gsk/pipe/html/handlebars.js

@@ -0,0 +1,70 @@
+// Définition du LazyPipe pour utiliser Handlebars
+'use strict';
+
+var path     = require('path');
+var _        = require('underscore');
+var lazypipe = require('lazypipe');
+var gulp     = require('gulp');
+var gutil    = require('gulp-util');
+var hbs      = require('gulp-hbs');
+var data     = require('gulp-data');
+var dir      = require('require-dir');
+var ENV      = require('../../tools/env');
+
+var DEST     = path.resolve(ENV.html['dest-dir']);
+var DEST_URL = DEST.replace(path.resolve(ENV.connect.baseDir), '')
+                   .replace(path.sep, '/');
+
+var genericDataFile  = path.resolve(path.join(ENV.html['data-dir'], 'data.json'));
+
+var layouts  = path.join(ENV.html['src-dir'], 'layout', '**', '*.hbs');
+
+// HBS HELPERS
+// ----------------------------------------------------------------------------
+var helpers = dir('../../tools/handlebars/helpers');
+
+hbs.registerHelper(helpers);
+
+// UTILS
+// ----------------------------------------------------------------------------
+function processData(file) {
+  var base = file.path.replace(ENV.html['src-dir'], ENV.html['data-dir']);
+  var specificDataFile = base.replace('.hbs', '.json');
+  var gData = {};
+  var sData = {};
+
+  try {
+    gData = require(genericDataFile);
+  } catch (e) {
+    gutil.log(gutil.colors.yellow('WARN:'),
+      'Unable to find data from',
+      genericDataFile.replace(path.resolve('.'), '').slice(1)
+    );
+  }
+
+  try {
+    sData = require(specificDataFile);
+  } catch (e) {
+    gutil.log(gutil.colors.yellow('WARN:'),
+      'Unable to find data from',
+      specificDataFile.replace(path.resolve('.'), '').slice(1)
+    );
+  }
+
+  var data  = _.extend({}, gData, sData);
+  data.url  = file.path.replace(ENV.html['src-dir'], DEST_URL).replace('.hbs', '.html');
+  data.main = hbs.handlebars.compile(file.contents.toString())(data);
+
+  return data;
+}
+
+module.exports = function () {
+  var lazystream = lazypipe()
+    .pipe(data, processData)
+    .pipe(hbs, gulp.src(layouts), {
+      dataSource: 'data',
+      defaultTemplate: ENV.html.layout || '_default.hbs'
+    });
+
+  return lazystream();
+};

.gsk/tasks/html.js

@@ -15,8 +15,7 @@ var ENV      = require('../tools/env').html;
 // On ne va compiler que les fichiers dont le nom ne commence pas par un _
 var SRC  = [
   path.join(ENV['src-dir'], '**', '*.*'),
-  path.join('!' + ENV['src-dir'], '**', '_*'),
-  path.join('!' + ENV['src-dir'], '**', '*.js')
+  path.join('!' + ENV['src-dir'], '**', '_*')
 ];
 var DEST = ENV['dest-dir'];
 

readme.md

@@ -209,6 +209,7 @@ le fichier `.gsk/config.json`, voir les [instructions de configuration](.gsk/rea
 
 ### HTML
 * [Twig](.gsk/docs/html/twig.md)
+* [Handlebars](.gsk/docs/html/handlebars.md)
 
 ### JavaScript
 * [Simple pipeline](.gsk/docs/js/simple.md)

src/html/layout/_default.hbs

@@ -0,0 +1,20 @@
+{{!-- _default.hbs --}}
+{{!-- Ce gabarit est utilisé par les pages du projets --}}
+<!DOCTYPE html>
+<html lang="fr">
+<head>
+  <meta charset="utf-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
+  <meta name="viewport" content="width=device-width,initial-scale=1,shrink-to-fit=no">
+
+  <title>{{ title }}</title>
+
+  <link href="{{root}}/css/styles.css" rel="stylesheet">
+  <script src="{{root}}/js/script.js" async></script>
+</head>
+<body>
+<section>
+  {{{ main }}}
+</section>
+</body>
+</html>