Listing things with eachz and itemz > item

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

You don’t really need RosaeNLG to do loops: Pug has its each and while methods. But when doing NLG you often want to generate texts like A, B, C and D: there’s one general kind of separator, the comma, and another one between the two last elements, the "and". When you have only two elements you would like to generate A and B, not A, B. This is why you need a proper way to list elements.

  • When the elements to list are in a javascript array, use eachz. For instance you want to list products.

  • When the elements to list are texts, mixins etc., use the itemz > item structure. For instance when you want to list the characteristics of a product, each characteristics of the product will have its own text.

  • The ways to assemble the elements are the same for the eachz and the itemz structures: assembly parameters.

The eachz structure

First example

This will output A, B, C and D.

eachz has this structure:

  1. The name of the iteration variable (here elt)

  2. An array of elements to iterate on, after in keyword

  3. An assembly structure after with keyword. See assembly parameters

  4. And in the block anything you want ((displaying some kind of information about the element is generally a good idea).

Empty elements

It will only output non-empty elements. For instance:

This will output A and D (and not A, D).

The itemz > item structure

It is a nested structure like case > when. Use it to list text elements.

This will output The ring has a huge central diamond, it is made with gold and it has 3 other diamonds if PRODUCT.gold is true. As usual, empty elements will be ignored (here when PRODUCT.gold is false).

Assembly parameters

There are plenty of parameters combinations and some of them may not have been tested.

You can generate either:

  • a single sentence: this is the default, you can also put mode: 'single_sentence'

  • multiple sentences:

    • sentences with a new HTML paragraph: <p>…​</p>: put mode: 'paragraphs'

    • without: put mode: 'sentences'

Common parameters

  • mix: boolean. the elements of the list are randomly mixed before being listed. This is often used to add diversity to the texts.

  • separator: default separator between to elements. Often "," when mode is single sentence, often "." otherwise.

  • begin_with_general: what the sentence should begin with. Could be The products are:. Often combined with begin_with_1 and if_empty

  • begin_with_1: what the sentence should begin with when there is only one element. Could be The only products is:

  • if_empty: what the sentence should begin with when there it is empty. Defaults to nothing. Could be No products today.

  • end: what the sentence should end with when it is not empty.

Single sentence specific parameters

  • last_separator: the last separator. Often " and ".

will output A, B, C and D.

Multiple sentences specific parameters

  • begin_with_general can be an array. Each element of the array will be output at the beginning of each new sentence, until exhaustion.

  • begin_last : last beginning of sentence. Could be at last.

  • begin_last_1: the previous to last beginning. Could be finally.

will output First, A. Second, B. C. As well, D. At last, E..

Classic parameters can be either string or mixins. Using a mixin is convenient when the content is variable, often for begin_with_1. These mixins can even receive parameters:

This will output X ALT_LAST_SEP Y. The name of the variable must be params.