Listing things with eachz
and itemz > item
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 theitemz
structures: assembly parameters.
The eachz
structure
First example
This will output A, B, C and D.
eachz
has this structure:
-
The name of the iteration variable (here
elt
) -
An array of elements to iterate on, after
in
keyword -
An assembly structure after
with
keyword. See assembly parameters -
And in the block anything you want ((displaying some kind of information about the element is generally a good idea).
Assembly parameters
There are plenty of parameters combinations and soeme 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>
: putmode: '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 withbegin_with_1
andif_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
.