Sfairadora

  • Reference Guide

Table Manipulator

The table manipulator tool allows you to perform a particular one-time manipulation on all table rows (for example, you can add or modify values in a particular column based on a specified condition etc.). You can perform a manipulation either on the entire table row or selectively – on the cells of the active column or on selected columns. You can also specify whether the manipulation should affect only selected rows or all rows. The manipulation itself is specified by means of an Enki language expression.

Table to Be Manipulated

This section is used to specify which table and which of its rows and columns should be affected by the manipulation.
Item
Description
Use active table
The table that was active when the tool was opened is used. If no table was active, you can activate it afterwards. If there is no active table, the tool cannot be used.
Select table manually
The table is selected manually using the Object name of table and Data reference of table fields.
Active row/Selected rows
The manipulation is performed only on the active row or on all selected rows if there are some selected rows.
All rows
The manipulation is performed on all rows in the table.
Object name of table
If the Select table manually option is selected, you can specify here the name of the object in which the table is located. Typically you will need to select the master identifier referencing the document affected by the tool (i.e. the document that was active when the tool was activated).
If the Use active table option is selected, information about the used table is displayed.
Data reference of table
Reference to a table within the specified Object name of table.
Manipulation range
You can choose whether the manipulation expression applies to the entire table row or to the active column (or selected columns) only.
If the table is selected manually, the manipulation range is always the entire row because a manually selected table does not have active/selected columns.

Manipulation expression

The selection of data to be manipulated is followed by an area for the definition of the manipulation expression. The manipulation expression is evaluated sequentially for every designated table row. Data currently affected by the manipulation is represented by the x variable. If the manipulation range is set to all row, the x variable represents a structure corresponding to the entire row. The content of individual cells can be referenced by the dot notation. For example, a cell in the name column is referenced by the x.name expression. Insertion of column names is facilitated by the buttons to the right of the expression editor.
If the manipulation range is set to selected column, the x variable represents directly the current cell. If multiple columns are selected, the manipulation expression is called multiple times for every row, whereby x always represents one cell.

Execution of Manipulation and Saving Settings

Execution of the manipulation starts when you click the Execute button. Should the manipulation take more time, a window is displayed allowing you to pause it. If the manipulation is paused, the rows on which it has already been performed are modified whereas the remaining rows still contain the original values. In other words, the rows on which the manipulation has already been performed do not return to their original values.
The Save settings button creates a new tool in the current document, which is based on this general table manipulator tool, but its definition reflects the current settings. This way you can create specific tools for easy execution of frequent table operations.

Notes

When the table manipulator tool is displayed, values in the table cells should not be edited (i.e. the cursor should not blink) because the edited values would not reflect the modification applied to the actual data.
It may be more convenient in some situations to use a computed table column, which continuously reflects changes in the table, instead of a one-time table manipulation.

Examples

1.
Multiply the value in the active column by 10
Set the manipulation range to selected column and the manipulation expression to:
x = x * 10
or alternatively to
x *= 10
2.
Set the value of empty optional cells to 0
Set the manipulation range to selected column and the manipulation expression to:
if(~is_present(x))
x = 0
3.
Remove optional values
If an optional cells contains a 0 value, the value should be removed.
Set the manipulation range to selected column and the manipulation expression to:
if(is_present(x) & x==0)
remove_optional(x)
See the object manipulation functions.
4.
Make the values in one column depend on another column
If the performance column exceeds 100, the salary column should be increased by 15 %.
Set the manipulation range to all row and the manipulation expression to:
if(x.performance > 100)
x.salary *= 1.15
5.
Remove opening and closing quotation marks in a column of the String type
Set the manipulation range to selected column and the manipulation expression to:
if(prefix(x, 1) == "`"")
x = suffix(x, size(x)-1);
if(suffix(x, 1) == "`"")
x = prefix(x, size(x)-1);
See the string manipulation functions.