Listing things with eachz and itemz > item

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

    • generate bullet lists: put mode: 'list'

  • use mode: 'combined' to assemble at 2 different levels; see 2 levels assembly

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.

List specific parameters

  • list_capitalize: boolean; put true to capitalize each element (defaults to false)

  • 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)

  • list_type: ul for unordered list, ol for ordered list; defaults to ul

  • 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:

  1. generating a set of sentences, each made of a limited number of the elements

  2. and then assembling these sentences together

Use 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 eachz and itemz.

Advanced: assemble dynamically

Dynamic assembly

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:

  1. create a JavaScript function that takes 1 parameter: the real length of the list, and returns the proper assembly

  2. reference that function in assembly

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 mix, the mix property must be at the top level, in the same structure as the assembly reference, as mix must occur before counting which elements are empty or not.
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 listInfo.nonEmpty in the itemz > item structure

will output either first, second and also third or first and second depending on WITH_3 flag.

  • When in a a eachz structure, elements are objects, while when in an itemz > item structure, elements are integers.

  • When you read listInfo.nonEmpty or 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.nonEmpty properly populated. Thus just test and ignore if undefined.