# Introduction to tables

{% embed url="<https://vimeo.com/441303480>" %}

{% embed url="<https://vimeo.com/443360584>" %}

## General <a href="#general" id="general"></a>

Tables are collection of **cells**, organised in **rows** (horizontally) and **columns** (vertically). The first row can optionally be assigned the status of a **header row**, which will be repeated on each page if a table spans multiple pages. All the other rows are called **body rows**.

In Clause9, a simple table with one header row and is created as follows:

{% code overflow="wrap" %}

```
|| header 1 	  || header 2		|| header 3 	    ||
|| ========== 	  || ----------------- 	|| ---------------- ||
|| cell column 1  || cell column 2 	|| cell column 3    ||
```

{% endcode %}

This will result in the following table:

<figure><img src="/files/OCJz9ki8VrTDgqVSzs7C" alt="" width="449"><figcaption></figcaption></figure>

A more complex example:

{% code overflow="wrap" %}

```
|| header 1 	  || header 2		 || header for righ-aligned column  ||
|| ------------   || --------------- 	 || ------------------------------: ||
|| cell column 1  || cell column 2       || cell column 3                   ||
||> merged cell columns 1 & 2            || regular cell                    ||
||>> merged all cells                                                       ||
|| regular cell 1 || vertically merged   || regular cell 3                  ||
|| regular cell 1 ||^                    || regular cell 3                  ||
```

{% endcode %}

<figure><img src="/files/ZWIEy8GtVOfUWF7vy9M6" alt="" width="563"><figcaption></figcaption></figure>

Some general notes:

* Each cell is separated by a double pipe symbol (||).
* Rows are separated by a newline (i.e., pressing Enter).
  * It is no problem for a row to span multiple lines in the text editor, e.g. because there are too many columns to fit on one line of Clause9's text editor.
  * You can have maximum one blank line between rows of the same table. If you insert at least two blank lines between rows, then a new table will be started.
* It is not necessary to line up the double pipe symbols between lines, although it will of course be much cleaner to like at in the editor. In the .DOCX or .PDF file, this will however not make any difference.
* The first row will be treated as a header row if it is followed by a **divider row** that contains cells with either multiple dashes (—-), or multiple equal-signs (====). There should be at least three dashes / equal-signs, but no upper limit applies.
* If a column in the divider row contains equal-signs, then all the cells in that column will have a light grey background. In the example above, this is the case for the first column.
* Whether the table contains borders, and whether it is left-aligned, center-aligned, right-aligned or instead stretched across the entire width of the page, can be changed in the *base* styling.

## Automatically reformatting a table

You can automatically reformat how a table looks inside the Clause9 grammar:

<figure><img src="/files/h8Hm0OQ600QG5Y4BWKWG" alt="" width="563"><figcaption></figcaption></figure>

by pressing “reformat tables” in the popup-menu at the right side:

<figure><img src="/files/7h3FyIQjddtXxQY2BhH2" alt="" width="563"><figcaption></figcaption></figure>

becomes

<figure><img src="/files/8USB5nLUNpyikj4HHpGA" alt="" width="563"><figcaption></figcaption></figure>

## Inserting large amounts of text <a href="#inserting-large-amounts-of-text" id="inserting-large-amounts-of-text"></a>

If you want to insert multiple paragraphs into a single cell, you have to use the internal inclusions mechanism. After all, remember that inserting a newline (Enter) would start a new row of the table…

Example:

{% code overflow="wrap" %}

```
|| alpha  || beta    || gamma ||
|| @DELTA || epsilon || zeta  ||

DELTA = this is a large amount of text... 

... spanning multiple paragraphs...

... that will be inserted in the first cell of the second row
```

{% endcode %}

results in:

<figure><img src="/files/HdnI1ArO35hEclL89ksW" alt="" width="563"><figcaption></figcaption></figure>

## Alignment of cells <a href="#alignment-of-cells" id="alignment-of-cells"></a>

The dashes or equal-signs in the divider row can optionally contain a colon (:) before the first dash/equal-sign and/or after the first dash/equal-sign. The presence of these colons will cause all the cells in that column to be left, center or right-aligned, respectively. For example:

* `:—--` or `:===` will cause the cells to be left-aligned
* `:—--:` or `:===:` will cause the cells to be center-aligned
* `---:` or `===:` will cause the cells to be right-aligned
* no colon will cause the cells to receive the general alignment specified in the styling (typically left-aligned or justified).

## Merging columns (horizontal cell merging) <a href="#merging-columns-horizontal-cell-merging" id="merging-columns-horizontal-cell-merging"></a>

