Dynamic Table

A Dynamic Table (previously also called a detail table) is an essential element in invoice templates. A Dynamic Table is different from a standard table in that it has a variable number of rows. In a Print context it will automatically overflow into as many pages as necessary to output all rows and it can display subtotals in its header and footer.

Dynamic Tables are only available if the loaded record set or data mapping configuration contains transactional data in one or more detail tables (see Loading data).
Depending on the data, a Dynamic Table can also contain data from nested detail tables.

Creating a Dynamic Table

To create a Dynamic Table:

1. Open the Insert Dynamic Table dialog. There are several ways to do that:

   • Drag the data field that contains the name of the detail table into the template.

   • On the menu select Insert > Table > Dynamic.

   • On the toolbar, click the Insert dynamic table button.

2. Enter the table's desired attributes:

   • ID: A unique identifier for the table. IDs are used to access the table from scripts and as CSS selectors for style rules.

   • Class: A class identifier for the table. Classes can be shared between elements and are used to access the table from scripts and as CSS selectors for style rules.

   • Detail Table: Use the drop-down to select which detail table will supply the data to display within the Dynamic Table.

   • Width: Enter the width of the table (e.g.

     100%

     ).

   • Use the Insertion Point drop-down to select where to insert the table.

     • At cursor position inserts it where the cursor is located in the template.
     • Before element inserts it before the HTML element in which the cursor is currently located. For example if the cursor is within a paragraph, the insertion point will be before the <p> tag.*
     • After start tag inserts it within the current HTML element, at the beginning, just after the start tag.*
     • Before end tag inserts it within the current HTML element, at the end, just before the end tag.*
     • After element inserts it after the element in which the cursor is currently located. For example if the cursor is within a paragraph, the insertion point will be after the end tag of the paragraph (</p>).*
     • Replace inserts it in place of the currently selected element. (This option is not available when inserting content in a Master Page.)

     * If the current element is located inside another element, use the Elements drop-down to select which element is used for the insertion location. The list displays every element in the breadcrumbs, from the current selection point down to the root of the body.

     Note: HTML has some restrictions as to which types of elements are allowed as children of other elements. For example, a paragraph element is not allowed to have children that are block level elements - like a Div or a Table. If inserting content at the selected location would produce invalid HTML the final result may be different than expected. For example, when you insert a Div into a paragraph, the paragraph gets split in two. This means you end up with two paragraphs with the Div in between.

