Development, packaging and rendering of the RosaeNLG templates

This is the documentation for 1.20.2 version, which is not the latest version. Consider upgrading to 3.4.0.

As RosaeNLG is primarly a node.js library, the easiest setup is just to use it in a simple node.js app: see Quick Start.

Still, there are multiple other possible ways to use RosaeNLG. A pipeline has 3 steps:

  1. develop NLG templates

  2. package the templates - which can be optional depending how you will run them

  3. render the templates to generate production texts

Table 1. Typical setups
Situation Develop Package Render

if you like node.js

one single node.js project using RosaeNLG npm library, and containing the templates

if you need to have Java for production

node.js project to develop the templates

use RosaeNLG Packager to package them

RosaeNLG Java Server to render them

if you don’t like node.js neither Java (but ok with Docker)

use Docker CLI for RosaeNLG to develop, test and package your templates

dockerized version of RosaeNLG Java Server to render them through an API

if you want to develop simple templates

directly in the browser IDE

use "Package" button in the browser IDE

use the RosaeNLG API on Rapid API

Develop RosaeNLG templates

  • Just create a node.js project and use RosaeNLG npm library. You can use the RosaeNLG node.js boilerplate project as a starting point for your NLG project.

  • Alternatively, you can use Docker CLI for RosaeNLG to test and render your templates. Just use VSCode (or whatever editor) to edit your templates, and test them using the Docker CLI.

  • For very small projects, you could the browser IDE.

Package RosaeNLG templates

Most of the time you don’t have to package anything: templates can directly be rendered server side. Pug’s integrated cache system is very efficient, compile will occur only once automatically.

  • Use RosaeNLG Packager:

    • to compile templates for client side rendering with compileTemplateToJsString

    • to package templates in a JSON file, to use in RosaeNLG Java Server, with completePackagedTemplateJson

  • Alternatively you can use Docker CLI for RosaeNLG to package templates in a single JSON file.

  • You might use Java Wrapper to compile templates, for browser rendering typically.

The browser IDE also allows to bundle a JSON package.

Render RosaeNLG templates

  • Create a node.js app (server, batch, whatever) using RosaeNLG npm library and use renderFile to render your templates.

  • Render your templates directly in a browser, client-side, after having compiled them in the packaging process.

  • Create a java application and use the RosaeNLG Java Wrapper to render your templates.

  • Run a RosaeNLG Java Server (standalone server or in Tomcat) and use the API to load JSON packaged templates and render them.

  • Use the dockerized version of RosaeNLG Java Server to do exactly the same.

  • Use the RosaeNLG API on Rapid API

  • Deploy your own RosaeNLG Lambda functions

Output data, and not only text

The main feature of RosaeNLG is to output text - actually in the renderedText field. But sometimes, data is computed in the templates (in JavaScript files), and you might wish to output this data as well.

When using the library, you can easily share variables:

In your RosaeNLG template:

- outputData.foo = 'bar'; // writing in a variable
| some text

In your JavaScript:

const text = rosaenlg.renderFile('template.pug', {
  language: '...',
  data: ...,
  outputData: {}, // or any name - to share data between RosaeNLG and its context
});

console.log(outputData.foo); // should output 'bar'

When using the API (node, Lambda or Java):

  • in your template, use the outputData variable: - outputData.obj = {aaa: 'bbb'};

  • in the API answer, read the outputData field, which will here contain {"obj":{"aaa":"bbb"}