Development, packaging and rendering of the RosaeNLG templates

This is the documentation for 3.0.1 version, which is not the latest version. Consider upgrading to 4.3.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:

develop NLG templates
package the templates - which can be optional depending how you will run them
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 yeoman to generate a standard RosaeNLG 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"}

"No Pug templates" usage

For some very specific usages you may wish to directly code the language generation using JavaScript code, making low level calls to RosaeNLG underlying API - completely bypassing Pug and the templates mechanisms. See Usage without templates