A cell can optionally span multiple columns. This can be achieved by inserting one or more larger-than symbols (>) immediately after the double pipe (without any space in between).

Example:

{% code overflow="wrap" %}

```
|| alpha           || beta            || gamma       ||
||>> delta     
|| epsilon        || zeta             || eta         ||
```

{% endcode %}

will be outputted as:

<figure><img src="/files/EtCtYMOFxY5VDDL18WoY" alt="" width="338"><figcaption></figcaption></figure>

## Merging rows (vertical cell merging) <a href="#merging-rows-vertical-cell-merging" id="merging-rows-vertical-cell-merging"></a>

A cell can optionally be merged with the cell above it. This can be achieved by inserting a *caret* symbol (^) after the double-pipes. The cell must not contain any other content. Example:

{% code overflow="wrap" %}

```
|| alpha           || beta            || gamma       ||
||^                || delta           || epsilon     ||
```

{% endcode %}

will be outputted as:

<figure><img src="/files/tcBplRweKaobLSsTojmi" alt="" width="425"><figcaption></figcaption></figure>

Note that horizontal and vertical merging can be combined. The cell that contains the caret will then have the same horizontal merging amount as the above cell it is merged with. Example:

{% code overflow="wrap" %}

```
|| alpha           || beta            || gamma       ||
||> delta                             || epsilon     ||
||^                                   || zeta        ||
```

{% endcode %}

will be outputted as:

<figure><img src="/files/Hll7Ycm47RDaEiH8Hevp" alt="" width="315"><figcaption></figcaption></figure>

## Conditional rows <a href="#conditional-rows" id="conditional-rows"></a>

Each body row can optionally contain a condition that will determine whether or not the row will be shown. This condition can be any valid condition, needs to be surrounded by curly brackets, and needs to be inserted after the last set of double-pipes. For example:

Example:

{% code overflow="wrap" %}

```
|| alpha    || beta  || 
|| ----     || ----  ||
|| gamma    || delta || {#deal^value > 5000 EUR}
|| epsilon  || zeta  || {#deal^value <= 5000 EUR}
```

{% endcode %}

In this example, the row with cells *gamma* and *delta* will only be shown if the *#deal^value* data-field happens to be larger than 5000 EUR. If not, the row with *epsilon* and *zeta* will be shown.

## Conditional columns <a href="#conditional-columns" id="conditional-columns"></a>

Similar to rows, columns can also be made conditional, by inserting a condition in curly brackets on the first row of the table. For example:

{% code overflow="wrap" %}

```
|| {#deal^value > 5000 EUR} ||       ||
|| alpha                    || beta  || 
|| ----                     || ----  ||
|| gamma                    || delta || 
|| epsilon                  || zeta  ||
```

{% endcode %}

The first column will not be shown if the *#deal^value* data-field contains a value lower than 5000 EUR.

## Repeating rows <a href="#repeating-rows" id="repeating-rows"></a>

A row will be automatically repeated if it contains at least one *repeating* data-field (hence the name of this type of data-field). The row will then be repeated for as many times as there are values in the repeating data-field. (If multiple repeating data-fields are used, then the repetition-amount will be equal to the amount of the repeating data-field with the largest amount of repeating data-fields)

For example, assume that the *#item^name, #item^price* and *#item^quantity* data-fields are all repeating-fields, containing the following values:

* *#item^name*: alpha, beta, gamma and delta
* *#item^price:* 100 EUR, 200 EUR, 300 EUR and 400 EUR
* *#item^quantity:* 1, 2 and 3.

The following table:

{% code overflow="wrap" %}

```
|| name       || price       || quantity       ||
|| ====       || -----       || -------------- ||
|| #item^name || #item^price || #item^quantity ||
```

{% endcode %}

will then result in the following output:

<figure><img src="/files/1FmSG1TSjtGfTn2SAyel" alt="" width="465"><figcaption></figcaption></figure>

Notice that the quantity of delta is not filled in, because the #item^quantity data-field only contained three items.

{% hint style="danger" %}
Do not use repeating fields from multiple concepts in the same row, as this is ambiguous (you will get an error message about “multiple repeating-lists in the same row”). After all, which of the concepts data should then be used to calculate the number of rows?
{% endhint %}

## Layout settings

In the “Table Settings” of the [Base styling](/styling/base-styling.md) (which you can always add to a specific clause through the [custom styling](/files/custom-styling.md) option) you can specify various options for tables, such as a table’s alignment, width, borders, background and text flow.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.clause9.com/clauses/introduction-to-tables.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.