3. Click Next. The Dynamic Table Builder appears.
   At this point the table has one row, which is based on the selected detail table. You can add, delete and reorder rows and fields.

    

   Fields - cells in the table - correspond to data fields in a (nested) detail table.

   • To add a field, select a data field from the drop-down next to the row's Add Field button. Or click the Add Field button itself to add an empty field.

     Empty fields are useful for positioning cells underneath each other to make them look like columns.

   • The Synchronize fields button refills a row with all the data fields of the detail table to which the row is associated.

   • Drag a field up or down to change the order of the cells in the table row.

   • Use the Format drop-down to select how the value must be formatted. Which options are available depends on the type of the data field (see Data types). For an explanation of the options see Formatting variable data.

   • Click the Left, Center or Right button to align the cell's content.
     The Text alignment mode determines how the cell's alignment will be added to the table:

     • Via inline styles: The text-alignment is set via the style attribute of the cells. This is also called local formatting. (See also: Styling and formatting.)

     • Use CSS utility classes: The cells get a class for which the default style sheet for Dynamic Tables (default_table_styles.css) has a style rule. For more information see Utility classes for text in a Dynamic Table.

   A row is associated with a (nested) detail table. The row will be repeated in the output (or in Preview mode) as many times as necessary to display all the records in the associated detail table.

   • To add a row, select a detail table from the drop-down next to the Add Row button at the top of the table. Or click the Add Row button itself to add an empty row.

     Multiple rows may be associated with the same detail table.

     Consecutive rows linked to the same detail table are treated as a group and repeated as such.

   • You can drag rows up or down to change the order in which they appear in the table.

   • By default, a row is repeated once for each record in the detail table, but in tables with several levels and long nested tables you may want an extra repetition of a row if its sub-table runs over multiple pages.
     
     In order to repeat a row before and/or after a page break:

     1. Add an extra row.
     2. Associate it with the detail table of which a row must be repeated in case its sub-table gets split over multiple pages.
     3. Change the Initial setting to Before a page break, After a page break, or before and after a page break (All). This button changes the data-show-row attribute of the row; see A Dynamic Table's data- attributes.
        Note that this button is only available if the row is followed by a nested table.
     4. Add fields as you like.
     
     Note that this extra row will only appear in the output in case there is a page break in its sub-table.

     A text like "continued on next page" or "continued from previous page" can be added after the table has been created. See Mixing text and data in one cell.

   • Activate the Header Row button to display a row with the names of the current row's data fields before each row in the output.
     The header row is not visible in the Wizard, but is inserted in the body of the table (the <tbody> element) when the Wizard is closed.
     In the output it will be repeated as many times as the current row. It has the same data-repeat attribute (see A Dynamic Table's data- attributes).
     Note that this button is only available if the row is followed by a nested table.

   The data field names of the row with the most fields will appear in the header (the <thead> element) of the Dyamic Table. If more rows have that same number of fields, the last one wins.

   The Initial and Header Row buttons are disabled on the row that provides the titles in the header.

4. Click Next and check Calculate Subtotals to enable the options for a (sub)total at the end, and (in Print sections) in the footer and/or header. The options are:

   • Field: Select the data field for which the subtotal must be calculated.
     

     The wizard only allows to add subtotals for fields in the detail table itself, not in any nested detail tables.
     However, it is also possible to add subtotals after the table has been inserted into the template, even for fields in nested detail tables. See Adding subtotals.

   • Show subtotal lines before page break: Check this option to display the subtotal in the footer of the table on each page (including at the end of the table).

   • Show subtotal lines after page break: Check this option to display the subtotal of the previous page in the header of the table on the next page.

   If neither of the latter two options has been enabled, the subtotal for the selected field will be put in the footer of the table and displayed only at the end of the table.

5. Click Next and select the desired table style. The top left option actually applies no styling to the table. The style can be easily changed afterwards; see Styling a Dynamic Table.

6. Check the option Allow Resizing to make it possible to change the width of columns in Design mode via drag-and-drop.

7. Check the option Hide when empty to make the table invisible when there are no data to display in it.

8. Click Finish to add the table to the section.

Changing cells in a Dynamic Table

The usual ways to mix data and text, such as drag-and-drop, generally don't work in Dynamic Table cells. To learn how to mix data and text in a Dynamic Table cell, see Mixing text and data in one cell.

Most properties of cells, such as which data field is linked to it and how the value is formatted, can be changed via the Attributes pane.

To personalize the content or style of cells, based on the value of a data field, you'll need a script. See Using scripts in Dynamic Tables.

Adding a row to the header or footer of a Dynamic Table

A Dynamic Table that is created by the Wizard always has a header (a <thead> element). It will also have a footer (a <tfoot> element) if you chose to add Subtotals.

Sometimes you may want to add more rows to the header or footer of a Dynamic Table, for example, to add taxes and/or the total of an invoice, or to add a custom message.

A header or footer row can be added to a Dynamic Table as follows.

1. In the workspace, open the Design tab.

2. If the table already has a header/footer:

   1. Right-click the header of the table if you want to add a header row, or the footer of the table if you want to add a footer row.

   2. On the shortcut menu select Row > Insert below or Insert above. The new row will be added to the header or footer.

   If the table doesn't have a header/footer, add it (see Adding a header or footer) and proceed with the next step.

   To determine if a table has a header and/or footer, expand the table on the Outline pane.

3. Select the new row (see Selecting an element).

4. On the Attributes pane, select one of the options from the Show Row drop-down that specifies whether the row must be repeated in the output. The options are:

   • All: The row will appear on all pages.

   • Before page break: The row will appear on all pages except the last.

   • After page break: The row will appear on all pages except the first.

   • At end of table: The row will only appear on the last page.

You can fill the new header or footer rows as usual. You could for example drag a root level data field to the row (see Variable Data) or type in the cells. See also: Mixing text and data in one cell.
You could also add a subtotal (see below).

Adding subtotals

When creating a Dynamic Table with the Wizard, you can add subtotals based on one data field to the table's footer and header. It is also possible to add (extra) subtotals to an existing Dynamic Table.

Subtotals are added by using the data-sum and data-show-row attributes, normally in the header and/or footer of the table.
Note that this requires the table to have the data-expander="2019" attribute. Tables created with the Dynamic Table Wizard that was introduced in version 2020.1 will get this attribute automatically.
For information about a Dynamic Table's attributes see A Dynamic Table's data- attributes.

To add subtotals to the header and/or footer:

1. In the workspace, open the Design tab.

2. If the table doesn't have a header/footer, add it (see Adding a header or footer). To determine if a table has a header and/or footer, expand the table on the Outline pane.

3. If you need an extra row in the header or footer:

   1. Right-click the header or the footer of the table, depending on where you want to add a row.

   2. On the shortcut menu, select Row > Insert below or Insert above.

4. Specify on which pages the row must appear in the output:

   1. Select the row to which you want to add a subtotal (see Selecting an element).

   2.  On the Attributes pane, select one of the options from the Show Row drop-down:

      • All: The row will appear on all pages.

      • Before page break (footer rows only): The row will appear on all pages except the last.

      • After page break (header rows only): The row will appear on all pages except the first.

      • At end of table: The row will only appear on the last page.

5. Now, add the subtotal to a cell in that row. This procedure is the same for subtotals in the header and footer.

   1. Select the cell (see Selecting an element).

   2. Select the data field:

      • On the Attributes pane, from the Sum drop-down, select the data field on which the subtotal must be based. The drop-down will offer all eligible fields, including those in nested detail tables.

      • Alternatively, e.g. to select a data field in a nested detail table, switch to Source view and manually add the data-sum attribute to the table cell (the <td> element).
        Its value should consist of the path to the data field. For example: <td data-sum="Instruments.Items.Amount">. This cell will have a subtotal based on the "Amount" field in the "Items" detail table which is nested in the "Instruments" detail table.

      1. You could also add text like "continued on next page" or "continued from previous page" to the cell. See Mixing text and data in one cell.

Subtotals inside a Dynamic Table

Subtotals normally appear in the header or footer of a table; however, it is also possible to insert subtotals in cells in the body of a table.

1. Start by adding a row to the body of the table: right-click a row in the table, depending on where you want to add a row, and select Row > Insert below or Insert above.
   

If the row should occur only once, you can now proceed with step 5 in Adding a row to the header or footer of a Dynamic Table.

If the row should occur as often as a certain detail table, it must be associated with that detail table first.

1. Select the row (see Selecting an element).
2. Change the row's Repeat attribute on the Attribute pane from None to the desired detail table. Usually this will be the detail table that is one level higher than the one that contains the field for which the subtotal must be calculated.
3. Proceed with step 5 in Adding a row to the header or footer of a Dynamic Table. The Sum drop-down will now only show the names of fields that occur in the specified detail table and in its nested detail tables.

Mixing text and data in one cell

By default, each Dynamic Table cell that is based on a data field shows a placeholder. For example: @CompanyName@ refers to a data field named CompanyName. However, unlike other placeholders, these placeholders are not used as selector.
Instead, if a cell has the data-field or data-sum attribute, the software will replace the entire contents of that cell that with a value: the current value of the data field, or a running total, respectively. (For information about data- attributes see: HTML: table element and data- attributes).
Any text that was added in Design mode will disappear.

In order to mix data and text in a cell, you should remove the data-field or data-sum attribute, respectively, from the cell itself and then put that attribute on an element inside the cell.
Here's how to do that.

1. In the Workspace, open the Design tab.

2. Select the cell (see Selecting an element).

3. On the Attributes pane, set Field or Sum to None.

4. Type text in the cell, before and/or after the placeholder.

5. Select the placeholder, right-click it and select Wrap in Span...

6. Select the new Span element.

7. On the Attributes pane, set Field or Sum to the desired data field.

8. Reapply the format if needed (see Formatting values in a Dynamic Table).

Changing content based on a value

Changing the contents of a cell or row in a Dynamic Table, based on the value of a data field, requires a script. See Using scripts in Dynamic Tables.

Formatting values in a Dynamic Table

Values in Dynamic Table cells can be formatted in different ways. A date value, for example, could be displayed as "Apr 2, 2016" (short date) or "4/2/16 12:00 AM" (medium date/time).

Which formats are possible depends on the data type of the field that the cell is associated to (see Data types)
For an explanation of the possible formats see Formatting variable data.

Selecting a format

The format of each value can be chosen when creating a table.
In an existing table you can change the formatting in two ways:

• Select the element that contains the value (i.e. a cell or a Span element) and then use the Format drop-down on the Attributes pane.

• Open the Source tab and manually add the desired format to the cell using the data-format attribute (see A Dynamic Table's data- attributes).

Hiding an empty Dynamic Table

The number of rows in a Dynamic Table is variable, as it depends on a detail table in the data.
You can hide a table that does not contain any data. There are two ways to achieve that.

• When creating a Dynamic Table, you can check the option Hide when empty. (See Creating a Dynamic Table.)

• For an existing Dynamic Table you can select the table (see Selecting an element) and check the option Hide when empty on the Attributes pane.

Hiding an empty table row

Empty rows are omitted from a Dynamic Table by default.
A row is considered empty if all elements with a data-field attribute in that row refer to empty data fields. Any additional text is not taken into account.

To keep empty rows visible in the output:

• Switch to Source view.

• Add the data-keep-when-empty attribute to the respective <tr> element(s). For example:
  <tr data-repeat="Instruments" data-keep-when-empty="">.

  To locate a row you can select it on the Outline pane.

Styling a Dynamic Table

The Insert Dynamic Table wizard lets you select a style for the table.

Tables are styled via CSS: when the wizard adds a Table, the chosen theme's class is added to the <table> element, and, if it doesn't exist yet, the default_table_styles.css file is added to the resources of the template. This CSS file contains the CSS rules for all table themes. (See: Styling templates with CSS files.)

To change the theme, you could simply select the table and change its class on the Attributes pane.
The available theme classes are: table--grid, table--colgrid, table--minimalist, table--dark, table--light, table--striped, table--topbar, table--portfolio. (Note the double dash in the class name.)

The default_table_styles.css file is read-only, but of course you could overwrite styles and create your own theme, using your own style sheets.
Regardless, you can change the font, font size and color, the borders, the cell padding (the distance between the edge of the cell and its content), and the background color or image of the table and its cells, via the Formatting dialog.

Both approaches are explained in the topic: Styling a table.

Dynamic Tables are best styled via CSS (see Via a style sheet), for two reasons:

• With local formatting, all rows that are added on the fly (in Preview mode and in output) will look exactly the same as the first one. Alternating row colors, for example, in dynamically added rows can only be done via CSS.

• When generating output from a template, a Dynamic Table is created slightly faster when it's styled via Cascading Style Sheets than when it's styled with local formatting.

Here are a few tips on how to target rows and cells in a Dynamic Table.

• There are CSS selectors with which you can target every so-maniest row (see Styling the first, last and nth rows).

• In the output, Dynamic Table rows are repeated including any classes that are set on the row and on its contents.

• Dynamic Tables and their rows and cells have some special attributes that can be used as selector. See: A Dynamic Table's data- attributes.

Utility classes for text in a Dynamic Table

In order to style text in a Dynamic Table, you could use some classes for which there are style rules in the default style sheet for Dynamic Tables (default_table_styles.css). The classes are:

• .u-text-left

• .u-text-center

• .u-text-right

• .u-text-bold

• .u-text-normal

• .u-text-italic

These classes will be applied when you choose Use CSS utility classes as Text Alignment mode when creating a table. To change the alignment after the table has been created, select the cell (see Selecting an element) and then type the desired class in the Attributes pane.

Note that if you selected Via inline styles as Text Alignment mode when creating the table, the utility classes won't work, unless you remove the inline style first. Inline styles always get applied since they are more specific. (For an explanation see Using a more specific CSS rule.)

Changing styles based on a data field value

Changing the styles of a row or cell in a Dynamic Table, based on the value of a data field, requires a script. See Using scripts in Dynamic Tables.

Resizing a Dynamic Table

To change the width of a Dynamic Table or of a column in a Dynamic Table, select it (see Selecting an element) and type the desired width as a percentage in the respective field on the Attributes pane.
It is also possible to resize colums via drag-and-drop (in Design mode only). To allow for this, select the table and check the option Allow Resizing on the Attributes pane.

The height of the Dynamic Table is adjusted automatically to the amount of data added to it in Preview mode or when generating output.
It is however possible to change the height of the rows: click in the row and type the desired height in the respective field on the Attributes pane. All line item rows will have the same height.

Adding leading and trailing space to a Dynamic Table

The best way to add extra space at the top or bottom of a Dynamic Table is to set the Table's top or bottom margin, respectively (see Styling a table).
Do not use empty lines (<br>) or paragraphs (<p>) to add trailing space to a table. In Print output they might end up on a next page without any other visible content, which would still be printed because lines and paragraphs must be treated as content, even when they are empty.

HTML: table element and data- attributes

In HTML, a Dynamic Table is a normal <table> element with rows and cells (see HTML element: table). But apart from the native attributes of a table, rows and cells, it has some proprietary data- attributes which make it dynamic.

These data- attributes are set automatically on a new table that is made with the Dynamic Table Wizard that was introduced in version 2020.1.
They can be changed via the Attributes pane, depending on which element is selected (see Selecting an element), or directly in the template's HTML via the Source tab.

For a list of all data- attributes that can be used in a Dynamic Table, see A Dynamic Table's data- attributes.