Listing things with
itemz > item
You don’t really need RosaeNLG to do loops: Pug has its
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 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
itemzstructures: assembly parameters.
This will output A, B, C and D.
eachz has this structure:
The name of the iteration variable (here
An array of elements to iterate on, after
An assembly structure after
withkeyword. See assembly parameters
And in the block anything you want ((displaying some kind of information about the element is generally a good idea).
itemz > item structure
|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
sentences with a new HTML paragraph:
generate bullet lists: put
mode: 'combined'to assemble at 2 different levels; see 2 levels assembly
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: 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_generalcan 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
This will output X ALT_LAST_SEP Y. The name of the variable must be
List specific parameters
list_capitalize: boolean; put
trueto capitalize each element (defaults to
list_end_item: string; ends each item of the list; typically put
.to end each item with a dot
list_last_end_item: string; specific end for the last item if the list (e.g. use
;for intermediate bullet ends, and
.for the last one)
ulfor unordered list,
olfor ordered list; defaults to
list_intro: text before the list, can be a string or a mixin
Advanced: 2 levels assembly
When dealing with long and dynamic lists of elements, you may wish to assemble elements in two steps, typically:
generating a set of sentences, each made of a limited number of the elements
and then assembling these sentences together
mode: 'combined', and in the
asms parameter, put 2 assemblies. The first will be the top level assembly (e.g.
mode: 'sentences'), and the second will be the second level assembly (e.g.
mode:'single_sentence'). The second must have a
max parameter, which is the maximum number of elements to use before switching to top level assembly.
It works with both
Advanced: assemble dynamically
You can dynamically generate a complete assembly depending of the number of non empty elements to assemble. For instance, when the list is very long, you may want to use a bullet list, but when the list is shorter, a single sentence might be better.
To do that:
reference that function in
RosaeNLG will first check which elements are not empty, then call the function to get the assembly parameters, and then render using that assembly.
when elements have to be shuffled, using
|you can also get a second parameter which is the list of the non empty elements.|
When assembling, knowing which elements are empty
When you list elements, it is sometimes (but very rarely) useful to be able to know which elements are empty and which are not.
The list of the non empty elements:
is sent to separators, when they are mixins and take an object parameter (see exemple)
is made available in
itemz > itemstructure
will output either first, second and also third or first and second depending on
When in a a
eachzstructure, elements are objects, while when in an
itemz > itemstructure, elements are integers.
When you read
params.nonEmpty, it can be
undefined: this happens when RosaeNLG is actually testing if the elements are empty or not. RosaeNLG will make a second call with
xxx.nonEmptyproperly populated. Thus just test and ignore if