feat: improve template helper wiring

dist/helpers/handlebars-helpers.js

@@ -26,7 +26,7 @@ Template helper definitions for Handlebars.
   @method registerHelpers
    */
 
-  module.exports = function(theme, opts) {
+  module.exports = function(theme, rez, opts) {
     var curGlob, ex, glob, slash, wrappedHelpers;
     helpers.theme = theme;
     helpers.opts = opts;
@@ -37,7 +37,7 @@ Template helper definitions for Handlebars.
           var args;
           args = Array.prototype.slice.call(arguments);
           args.shift();
-          args.pop();
+          args[args.length - 1] = rez;
           return func.apply(this, args);
         });
       }

dist/renderers/handlebars-generator.js

@@ -51,8 +51,6 @@ Definition of the HandlebarsGenerator class.
     },
     generate: function(json, jst, format, curFmt, opts, theme) {
       var ctx, encData;
-      registerPartials(format, theme);
-      registerHelpers(theme, opts);
       encData = json;
       if (format === 'html' || format === 'pdf') {
         encData = json.markdownify();
@@ -60,6 +58,8 @@ Definition of the HandlebarsGenerator class.
       if (format === 'doc') {
         encData = json.xmlify();
       }
+      registerPartials(format, theme);
+      registerHelpers(theme, encData, opts);
       ctx = {
         r: encData,
         RAW: json,

src/helpers/handlebars-helpers.coffee

@@ -17,23 +17,28 @@ Register useful Handlebars helpers.
 @method registerHelpers
 ###
 
-module.exports = ( theme, opts ) ->
+module.exports = ( theme, rez, opts ) ->
 
   helpers.theme = theme
   helpers.opts = opts
   helpers.type = 'handlebars'
 
+  # Prepare generic helpers for use with Handlebars. We do this by wrapping them
+  # in a Handlebars-aware wrapper which calls the helper internally.
   wrappedHelpers = _.mapObject helpers, ( hVal, hKey ) ->
     if _.isFunction hVal
       return _.wrap hVal, (func) ->
         args = Array.prototype.slice.call arguments
-        args.shift() # lose the 1st element (func)
+        args.shift()                  # lose the 1st element (func) [^1]
-        args.pop() # lose the last element (the Handlebars options hash)
+        #args.pop()                   # lose the last element (HB options hash)
-        func.apply @, args
+        args[ args.length - 1 ] = rez # replace w/ resume object
+        func.apply @, args            # call the generic helper
     hVal
   , @
-
   HANDLEBARS.registerHelper wrappedHelpers
+
+  # Prepare Handlebars-specific helpers - "blockHelpers" is really a misnomer
+  # since any kind of Handlebars-specific helper can live here
   HANDLEBARS.registerHelper blockHelpers
 
   # Register any theme-provided custom helpers...
@@ -64,3 +69,9 @@ module.exports = ( theme, opts ) ->
         inner: ex
         glob: curGlob, exit: true
       return
+
+# [^1]: This little bit of acrobatics ensures that our generic helpers are
+# called as generic helpers, not as Handlebars-specific helpers. This allows
+# them to be used in other templating engines, like Underscore. If you need a
+# Handlebars-specific helper with normal Handlebars context and options, put it
+# in block-helpers.coffee.

src/renderers/handlebars-generator.coffee

@@ -30,7 +30,9 @@ HandlebarsGenerator = module.exports =
     try
       # Compile and run the Handlebars template.
       template = HANDLEBARS.compile tpl,
-        strict: false, assumeObjects: false, noEscape: data.opts.noescape
+        strict: false
+        assumeObjects: false
+        noEscape: data.opts.noescape
       return template data
     catch
       throw
@@ -42,10 +44,6 @@ HandlebarsGenerator = module.exports =
 
   generate: ( json, jst, format, curFmt, opts, theme ) ->
 
-    # Set up partials and helpers
-    registerPartials format, theme
-    registerHelpers theme, opts
-
     # Preprocess text
     encData = json
     if format == 'html' || format == 'pdf'
@@ -53,6 +51,10 @@ HandlebarsGenerator = module.exports =
     if( format == 'doc' )
       encData = json.xmlify()
 
+    # Set up partials and helpers
+    registerPartials format, theme
+    registerHelpers theme, encData, opts
+
     # Set up the context
     ctx =
       r: encData