Dynamic Rows

The Dynamic Rows type adds a table to the form where the user adds rows, such as order items, equipment or travel expenses. You define the columns, their types and behaviour in JSON, and the row calculations (products, sums, hiding columns) in a script. You set it up in the variable editor (Templates › template › Variables › variable). The shared part of the editor is described in the article Variables: overview and common settings.

Dynamic rows are a tool for consultants and template authors who know JSON and basic JavaScript.

Dynamic rows editor

When you select the Dynamic Rows type, a full-width Dynamic Rows section appears below the basic information. You do not enter the default value in a field. Instead, you fill in the preview.

No.ElementPurpose
1ScriptJavaScript code editor that controls cell values and behaviour. It highlights syntax, offers autocompletion and underlines errors.
2HelpOpens the dynamic rows help: table and column properties, script methods with examples and a complete sample definition. The definition has the same button.
3Insert snippetMenu of ready-made code snippets that are inserted at the cursor position. You can search the menu.
4Full screenOpens the editor in a full-screen window.
5Table and column definitionJSON with the table properties (table) and the list of columns (columns). It has its own help, snippets and full screen. When you leave the editor, the preview refreshes automatically.
6PreviewThe table as the user will see it. The rows you fill in the preview are saved as the default value of the variable.
7RefreshRebuilds the preview from the current definition and script.

In the example, the Equipment list table has the columns Item (selection from fixed options), Quantity, Unit price, Total and Note. The script calculates the Total column as the product of quantity and price:

this.value('total', null, function (t, i) {
  var q = t['quantity'][i].getValue();
  var p = t['unitPrice'][i].getValue();
  return q && p ? q * p : null;
});

Snippets

MethodPurpose
this.valueSets the value of a cell or cells, typically a column calculation.
this.taskChanges the appearance (styles) of a cell or cells.
this.changeDefChanges the table definition at runtime, for example hides a column or makes it read-only.
this.changeFormComponentsSets the value of another variable in the task form, for example a sum into a number variable.
this.formComponentsStyleChanges the style of another variable in the form, mainly to hide it.
this.insertHtml and this.valueHtmlInserts custom HTML below the table (for example total fields) and sets its value.
this.changeCellChanges cell properties, for example whether it is mandatory or valid.
this.getDynTableLoads the values of a dynamic table column for use in the script.
this.deleteRowDeletes a row.
this.handleErrorsReports errors in the form and prevents the task from being completed until they are fixed.

Table definition

Main table properties (table):

PropertyMeaning
showTotalsTotals row below the table. Default: yes.
showAddRemove, showAdd, showRemove, showClone, showRemoveAllWhether the user can add, delete and copy rows, and delete all rows at once. Adding, deleting and copying are allowed by default, deleting all rows is not.
isDraggableReordering rows by dragging. Default: yes.
watchVariablesTask variables whose change triggers a script recalculation. The variables must be assigned to the task as writable.
runCondsOnChange, runAfterConds, attachScriptToCondsRelationship to the task's dynamic conditions: re-evaluating the conditions after a change in the table, running the script only after the conditions, or controlling the table only from dynamic conditions.
resizable, minColWidth, sideResizing column widths with a horizontal scrollbar, minimum column width and table placement.

Main column properties (columns): name (name for the script), type (DL, SL, currency, number, percentage, date, text, textarea, file, checkbox), caption and translations (header and its translations), value (default cell value), duty (writeable, mandatory, readonly, cond-mandatory), choices (options for SL), dataUrl, urlFilter and dataStructure (data source for DL), nrOfDecimals, thCss and css (width and appearance). The full list with examples is in the editor help.

Invalid JSON is not saved
If the table definition is not valid JSON, saving ends with the message “Not valid JSON!” and the variable is not saved. When the table has attachScriptToConds: true set, the script is read-only, because the table is controlled by the task's dynamic conditions.

Extended example: order items

The sample template “TAS | Purchase Order 5.19” uses dynamic rows for order items. The script sets units of measure and VAT rates according to the language and calculates prices excluding and including VAT, the definition watches the purchase type and cost centre variables (watchVariables), and the columns have header translations.

How it looks in the form

The user selects an item and enters the quantity and price. The Total column is calculated by the script and is read-only. The plus icon below the table adds a row. Depending on the table definition, the user can also delete, copy and reorder rows by dragging. The Equipment list table has the totals row turned off (showTotals: false).

Related: Variables: overview and common settings, Dynamic Table, Task dynamic conditions.

Lists (texts, numbers, dates)

Date
Syca (opens in a new tab)

Powered by HelpDocs (opens in a new tab)