Array Size

This example demonstrates the use of the Docmosis size()function, and the built-in $size variable.

Using array size

When working with groups or sets of data, it may be necessary to display the total number of items in that group, or to use that number to control whether other content should be displayed or not.

Data sent to Docmosis can be organized into ordered sets of logically related elements, such as a list of client names and addresses, or a set of bank transactions. These data sets are sent to Docmosis as arrays.

The number of elements in the array (that is, the size or length of the array) can be used as follows:

• Inside a loop, such as a repeating section or repeating rows, using the built-in $size variable.
• Outside of a loop, using the size() function. For example, the expression array1.size() returns the size of the array named array1.

Array size (inside or outside of a loop) can be:

• displayed as a number, in the output document. For example, display the total number of items within a section.
• can form part of an expression in a conditional section. For example, show or hide a header in the output document depending on how much data is in the array.

To visualize array structure in the data, see the section at the end of this article: "Example of an array in the data".

Using the $size variable

The built-in $size variable can only be used from within a repeating section, such as <<rs_array1>>...<<es>>, or from within repeating rows, such as <<rr_array1>>...<<er>>. 

Use the syntax $size within a repeating section or repeating rows for an array, to reference the size of that array.

Displaying the value of $size

Within a repeating section, or within the repeating rows in a table, the size of an array can be displayed by using the $size variable in its own field: <<$size>>

In "Example 1" in the template, a single line is used within a repeating section, showing the number of the current item <<$itemnum>> out of the total number of items <<$size>>, and followed by the first name and surname for the array's current item.

The steps for this expression are:

1. Use a repeating section to loop through the Names array: <<rs_Names>>...<<es_Names>>.
2. Within the repeating section, display a line in the document that shows the person's position in the ordered array, <<$itemnum>, out of the total size of the array, <<$size>>, followed by their full name:
   Person <<$itemnum>> of <<$size>>: <<firstname>> <<surname>>.

Using $size within an expression

Use $size within an expression to form part of a conditional section.

In "Example 2", <<firstname>> and <<surname>> are only displayed in the document if the current item is the final one in the Names array.

The steps for this expression are:

1. Use a repeating section to loop through the Names array: <<rs_Names>>...<<es_Names>>.
2. Use a conditional section to determine if this is the last item in the list, by checking whether the value of the current item number is equal to the size of the list: <<cs_{$itemnum=$size}>>...<<es_>>.
3. If the condition is true, the <<firstname>> and <<surname>> for the current item of the array appear in the document.

 Note: $itemnum is the Docmosis built-in variable for the number of current item in the list/array.

Using the size() function

The size() function is accessed from outside of a loop (such as a repeating section or repeating rows).

The syntax is: array name, followed by a point, followed by size(). For example, Array1.size() returns the size of Array1.

Displaying size()

To display the value of size() type <<arrayName.size()>> where the array name is arrayName.

In "Example 3" in the template, the size of the Reservations array is displayed in the document within a sentence:

Using size() within an expression

The size() function can be used within an expression to form part of a conditional section.

In "Example 4" in the template: a section sub-heading is only displayed in the document if there is data in the Reservations array.

The steps for this expression are as follows:

1. Use a conditional section to check if there is at least one item in the Reservations array, by checking if its size is greater than zero: <<cs_{Reservations.size()>0}>>...<<es_>>.
2. If the condition is true, display the text within the conditional section: "Reservations for this year".

Use cases

These articles have example templates that use the size() function:

• Bill of Lading: Include an additional page if there are enough elements in an array. See the section "Conditional Pages". 
• Candidate Resume: Include an additional section, only if the array is not empty. See the section "Checking if an array is empty".

These articles have example templates that use the $size variable:

• Shipping Invoice: Display the total number of waybills in an array, as part of a table header. See the section "Built-in Docmosis variables".
• Candidate Resume: Include an extra bullet point if there is another array element to display. See the section "Displaying a two-column bullet list"
• This, This and That: Insert commas between words where appropriate, when constructing a string expression out of array elements. See the section "Example 1".

Example of an array in the data

In this JSON example, an array called ctrs has the items for container data: