# Repeating list datafields

## Introduction

_Repeating list_ datafields are a very special type of datafield. They differ from the other types of datafields in two aspects:

* While all other types of datafields can only hold one single type of value (e.g. text, currency, number, date, etc.), a _repeating list_ can in principle hold any type of value and are therefore very versatile.
* Similar to _list of texts_ type datafields, they enable users to enter multiple values into one datafield.

## Creating a repeating list datafield

In order to insert a _repeating list_ datafield, simply create a new datafield and click on _repeating list_.

<figure><img src="https://1353649376-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaTEDNbiFdDa6DW2eNG17%2Fuploads%2FGGOE2tqI00cOuoQQrJJx%2Fimage.png?alt=media&#x26;token=1614b1d0-0b9f-4d08-9e0f-7750c0769b4a" alt="" width="375"><figcaption></figcaption></figure>

As mentioned above, repeating list datafields are special in that they can contain elements of all other data types in Clause9: text, true/false, number, floating point number, currency, date and duration.

<figure><img src="https://1353649376-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaTEDNbiFdDa6DW2eNG17%2Fuploads%2FmbKDlWZSYARubLWFdqjB%2Fimage.png?alt=media&#x26;token=2989a8e8-6dfb-4e4b-8459-212d7858e0a6" alt="" width="375"><figcaption><p>By default, an element in a repeating list datafield can take the form of any other type of datafield in ClauseBase.</p></figcaption></figure>

In most cases, however, it will be useful and often even necessary to limit this to only **one type** of data (e.g. to improve user experience, making it impossible for the end user to enter the wrong data type). This can be done by editing the datafield, setting the **element type** to the desired type of data and saving the changes.

<figure><img src="https://1353649376-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaTEDNbiFdDa6DW2eNG17%2Fuploads%2FBVHV6gT32m4CwJi1cRLf%2Fimage.png?alt=media&#x26;token=60c25880-af2c-4012-937e-83acff962b48" alt="" width="563"><figcaption></figcaption></figure>

## Repeating list logic

_Repeating list_ datafields allow you to store multiple values, possibily of different datatypes, in a single datafield. Conceptually, you can think of the datafield as creating an (imaginary) **column of a** **table**. Inserting a new value (element) into the datafield adds another row cell to that column. Thus, each _repeating list_ datafield in essence stores a column with as many cells (rows) as there are elements in that datafield.

This logic is also visualized in the datafield pane. As you can see in the screenshot, the _repeating list_ datafield called _items-to-return_ stores multiple values. It essentially stores a column of items that need to be returned.

<figure><img src="https://1353649376-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaTEDNbiFdDa6DW2eNG17%2Fuploads%2FRJffDaVyqwuTVekRCclC%2Fimage.png?alt=media&#x26;token=9a646dc1-4303-4fca-9632-800b12cc8fb8" alt="" width="563"><figcaption></figcaption></figure>

Keeping that in mind, _repeating list_ datafields enable you to do the following things:

* You can insert a list of values on a **single insertion point into a single clause** (whereas the items themselves can be different datatypes) using a single repeating list datafield. For instance, we can insert a list of items that need to be returned by an employee, by using a single single datafield (_items-to-return_).

<figure><img src="https://1353649376-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaTEDNbiFdDa6DW2eNG17%2Fuploads%2F1sjB6A9rnY56YaLri4s5%2Fimage.png?alt=media&#x26;token=d85e8913-07e7-41fe-aeba-7d1ff2512914" alt="" width="530"><figcaption></figcaption></figure>

* You can **repeat document elements** (clauses, bullets, table rows, documents,…) whereby each element contains one data input (“table row”) from the _repeating list_ datafield. So, instead of having **a single clause** that says which items need to be returned, Clause9 can **automatically display** **a new clause for each item** that was included in the repeating list datafield. Each element is used in a new clause.

<figure><img src="https://1353649376-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaTEDNbiFdDa6DW2eNG17%2Fuploads%2FWPizKEURXOQiRFzp6ywL%2Fimage.png?alt=media&#x26;token=6c5d2d1b-15e1-4f81-a222-c1258f57b467" alt="" width="432"><figcaption></figcaption></figure>

* An even more powerful use of repeating list datafields is “linking” columns in an (imaginary) table together. Different repeating list datafields that are used in the same repeating clause (e.g. containing a bullet) or table row will thus form one large table, where each repeating list datafield can be thought of as a column in that table and each element in those datafields as a row in the table. The images below give a practical example:

<figure><img src="https://1353649376-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaTEDNbiFdDa6DW2eNG17%2Fuploads%2FeUgC5CB34xZ5HOj46alK%2Fimage.png?alt=media&#x26;token=97bd340f-9312-4f84-a037-32dad6ae8a69" alt="" width="563"><figcaption></figcaption></figure>

<figure><img src="https://1353649376-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaTEDNbiFdDa6DW2eNG17%2Fuploads%2FeWezoSppcT6xOote7fzU%2Fimage.png?alt=media&#x26;token=be0ef35f-a5fb-4193-895b-dd97c97306d4" alt=""><figcaption><p>Example of elements in each of the repeating list datafields</p></figcaption></figure>

<figure><img src="https://1353649376-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaTEDNbiFdDa6DW2eNG17%2Fuploads%2FlERlOn3axRDztiaGgbyc%2Fimage.png?alt=media&#x26;token=73ca16f0-6731-4e4d-b4d2-bb5d87cda89e" alt=""><figcaption><p>End result</p></figcaption></figure>

As can be seen in the above example, each first element of a repeating list datafield is displayed in the first repeating bullet, each second element is displayed in the second bullet and each third element is displayed in the third bullet. Conceptually, you can think of these inputs forming the following table:

| **year** | **number-shares** | **strike-price** |
| -------- | ----------------- | ---------------- |
| 2021     | 100               | 15,000 EUR       |
| 2022     | 200               | 30,000 EUR       |
| 2023     | 300               | 40,000 EUR       |

More information on how to create repeating clauses, bullets or tables can be found below under [Use cases](broken-reference).

## Use cases <a href="#use-cases" id="use-cases"></a>

### Repeat a single clause

As shown above, with _repeating list_ datafields you can repeat elements (such as clauses) based on the data input (“table row”) of a _repeating list_ datafield. In order to achieve this, we first need to create a clause with a _repeating list_ datafield, in the example below called _name_.

<figure><img src="https://1353649376-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaTEDNbiFdDa6DW2eNG17%2Fuploads%2FwwMkS1HvG7CqbAO5i6ih%2Fimage.png?alt=media&#x26;token=f6907682-4679-44ef-b443-851a7a385c35" alt="" width="563"><figcaption></figcaption></figure>

Under the _advanced_ pane, we then navigate to _repeat clause_ and choose the datafield based on which the clause shall be repeated. In this case, we want a new clause to be added for each new name that we input into our datafield. So, we have to choose the name datafield.

<figure><img src="https://1353649376-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaTEDNbiFdDa6DW2eNG17%2Fuploads%2FdFQQwv0aRwuUSO1DmqwJ%2Fimage.png?alt=media&#x26;token=d5d11d1b-c228-4893-a3c1-73efbcc94c96" alt="" width="563"><figcaption></figcaption></figure>

If we now insert multiple names in this _repeating list_ datafield, you can see that a new clause is created for each new name.

<figure><img src="https://1353649376-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaTEDNbiFdDa6DW2eNG17%2Fuploads%2FVAOXWT5wGlRzpEx8GFj4%2Fimage.png?alt=media&#x26;token=59eb52ff-748e-486e-8921-8219b11101ee" alt=""><figcaption></figcaption></figure>

Clause9 achieves such “clause magic” because of the way it stores the _repeating list_ data input. Although the value input is stored in the same datafield, each item is still stored as a separate value. This allows Clause9 to iterate through each value input (“table row”) and use it in a separate clause.

### Repeat table rows

With repeating list datafields, you can create tables with repeating rows. In this example, we want a new row to be added for each new name or intern number that we input. In order to do so, a table first needs to be created. The datafield _name_ and _intern-number_ are both repeating list datafields.

<figure><img src="https://1353649376-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaTEDNbiFdDa6DW2eNG17%2Fuploads%2F7BFZH7iBn1zS4o1Uhd30%2Fimage.png?alt=media&#x26;token=43e64a81-cdc7-4951-a51d-d69fc5ef56f3" alt="" width="358"><figcaption></figcaption></figure>

In the _datafield_ pane, we can now input multiple values and multiple datatypes.

<figure><img src="https://1353649376-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaTEDNbiFdDa6DW2eNG17%2Fuploads%2FS8WhC6CcO62Vf9Buqybp%2Fimage.png?alt=media&#x26;token=266b1a31-7771-44bf-966a-ace84e18175a" alt="" width="563"><figcaption></figcaption></figure>

In the document preview, you will be able to see that for each new data element that we input, a new row will be added. In tables, there is no special setting to be applied. Rows containing repeating list datafields will be repeated automatically.

<figure><img src="https://1353649376-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaTEDNbiFdDa6DW2eNG17%2Fuploads%2FnvAKszmsmG3WNMjW5uiv%2Fimage.png?alt=media&#x26;token=b3d34025-aed2-454e-ab6a-06fe1ed3d002" alt="" width="563"><figcaption></figcaption></figure>

{% hint style="info" %}
Clause9 allows you to create a lot more repeating “clause magic” than just repeating clauses and table rows! You can also repeat bullets or even entire documents. That is especially useful for use cases like [advanced party introduction clauses](../clauses/how-to-clauses/creating-advanced-party-introduction-clauses). If you want to know more about this topic, feel free to check out [this article](../clauses/how-to-clauses/make-a-clause-repeat).
{% endhint %}

