panthera-view-engine

Handlebars.js-based view engine middleware for Koa applications.

Intended for use with any kind of database, provided the database tables or collections are organized compatibly and the data is retrieved in a way the view engine is capable of consuming. Introduces the concept of themes, or numerically-identified sets of templates that include any number of layouts, any number of views, and any number of partials.

See test/integration/setup.sql for a compatible MySQL table structure.

Installation

npm install panthera-view-engine

Usage

const koa = require('koa');
const viewEngine = require('panthera-view-engine');

let app = koa();
// app.context.models = ...;
app.use(viewEngine(app));

app.use(function* () {
  yield* this.render('user', {
    name: 'Username',
    age:  'Old enough!'
  });
});

app.listen(3000);

models

The models must be attached to the Koa application context. app.context.models is expected to be an object with properties named layouts, partials, and views. Each of these is expected to implement a method that retrieves the necessary data and returns a Promise object. The resolution values of the returned Promises must be compatible with results returned from mysql queries.

The implementation that panthera-view-engine expects is the following.

let models = {


  layouts: {


    /**
     * @param  {String}  namespace
     * @param  {Number}  themeId
     * @param  {String}  layoutName
     * @param  {Number}  lastUpdated
     * @return {Promise}
     */
    getOne: function(namespace, themeId, layoutName, lastUpdated) {
      /*
      return Promise.resolve([
        [ { contents: '' } ]
      ]);
      */
    }
  },


  partials: {


    /**
     * @param  {String}  namespace
     * @param  {Number}  themeId
     * @param  {Number}  lastUpdated
     * @return {Promise}
     */
    getAll: function(namespace, themeId, lastUpdated) {
      /*
      return Promise.resolve([
        [ { name: '', contents: '' }, { name: '', contents: '' } ]
      ]);
      */
    }
  },


  views: {


    /**
     * @param  {String}  namespace
     * @param  {Number}  themeId
     * @param  {String}  viewName
     * @param  {Number}  lastUpdated
     * @return {Promise}
     */
    getOne: function(namespace, themeId, viewName, lastUpdated) {
      /*
      return Promise.resolve([
        [ { contents: '' } ]
      ]);
      */
    }
  }
};

Rendering options

By default, panthera-view-engine renders templates from themes for the namespace __default, using the theme with the id 1, falling back on the layout named main.

These options may be changed by passing in an options argument with any of the appropriate properties as a third argument:

app.use(function* () {
  let options = {
    namespace: 'anotherNamespace',
    themeId:   5,
    layout:    'anotherLayout'
  };

  // This will render 'view' with the layout 'anotherLayout' belonging to theme
  // `5`, in the namespace `anotherNamespace`.
  yield* this.render('view', {
    context: 'goes here'
  }, options);
});