Register rendering helpers programmatically

API.md

@@ -13,6 +13,9 @@ are augmented as follows:
     - [The `view` handler](#the-view-handler)
 - [Reply interface](#reply-interface)
     - [`reply.view(template, [context, [options]])`](#replyviewtemplate-context-options)
+- [View Manager](#view-manager)
+    - [`manager.registerHelper(name, helper)`](#managerregisterhelpername-helper)
+    - [`manager.render(template, context, options, callback)`](#managerrendertemplate-context-options-callback)
 
 ## [Server](https://github.com/hapijs/hapi/blob/master/API.md#server)
 
@@ -28,7 +31,7 @@ Initializes the server views manager where:
             - `compile()` - the rendering function. The required function signature depends on the
               `compileMode` settings (see below). If `compileMode` is `'sync'`, the signature is
               `compile(template, options)`, the return value is a function with signature
-              `function(context, options)` (the compiled sync template), and the method is allowed to throw errors. If 
+              `function(context, options)` (the compiled sync template), and the method is allowed to throw errors. If
               `compileMode` is `'async'`, the signature is `compile(template, options, next)`
               where `next` has the signature `function(err, compiled)`, `compiled` is a
               function with signature `function(context, options, callback)` (the compiled async template) and `callback` has the
@@ -99,6 +102,8 @@ When [`server.views()`](https://github.com/hapijs/hapi/blob/master/API.md#server
 plugin, the views manager is only available to [plugins](https://github.com/hapijs/hapi/blob/master/API.md#plugins)
 methods.
 
+`server.views()` returns a [view manager](#view-manager) that can be used to programmatically manipulate the engine configuration.
+
 ### `server.render(template, context, [options], callback)`
 
 Utilizes the server views manager to render a template where:
@@ -301,3 +306,13 @@ server.register(require('vision'), (err) => {
     </body>
 </html>
 ```
+
+# View Manager
+
+## `manager.registerHelper(name, helper)`
+
+Registers a helper, on all configured engines that have a `registerHelper()` method, for use during template rendering. Engines without a `registerHelper()` method will be skipped. The `name` is the name that templates should use to reference the helper and `helper` is the function that will be invoked when the helper is called.
+
+## `manager.render(template, context, options, callback)`
+
+Renders a template. This is typically not needed and it is usually more convenient to use [`server.render()`](#serverrendertemplate-context-options-callback).

lib/index.js

@@ -37,7 +37,9 @@ exports.register = function (server, pluginOptions, next) {
             options.relativeTo = this.realm.settings.files.relativeTo;
         }
 
-        this.realm.plugins.vision.manager = new Manager(options);
+        const manager = new Manager(options);
+        this.realm.plugins.vision.manager = manager;
+        return manager;
     });
 
     server.decorate('server', 'render', internals.render);

lib/manager.js

@@ -264,6 +264,19 @@ internals.Manager.prototype._loadHelpers = function (engine) {
 };
 
 
+internals.Manager.prototype.registerHelper = function (name, helper) {
+
+    Object.keys(this._engines).forEach((extension) => {
+
+        const engine = this._engines[extension];
+
+        if (typeof engine.module.registerHelper === 'function') {
+            engine.module.registerHelper(name, helper);
+        }
+    });
+};
+
+
 internals.Manager.prototype.render = function (filename, context, options, callback) {
 
     this._prepare(filename, options, (err, compiled) => {

test/index.js

@@ -643,6 +643,47 @@ describe('views()', () => {
         }).to.throw('Cannot set views manager more than once');
         done();
     });
+
+    it('can register helpers via the view manager', (done) => {
+
+        const server = new Hapi.Server();
+        server.register(Vision, Hoek.ignore);
+
+        const manager = server.views({
+            engines: { 'html': Handlebars.create() },
+            relativeTo: 'test/templates',
+            path: 'valid'
+        });
+
+        manager.registerHelper('long', (string) => string);
+        manager.registerHelper('uppercase', (string) => string);
+
+        server.render('testHelpers', { something: 'uppercase' }, (err, result) => {
+
+            expect(err).not.to.exist();
+            expect(result).to.equal('<p>This is all uppercase and this is how we like it!</p>');
+            done();
+        });
+    });
+
+    it('can render templates via the view manager', (done) => {
+
+        const server = new Hapi.Server();
+        server.register(Vision, Hoek.ignore);
+
+        const manager = server.views({
+            engines: { 'html': Handlebars },
+            relativeTo: 'test/templates',
+            path: 'valid'
+        });
+
+        manager.render('test', { message: 'Hello!' }, null, (err, result) => {
+
+            expect(err).not.to.exist();
+            expect(result).to.contain('<h1>Hello!</h1>');
+            done();
+        });
+    });
 });
 
 describe('Plugin', () => {

test/manager.js

@@ -10,6 +10,7 @@ const Jade = require('jade');
 const Lab = require('lab');
 const Vision = require('..');
 const Manager = require('../lib/manager');
+const Mustache = require('mustache');
 
 
 // Declare internals
@@ -1773,6 +1774,65 @@ describe('Manager', () => {
             });
         });
 
+        it('registers helpers programmatically', (done) => {
+
+            const tempView = new Manager({
+                engines: {
+                    html: { module: Handlebars.create() },
+                    txt: { module: Handlebars.create() }
+                },
+                relativeTo: 'test/templates',
+                path: 'valid'
+            });
+
+            tempView.registerHelper('long', (string) => string + string.substr(-1).repeat(2));
+            tempView.registerHelper('uppercase', (string) => string.toUpperCase());
+
+            tempView.render('testHelpers.html', { something: 'uppercase' }, null, (err, rendered1) => {
+
+                expect(err).not.to.exist();
+                expect(rendered1).to.equal('<p>This is all UPPERCASE and this is howww we like it!</p>');
+
+                tempView.render('testHelpers.txt', { something: 'uppercase' }, null, (err, rendered2) => {
+
+                    expect(err).not.to.exist();
+                    expect(rendered2).to.equal('This is all UPPERCASE and this is howww we like it!');
+                    done();
+                });
+            });
+        });
+
+        it('does not register helpers on engines that don\'t have helper support', (done) => {
+
+            const tempView = new Manager({
+                engines: {
+                    html: {
+                        compile: function (template) {
+
+                            Mustache.parse(template);
+
+                            return function (context) {
+
+                                return Mustache.render(template, context);
+                            };
+                        }
+                    }
+                },
+                relativeTo: 'test/templates',
+                path: 'valid'
+            });
+
+            tempView.registerHelper('long', (string) => string + string.substr(-1).repeat(2));
+            tempView.registerHelper('uppercase', (string) => string.toUpperCase());
+
+            tempView.render('testHelpers', { something: 'uppercase' }, null, (err, rendered, config) => {
+
+                expect(err).not.to.exist();
+                expect(rendered).to.equal('<p>This is all  and this is  we like it!</p>');
+                done();
+            });
+        });
+
         it('reuses cached compilation', (done) => {
 
             let gen = 0;

test/templates/valid/testHelpers.txt

@@ -0,0 +1 @@
+This is all {{uppercase this.something}} and this is {{long "how"}} we like it!