Add server and plugin render(). Closes #1795

hapijs · Aug 5, 2014 · 88a2fef · 88a2fef
1 parent ce687c6
commit 88a2fef
Show file tree

Hide file tree

Showing 8 changed files with 205 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@
 and other essential facilities for building web applications and services. **hapi** enables developers to focus on writing reusable
 application logic instead of spending time building infrastructure, without getting in the way.
 
-Current version: **6.3.x** ([release notes](https://github.com/hapijs/hapi/issues?labels=release+notes&page=1&state=closed)) [![Build Status](https://secure.travis-ci.org/hapijs/hapi.svg)](http://travis-ci.org/hapijs/hapi)
+Current version: **6.5.x** ([release notes](https://github.com/hapijs/hapi/issues?labels=release+notes&page=1&state=closed)) [![Build Status](https://secure.travis-ci.org/hapijs/hapi.svg)](http://travis-ci.org/hapijs/hapi)
 
 For the latest updates and release information visit [hapijs.com](http://hapijs.com) and follow [@hapijs](https://twitter.com/hapijs) on twitter.
 

diff --git a/docs/README.md b/docs/README.md
@@ -1,7 +1,9 @@
 ## Current Documentation
-  [v6.3.x](https://github.com/hapijs/hapi/blob/master/docs/Reference.md)  
+  [v6.5.x](https://github.com/hapijs/hapi/blob/master/docs/Reference.md)  
 
 ## Previous Documentation
+  [v6.4.x](https://github.com/hapijs/hapi/blob/v6.4.0/docs/Reference.md)
+  [v6.3.x](https://github.com/hapijs/hapi/blob/v6.3.0/docs/Reference.md)
   [v6.2.x](https://github.com/hapijs/hapi/blob/v6.2.0/docs/Reference.md)
   [v6.1.x](https://github.com/hapijs/hapi/blob/v6.1.0/docs/Reference.md)
   [v6.0.x](https://github.com/hapijs/hapi/blob/v6.0.0/docs/Reference.md)

diff --git a/docs/Reference.md b/docs/Reference.md
@@ -1,4 +1,4 @@
-# 6.3.x API Reference
+# 6.5.x API Reference
 
 - [`Hapi.Server`](#hapiserver)
     - [`new Server([host], [port], [options])`](#new-serverhost-port-options)
@@ -32,6 +32,7 @@
         - [`server.inject(options, callback)`](#serverinjectoptions-callback)
         - [`server.handler(name, method)`](#serverhandlername-method)
         - [`server.location(uri, [request])`](#serverlocationuri-request)
+        - [`server.render(template, context, [options], callback)`](#serverrendertemplate-context-options-callback)
     - [`Server` events](#server-events)
 - [Request object](#request-object)
     - [`request` properties](#request-properties)
@@ -88,6 +89,7 @@
         - [`plugin.cache(options)`](#plugincacheoptions)
         - [`plugin.bind(bind)`](#pluginbind-bind)
         - [`plugin.handler(name, method)`](#pluginhandlername-method)
+        - [`plugin.render(template, context, [options], callback)`](#pluginrendertemplate-context-options-callback)
     - [Selectable methods and properties](#selectable-methods-and-properties)
         - [`plugin.select(labels)`](#pluginselectlabels)
         - [`plugin.length`](#pluginlength)
@@ -1343,6 +1345,36 @@ var server = Hapi.createServer('localhost', 8000);
 console.log(server.location('/relative'));
 ```
 
+#### `server.render(template, context, [options], callback)`
+
+Utilizes the server views engine configured to render a template where:
+- `template` - the template filename and path, relative to the templates path configured via the server [`views.path`](#server.config.views).
+- `context` - optional object used by the template to render context-specific result. Defaults to no context `{}`.
+- `options` - optional object used to override the server's [`views`](#server.config.views) configuration.
+- `callback` - the callback function with signature `function (err, rendered, config)` where:
+    - `err` - the rendering error if any.
+    - `rendered` - the result view string.
+    - `config` - the configuration used to render the template.
+
+```javascript
+var Hapi = require('hapi');
+var server = new Hapi.Server({
+    views: {
+        engines: { html: require('handlebars') },
+        path: __dirname + '/templates'
+    }
+});
+
+var context = {
+    title: 'Views Example',
+    message: 'Hello, World'
+};
+
+server.render('hello', context, function (err, rendered, config) {
+
+    console.log(rendered);
+});
+```
 
 ### `Server` events
 
@@ -2706,6 +2738,37 @@ exports.register = function (plugin, options, next) {
 }
 ```
 
+#### `plugin.render(template, context, [options], callback)`
+
+Utilizes the plugin views engine configured to render a template where:
+- `template` - the template filename and path, relative to the templates path configured via ['plugin.views()`](#pluginviewsoptions).
+- `context` - optional object used by the template to render context-specific result. Defaults to no context `{}`.
+- `options` - optional object used to override the plugin's ['plugin.views()`](#pluginviewsoptions) configuration.
+- `callback` - the callback function with signature `function (err, rendered, config)` where:
+    - `err` - the rendering error if any.
+    - `rendered` - the result view string.
+    - `config` - the configuration used to render the template.
+
+```javascript
+exports.register = function (plugin, options, next) {
+
+    plugin.views({
+        engines: {
+            html: {
+              module: Handlebars.create()
+            }
+        },
+        path: './templates'
+    });
+
+    plugin.render('hello', context, function (err, rendered, config) {
+
+        console.log(rendered);
+        next();
+    });
+};
+```
+
 ### Selectable methods and properties
 
 The plugin interface selectable methods and properties are those available both on the `plugin` object received via the

diff --git a/lib/pack.js b/lib/pack.js
@@ -401,6 +401,15 @@ internals.Pack.prototype._plugin = function (plugin, registerOptions, state, cal
         env.views = new Views.Manager(options, override);
     };
 
+    root.render = function (template, context /*, options, callback */) {
+
+        var options = arguments.length === 4 ? arguments[2] : {};
+        var callback = arguments.length === 4 ? arguments[3] : arguments[2];
+
+        Hoek.assert(env.views, 'Missing plugin views manager');
+        return env.views.render(template, context, options, callback);
+    };
+
     root.method = function (/* name, method, options */) {
 
         var args = Array.prototype.slice.call(arguments);

diff --git a/lib/server.js b/lib/server.js
@@ -217,9 +217,7 @@ exports = module.exports = internals.Server = function (/* host, port, options *
 
     // Initialize Views
 
-    if (this.settings.views) {
-        this._views = new Views.Manager(this.settings.views);
-    }
+    this._views = (this.settings.views ? new Views.Manager(this.settings.views) : null);
 
     // Create server
 
@@ -492,6 +490,16 @@ internals.Server.prototype.views = function (options) {
 };
 
 
+internals.Server.prototype.render = function (template, context /*, options, callback */) {
+
+    var options = arguments.length === 4 ? arguments[2] : {};
+    var callback = arguments.length === 4 ? arguments[3] : arguments[2];
+
+    Hoek.assert(this._views, 'Missing server views manager');
+    return this._views.render(template, context, options, callback);
+};
+
+
 internals.Server.prototype.cache = function (name, options) {
 
     Schema.assert('cachePolicy', options, name);

diff --git a/lib/views.js b/lib/views.js
@@ -113,8 +113,6 @@ exports.Manager = internals.Manager = function (options, _override) {
 
 internals.Manager.prototype._loadPartials = function (engine) {
 
-    var self = this;
-
     if (!engine.config.partialsPath ||
         !engine.module.registerPartial ||
         typeof engine.module.registerPartial !== 'function') {
@@ -164,8 +162,6 @@ internals.Manager.prototype._loadPartials = function (engine) {
 
 internals.Manager.prototype._loadHelpers = function (engine) {
 
-    var self = this;
-
     if (!engine.config.helpersPath ||
         !engine.module.registerHelper ||
         typeof engine.module.registerHelper !== 'function') {
@@ -209,12 +205,12 @@ internals.Manager.prototype.render = function (filename, context, options, callb
     var engine = null;
 
     var fileExtension = Path.extname(filename).slice(1);
-    var extension = fileExtension || self._defaultExtension;
+    var extension = fileExtension || this._defaultExtension;
     if (!extension) {
         return callback(Boom.badImplementation('Unknown extension and no defaultExtension configured for view template: ' + filename));
     }
 
-    engine = self._engines[extension];
+    engine = this._engines[extension];
     if (!engine) {
         return callback(Boom.badImplementation('No view engine found for file: ' + filename));
     }

diff --git a/test/pack.js b/test/pack.js
@@ -2162,4 +2162,85 @@ describe('Pack', function () {
             done();
         });
     });
+
+    describe('#render', function () {
+
+        it('renders view', function (done) {
+
+            var plugin = {
+                name: 'test',
+                register: function (plugin, options, next) {
+
+                    plugin.views({
+                        engines: { 'html': require('handlebars') },
+                        basePath: __dirname + '/pack/--views',
+                        path: './templates'
+                    });
+
+                    var view = plugin.render('test', { message: 'steve' }, function (err, rendered, config) {
+
+                        plugin.route([
+                            {
+                                path: '/view', method: 'GET', handler: function (request, reply) {
+
+                                    return reply(rendered);
+                                }
+                            }
+                        ]);
+
+                        return next();
+                    });
+                }
+            };
+
+            var server = new Hapi.Server();
+            server.pack.register(plugin, function (err) {
+
+                expect(err).to.not.exist;
+                server.inject('/view', function (res) {
+
+                    expect(res.result).to.equal('<h1>steve</h1>');
+                    done();
+                });
+            });
+        });
+
+        it('renders view (with options)', function (done) {
+
+            var plugin = {
+                name: 'test',
+                register: function (plugin, options, next) {
+
+                    plugin.views({
+                        engines: { 'html': require('handlebars') }
+                    });
+
+                    var view = plugin.render('test', { message: 'steve' }, { basePath: __dirname + '/pack/--views', path: './templates' }, function (err, rendered, config) {
+
+                        plugin.route([
+                            {
+                                path: '/view', method: 'GET', handler: function (request, reply) {
+
+                                    return reply(rendered);
+                                }
+                            }
+                        ]);
+
+                        return next();
+                    });
+                }
+            };
+
+            var server = new Hapi.Server();
+            server.pack.register(plugin, function (err) {
+
+                expect(err).to.not.exist;
+                server.inject('/view', function (res) {
+
+                    expect(res.result).to.equal('<h1>steve</h1>');
+                    done();
+                });
+            });
+        });
+    });
 });
diff --git a/test/server.js b/test/server.js
@@ -1596,4 +1596,38 @@ describe('Server', function () {
             done();
         });
     });
+
+    describe('#render', function () {
+
+        it('renders view', function (done) {
+
+            var server = new Hapi.Server();
+            server.views({
+                engines: { html: require('handlebars') },
+                path: __dirname + '/templates'
+            });
+
+            server.render('valid/test', { title: 'test', message: 'Hapi' }, function (err, rendered, config) {
+
+                expect(rendered).to.exist;
+                expect(rendered).to.contain('Hapi');
+                done();
+            });
+        });
+
+        it('renders view (options)', function (done) {
+
+            var server = new Hapi.Server();
+            server.views({
+                engines: { html: require('handlebars') }
+            });
+
+            server.render('valid/test', { title: 'test', message: 'Hapi' }, { path: __dirname + '/templates' }, function (err, rendered, config) {
+
+                expect(rendered).to.exist;
+                expect(rendered).to.contain('Hapi');
+                done();
+            });
+        });
+    });
 });