Custom Engine

Sources on GitHub jsreport-ejs

This tutorial shows how you can add a custom templating engine into jsreport. Adding a custom engine is not such common as adding a custom recipe but still can become handy if you prefer to use a specific engine or have some special requirements that already supported engines doesn't fulfill.

One of the templating engines you may like to add as a custom engine is EJS. With EJS you can assemble html or xml in the quite convenient way using special tags inlining javascript.

<ul>
<% for(var i=0; i<supplies.length; i++) {%>
   <li> <%= supplies[i] %> </li>
<% } %>
</ul>

This tutorial shows you how to add support for EJS into jsreport as a custom extension. Before you continue it is recommended to read general information for writing jsreport custom extensions.

---

Get started

The first thing to do is downloading and installing extension starter kit. As the second step you can rename the extension in jsreport.config.js.

module.exports = {
  "name": "ejs",
  "main": "lib/main.js"
}

Register engine

Extension's main server javascript file has to export function which is then called by jsreport during initialization. In the function's body you should add the new EJS engine into the engines collection.

Engine is identified by its name and path to the engine script. The engine implementation needs to be separated into the dedicated file because it will run in the different process for the security reasons.

//ejs.js
module.exports = (reporter, definition) => {
  reporter.extensionsManager.engines.push({
    name: "ejs",
    pathToEngine: require("path").join(__dirname, "engine.js")
  });
};

EJS rendering

Now it's time to finally implement the EJS rendering function, but first you need to install two packages the function will require.

npm install ejs --save
npm install node.extend --save

The rendering function is then very simple. Only thing you need to do is to merge helpers object and data object into one because EJS accepts the single context object with both functions and local attributes on it.

//engine.js
const ejs = require('ejs')
const extend = require('node.extend')

module.exports = (html, helpers, data) => {
  const template = ejs.compile(html)

  return function (helpers, data) {
    const ejsMix = extend(true, helpers, data)
    delete ejsMix.filename
    return template(ejsMix)
  }
}

Testing

Now you can hit npm start and you should be able to reach the jsreport studio on http://localhost:5488 and test the engine.

Distributing

The best way to distribute the new engine into the public audience is through the npm. To prepare the package for publishing you should change the package name, author and other attributes in package.json file. Afterwards you can simply type

npm publish

and the package will be publicly available in npm.

Syntax highlighting in studio

The last optional step is to add a syntax highlighting into the jsreport studio, but fortunately, this will be easier than it looks like.

jsreport studio uses ace editor which supports syntax highlighting for the most of the currently used languages. The only thing we need to do is pack the syntax highlighting for ejs and configure the jsreport editor when to use it.

The first lets download and install brace package which includes the syntax highlighting sources

npm install brace --save-dev

Then use studio/main_dev.js to reference particular brace ejs mode and Studio.templateEditorModeResolvers to register it.

import Studio from 'jsreport-studio'
import 'brace/mode/ejs'

Studio.templateEditorModeResolvers.push((template) => template.engine === 'ejs' ? 'ejs' : null)