Table builder
Apps · Table Builder
Preview grid data, choose the columns people need, and add buttons, badges, and workflow actions.
The table builder is a panel in the app designer for one grid of a form. It shows a sample of the data the grid's table delivers, one row per column, with how well each column is filled and example values. Use it to choose which columns the grid shows, to name and size them, and to add special columns such as buttons and badges. The grid in the form updates as you make each change.
The table builder works on the same columns as the Table tab, so changes in one are shown in the other. It works together with the form builder: a button column can open a modal that you build in the form builder, and you can edit what a button does there.
The table builder only makes changes in Design mode. In Run mode you can still look at the data, but you cannot change the columns. Changes are kept in the app as soon as you make them; select Save in the app designer to store the app.
Open the table builderDirect link to Open the table builder
Open an app in the app designer, select Design, and use one of these:
| From | How |
|---|---|
| Table tab | Select a grid in the form, open the Table tab, and select Builder next to Columns:. |
| A grid in the form | In Design mode, click a column of a grid in the form. The table builder opens on that grid with the column selected. If you click the button or badge of a special column, its settings open as well. |
| The form builder | Select an item that contains a grid and select Table builder. |
| The title bar of the form builder | When the form builder shows a modal that is opened from a grid column, select the link in its title bar to go back to the table builder on that grid. |
The table builder stays on the grid it was opened for. Selecting another item in the form does not change it. To work on another grid, open the table builder from that grid.
The panelDirect link to The panel
Title barDirect link to Title bar
The title bar shows Table builder – followed by the name of the table, and the view when the grid has views. While you edit a special column, it also shows the name and kind of that column. On the right, it shows how many columns the grid shows, for example 5 of 23 columns shown.
When the grid is on another form than the one the designer shows (for example, while you build a modal in the form builder), the title bar says grid on form <name> – click to show. Click anywhere on the panel to show that form again. The table builder keeps working on the grid either way.
Position and sizeDirect link to Position and size
| Button | What it does |
|---|---|
| Show only the row of this grid in the form | Hides the other rows of the form, so that only the grid is shown. Select it again to show the whole form. |
| Dock at the bottom | Docks the panel at the bottom of the window; the form moves up to make room. Ctrl+click docks it at the top. |
| Dock at the right | Docks the panel at the right of the window; the form moves left. Ctrl+click docks it at the left. |
| Float over the form | The panel floats over the form. Drag the title bar to move it. |
| Full height | While floating, the panel takes the full height of the window. You can also double-click the title bar. Select it again to return to the previous height. |
| Fill the whole window | The panel fills the window. Select it again to return to the size and place it had. |
| Close | Closes the table builder. |
When the panel is docked, drag its inner edge to resize it. Only one builder can be docked at each side of the window: if the form builder is docked on the side you choose, it starts to float. When you open or dock the table builder, the form scrolls so that the grid is in view.
The toolbarDirect link to The toolbar
| Option | What it does |
|---|---|
| Columns / Rows | Columns shows one row per column of the table, to choose and configure them. Rows shows the sample rows as a grid. See Preview the rows. |
| Explore / Configure | Decides which properties come first when the panel is too narrow to show all of them. Explore puts what a column holds first (Kind, Filled, Unique, Value), for choosing columns. Configure puts the settings first (Display name, Variable, Width, Key), for setting up the columns you chose. The builder remembers your choice. When a grid shows no columns yet, or when you open the builder from the form builder, it starts with Explore. |
| Properties | Chooses which properties of each column the list shows: Kind, Filled, Unique, Value, Description, Display name, Width, Key, Variable, No resize, and Empty header. Use all or none to change them all at once. A property you switch on is shown even when there is little room. A property that is allowed but has no room right now is dimmed; switch it off and on to force it. The builder remembers your choice in this browser. |
| Refresh | Fetches the sample rows again. |
| Fit widths | Sets the width of every shown data column from its sample values. |
| value arrows | Steps through the distinct values that the Value column shows. The label between the arrows shows which values you see, for example 2-4 of 17. |
| Status | On the right: sample of 200 rows (of 1500), or loading…, or an error message. |
The sampleDirect link to The sample
The table builder fetches up to 200 rows of the table as a sample. All statistics and example values come from these rows. When the table has parameters, the sample uses the values that the bound variables have in the designer (on the Variables tab), or the fixed values of the parameters.
Choose and configure columnsDirect link to Choose and configure columns
In Columns mode, the list has one row per column of the table. The columns of the list are:
| Column | What it shows or sets |
|---|---|
| Check box | Whether the grid shows the column. The check box in the header shows or hides every column. When you show a column that still has the default width, the builder sets its width from the sample values. |
| Column | The name of the column. Drag a row to change the order of the columns in the grid. You can rename a special column or a bar column by clicking its name; actions bound to a click on the column follow the new name. Hover over the name to see the description of the column. |
| Kind | The data type of a data column, or JavaScript or bar for a generated column. |
| Filled | The share of the sample rows in which the column has a value. Hover to see the numbers. |
| Unique | The number of distinct values in the sample rows. |
| Value | Example values from the sample rows. Use the value arrows in the toolbar to step through them. Hover to see a list of all distinct values. |
| Description | What the column holds, when the table describes it. |
| Display name | The header shown in the grid. |
| Variable | The app variable that the selected row of the grid writes this column to. Type a name; a variable that the app does not have yet is created. |
| Width | The width of the column in pixels. |
| Key | The column that identifies a row. A table has one key column; selecting another clears the previous one. Only for data columns. |
| No resize | The user cannot resize the column in the grid. |
| Empty header | The header of the column shows no title, sort, or menu button, and the column cannot be sorted. |
The buttons at the end of each row are:
- Edit the template settings: opens the settings of a special column. See Add a special column.
- Edit the script: opens the script editor for a generated column.
- Remove the column: removes a generated column, together with the actions bound to a click on it. Data columns of the table cannot be removed; hide them with the check box instead.
Preview the rowsDirect link to Preview the rows
Select Rows to see the sample rows as a grid, with the data columns of the table. Columns that the grid does not show are dimmed. You can sort, filter, and resize the columns of this preview; that does not change the grid in the form.
Add a special columnDirect link to Add a special column
Special columns are generated columns that you set up with a few settings instead of a script. At the bottom of the panel:
- Pick a kind under Special column.
- Select Add column….
The new column is added to the grid right away, so you see it in the form while you set it up. Every change in the settings shows in the form immediately. When a setting is missing or wrong, a message under the settings says what to fix, and the form keeps showing the last valid version.
- Save keeps the column with these settings. For a new column, it also binds the variables and adds the click actions that the kind of column needs. A * on the button means there are changes that are not saved yet. You can open the settings again later with Edit the template settings.
- Cancel removes a new column again, or puts an existing column back the way it was. Actions bound to an existing column stay as they are.
If you close the table builder, open another column, or switch to another grid while the settings are open, the builder saves them when they are valid and cancels them otherwise. Switching the app to Run mode cancels them.
If you change the script of a special column on the Table tab, the column is no longer linked to its settings, and you can no longer edit it with Edit the template settings. The Studio asks you to confirm before it does this.
The kinds of special columns are:
| Kind | Available for | What it shows |
|---|---|---|
| Button | Every table | A button in every row, or only in some rows. Its text, color, and icon are fixed, come from a column, or depend on the row. |
| Badge | Every table | The value of a column as a colored label. Empty values show nothing. |
| Mapped badge | Every table | A label whose text, color, and icon are decided by rules on the row, for example the status of a case as running, stuck, or completed, each in its own color. |
| Workflow: open step | The workflow.my_tasks table | A button that opens the app of a work item. |
| Workflow: approve | The workflow.my_tasks table | A button that completes a step with its positive outcome. |
| Workflow: reject | The workflow.my_tasks table | A button that completes a step with its negative outcome, or first opens a form. |
| Workflow: send message | The workflow.my_tasks and workflow.my_cases tables | A button that sends a workflow message, such as a withdrawal. |
ButtonDirect link to Button
First choose the kind of button:
- Same on every row: one text, color, and icon for every row.
- Text from a column: the button shows a value of the row.
- Depends on the row: text, color, icon, and click event are decided by rules. See Rules.
Then fill in the settings. Which settings you see depends on the kind of button.
Column
| Setting | Description |
|---|---|
| Column name | The name of the column. Required. You can only change it while the column is new; rename an existing column in the Column column of the list. |
| Header | The header shown above the column. |
| Button width | fit the text, or fill the column. |
Button (not for Depends on the row)
| Setting | Description |
|---|---|
| Text column | For Text from a column: the column whose value the button shows. Required. |
| Button text / Text when empty | For Same on every row: the text of the button (required). For Text from a column: the text when the column has no value. |
| Color | The color of the button. |
| Icon | An icon in front of the text. Select the button to pick one, or the cross to remove it. |
Click (not for Depends on the row)
| Setting | Description |
|---|---|
| Click event | The name of the click event that the button raises. Leave it empty to use the plain click on the column. A named event is an event of its own on the Actions tab, so several buttons in one column can do different things. If you rename the event, the actions bound to it follow. |
| Does | What a click on the button does. Select it to edit the actions of the click in the form builder. The column is saved first. |
| Show when | In which rows the button is shown: always, column not empty (when a column has a value), column equals value (when a column has a specific value), or expression (when a JavaScript expression on the row is true). |
| Condition column | For column not empty and column equals value: the column to check. Required. |
| Condition value | For column equals value: the value to compare with. The list offers values from the sample. |
| Expression | For expression: the condition. Select Edit to write it in the script editor, where you can insert the columns of the row and the app variables. A row for which the expression fails does not show the button. |
Preview shows the button as the grid will show it, and in which rows it is shown.
The modal a click opens
Next to Save and Cancel, a button column has a list of modals and a button to build one:
- Pick new modal, or one of the modals of the app. When the button already opens a modal, it is marked (opens now).
- Opens modal… saves the column, lets a click on the button open the modal you picked (or a new one), and opens that modal in the form builder in the place of the table builder. If the button opened another modal before, it now opens only the new one.
- Edit modal is shown instead when you picked the modal that the button already opens. It saves the column and opens the modal in the form builder.
Hold Ctrl (Cmd on a Mac) while you select either button to open the form builder next to the table builder instead. The title bar of the form builder links back to this column. See the form builder for how it helps you build a modal for a grid row.
BadgeDirect link to Badge
| Setting | Description |
|---|---|
| Column name | The name of the column. Required. |
| Header | The header shown above the column. |
| Value column | The column whose value the badge shows. Required. |
| Color | The color of the badge. |
Mapped badgeDirect link to Mapped badge
| Setting | Description |
|---|---|
| Column name | The name of the column. Required. |
| Header | The header shown above the column. |
| Value shown by rules without text | Shown when a rule has no text of its own: the column whose value such a rule shows, for example for Otherwise. |
| Badge width | fit the text, all equal (longest text), or fill the column. |
The text, color, and icon of the badge are decided by rules. A rule without a color shows plain text instead of a badge.
RulesDirect link to Rules
A button that Depends on the row and a Mapped badge use rules. For each row, the first rule whose condition holds decides what the row shows. A row for which no rule holds shows nothing, unless there is an Otherwise rule.
Above the rules:
- Fill from sample: pick a column first, then select this to add a rule column equals value for every distinct value of that column in the sample.
- + Rule: adds an empty rule.
- + Otherwise: adds the last rule, which holds for every row that no rule above holds for. A list has at most one.
The rules grid has these columns:
| Column | Description |
|---|---|
| When | The condition, in words. Select the row to edit it below the grid. Drag a row to change the order. |
| Text | What is shown. When it is empty, the rule shows the value of the column its first equals part reads. |
| Color | A color of the theme. |
| Icon | Click the cell to pick an icon, or none. |
| Event | Buttons only. The name of the click event the button raises when this rule holds. Leave it empty for the plain click on the column. Each name is an event of its own on the Actions tab. |
| Does | Buttons only. What a click on the button of this rule does. Click the cell to edit the actions in the form builder. |
| Preview | The button or badge as the grid shows it. |
The last column removes the rule.
Edit a condition
Select a rule to edit its condition below the grid. A condition is one or more parts, joined by and. Each part has:
- A column of the row.
- A comparison: equals, not equals, is empty, is not empty, exists, not exists, contains, or starts with. exists holds when the column has a value; is empty and is not empty look at the text of the value.
- For comparisons that need one: value with a fixed value (the list offers values from the sample), or variable with an app variable.
Use + and to add a part, and the cross to remove one. Select advanced to decide with a JavaScript expression instead; Edit expression opens it in the script editor, and back to clauses returns to parts (the expression is dropped). For the Otherwise rule, select give it a condition to turn it into an ordinary rule.
Below the rules, two reference lists help you write conditions: the columns of the table with up to three Example values from the sample, and the app variables with their Current value in the designer.
Workflow columnsDirect link to Workflow columns
The workflow columns are buttons for task lists built on the workflow.my_tasks table (and, for Workflow: send message, the workflow.my_cases table). When you save one, the builder binds the listed table columns to the variables you name, and adds the actions that the button runs.
| Setting | Description |
|---|---|
| Column name | The name of the column. Required. |
| Header | The header shown above the column. |
| Button text | Workflow: open step and Workflow: send message only. The text of the button. Required. |
| Color | The color of the button. |
| Work item variable | The variable that the column work_item_id writes. Required. |
| Outcome variable | Workflow: approve and Workflow: reject only. The variable that the column outcome_positive (approve) or outcome_negative (reject) writes. Required. |
| Subject variable | Workflow: approve only, optional. The variable that the column subject writes, used in the message shown after approving. |
| Navigate to form | Workflow: reject only, optional. A form to open first, for example to ask for a reason. Leave it empty to complete the step directly. |
What each button does:
- Workflow: open step: shown on the rows of steps that are performed in an app. A click opens that app for the work item.
- Workflow: approve: shown on the rows of steps that are decided from the list, labeled with the positive outcome of the row. A click completes the step with that outcome and refreshes the form.
- Workflow: reject: shown on the rows that have a negative outcome, labeled with that outcome. A click completes the step with it and refreshes the form, or opens the form you chose under Navigate to form.
- Workflow: send message: shown on the rows that are messages, such as a withdrawal. A click sends the message and refreshes the form. On workflow.my_cases, it is the withdrawal that the initiator of the case can send.