## Miscellaneous

### Repeating list datafield vs. repeating list of texts

_Repeating list_ datafields may remind you of another special type of datafields: _list of texts_ datafields. (You may recall that _list of texts_ datafields also allow you to store multiple data values using a single datafield.) However, there are two key differences between these two types:

* As suggested by the name, _list of texts_ can only store text values. So, if you want to insert any other data types (numbers, floating point numbers, duration, …) you need to use _repeating list_ datafields instead.
* The second difference is that, by default, without any extra measures being taken, **each list of text will be displayed as a whole**.

In the screenshot below, the items that need to be returned by the intern are inserted using a _list of texts_ datafield. The _advanced_ setting “repeat clause” was applied to make the clause repeat itself for each new list item. First of all, you can see that the clause was repeated three times since there are three list items. Secondly, this example also shows that with _list of texts_ datafields, the list is always displayed as a whole, i.e. every three list items are displayed in each clause.

<figure><img src="https://1353649376-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaTEDNbiFdDa6DW2eNG17%2Fuploads%2FQVFsVMzspf849JrNc7pB%2Fimage.png?alt=media&#x26;token=b5224967-5108-4cc5-a5dd-06b5bf1f8c61" alt="" width="563"><figcaption></figcaption></figure>

You can, however, take extra measures to extract the individual items from the _list of texts_. In the example above, for example you could use the following code:

```
#Intern needs to return @nth(#items-to-return^element, @index).
```

which results in:

<figure><img src="https://1353649376-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaTEDNbiFdDa6DW2eNG17%2Fuploads%2FdKlnqRY9Jp9omhFIG4iC%2Fimage.png?alt=media&#x26;token=048c4379-ebe9-4781-92c3-272878830793" alt="" width="225"><figcaption></figcaption></figure>

Similarly, you could also use `@bullets(#items-to-return^element)` or one of its variations to turn the _list of texts_ into a bulleted list:

<figure><img src="https://1353649376-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaTEDNbiFdDa6DW2eNG17%2Fuploads%2FYagBRCgjWCusxPP2mIKF%2Fimage.png?alt=media&#x26;token=da895747-1346-497f-9880-766c3361a73c" alt="" width="225"><figcaption></figcaption></figure>

### Conditions <a href="#conditions" id="conditions"></a>

When used inside **repeating clauses or table rows**, repeating list datafields act as the corresponding non-list type datafield — i.e. the clause will actually “see” each individual element in the list, instead of the text as a whole, e.g. a text element of a repeating list datafield will act as a text type datafield, a date element of a repeating list datafield will act as a date type datafield and so on. That also means that in the Clause9 grammar, [conditions must be written](../clauses/writing-conditions) to take that into account. E.g. for a text element the grammar would be: `{#concept^repeating-list-text = "sample text": text to display}` and **not** the condition grammar that you would use for lists: `{"sample text" in #concept^repeating-list-text: text to display}`.

Note however that for repeating list datafields [that were not assigned a specific element type](broken-reference), once you used a certain comparison operator that only “makes sense” with a certain datatype, you must stick with the data type that was assigned to the _repeating list_ datafield by implication.

#### **Example**

The condition `{#test^repeating-list`` `**`> 10`**` ``: This number is bigger than 10.}` only makes sense if the data input is a number or a floating point number, not for instance a text. So, even though we can technically use any data type, the data type that makes sense is implied by the condition.

Thus, if we use this condition `{#test^repeating-list`` `**`= "text"`**` ``: This is some text.}` next, we are suggesting that the data input is text. If the user would then insert a date type element, Clause9 will then be confused as to which data type the input shall be and an error message will prompt.

### “Escaping” the repeating nature

In some cases, you want the repeating list datafield to display its entire list even inside a repeating clause or table row. Or — for example — you want to use a special function that only works on list type datafields (e.g. the `@count` [special function](../special-functions)) inside a repeating clause/table row.

By default however, inside a repeating clause or table row, the repeating list datafield will act exactly the same way a “normal” (non-list type) datafield acts. That means that, as we have seen, the repeating clause/table row will only display the one element that corresponds to that row (cf.[ above](broken-reference)). That also means that for conditions, the datafield will act as its non-list counterpart (cf. [above](broken-reference)).

There is a way to force the repeating list datafield to again act as a _list_ datafield inside repeating clauses/table rows and that is by including an underscore in the datafield reference in the Clause9 grammar, like this: `#concept^_repeating-list`. Written like this, the datafield will **always** act like a list datafield and will thus display all elements that were inserted into it and can be used for special functions that require list datafields (e.g. `@count(#concept^_repeating-list`).

## Other avenues to repeat elements

Besides repeating lists, you can also use `@for` and `@for-calc` to create “repeating” words, sentences, paragraphs, table rows, etc. This is an advanced subject, explained in great depth in [another page](../clauses/for-loops).
