Skip to main content

Table

A table is used to load, visualize, and interact with large datasets from your datastores.

Add data to a table

The data passed to a table component for visualization must be formatted as an array of objects, e.g.:

[
{
"city": "Toronto",
"population": 2930000,
"country": "Canada"
},
{
"city": "New York",
"population": 8419000,
"country": "USA"
}
]

If objects have fewer elements (key-value pairs) than other objects, the corresponding column in the table for this object and element remains empty.

Example

Start by dragging the Table component from the Components panel to the empty canvas.

A Table component was selected from the component panel

The table will load with an example dataset.

The Table visualizes a example dataset when added to the Canvas

To populate the table from a database, you can use the API builder. A Superblocks API is a structured way to query across any datastores (Databases, Cloud Data Warehouse, Internal REST APIs, Spreadsheets, and more), merge the data, and load it in a UI component.

Click Add Backend API in the bottom panel and click on [Demo] Orders to create an API that uses the [Demo] Orders Postgres Database.

A PostgreSQL step was added to a new Backend API

Use API1 to write a SQL query that fetches all the orders from the orders table in the demo database.

SELECT *
FROM orders
A PostgreSQL Step was added to a Backend API

Click the Run API button to execute the API, which will run the query and post the execution result below.

The Backend API was executed to get the results from PostgreSQL

Finally, since we are using API1 to query all our Orders, let’s rename API1 to getOrders.

Rename API

Click on the table to open the Properties panel. The Properties panel allows you to configure components by changing their UI design, adding event triggers, and most importantly, connecting API responses to UI elements.

To display the results from the getOrders backend API in the table component in the application's frontend, use frontend bindings and replace the example JSON with {{getOrders.response}} in the Table Data field using the autocomplete:

Add table data and rename table

Edit table data

The data in a table can be edited by the user directly in the frontend of an application. The user can update existing rows, insert new rows, and/or delete existing rows.

Define the editing type

When a column is set to be editable, the method of editing is determined by the column's formatting. For example, if a column is formatted as a date, a date picker will appear when the user intends to modify a value.

This behavior can be modified by configuring the Editing Type within the Column Properties. For instance, the editing type of a date column can be configured as Text, enabling the user to modify the date as text rather than selecting a new date using a date picker.

The following options are available for selection: Text, Number, Email, Date Picker, Dropdown, Checkbox.

A user defines a table column's editing type.

Editing type Dropdown

Dropdowns can be added to Table Components by selecting the Editing Type as Dropdown. The Options setting expects an array of objects within frontend bindings [{},{}]. For example, by copying and pasting the following into Options, you can create a Dropdown with two selectable values:

{{
[
{
"label": "New York",
"value": "NEW YORK"
},
{
"label": "Toronto",
"value": "TORONTO"
}
]
}}
Using the editing type Dropdown for a table column.

Update existing rows

To make individual columns editable by the user, click on the table component to open the properties panel. In the Columns section, set a check mark for each column that should be editable:

Make table columns editable from the properties panel

If a user hovers over a cell that is editable, it will be colored gray to indicate that the data can be edited. By double-clicking a cell, the user switches to edit mode. After a change has been made, it can be confirmed by pressing the Enter key:

Hover over a cell and double-click to edit a cell

In the following example, the value Billie Eilish was changed to Julia. The fact that the cell value has been edited is indicated by a blue marker at the upper left corner of the cell.

Insert new rows

To allow new rows to be inserted by the user, click on the table component to open the properties panel. Toggle on "Enable row insertion".

Enable row insertion from the properties panel

When row insertion is enabled, new rows can be added by clicking the "+" button in the table footer. An empty row is added to the bottom of the table, and the user can edit each cell in the newly inserted row.

Columns in inserted rows can be edited

Additionally, if you click into the ... menu on the right side of a row, you can select from the dropdown menu to Insert Row Above, Insert Row Below, or Duplicate Row. Insert Row Above/Below will place a blank row above or below the currently selected row. Duplicate Row will add a row below the currently selected row and will auto-fill the same data as the selected row.

Insert row above, below or duplicate

Delete rows

To allow rows to be deleted by the user, click on the table component to open the properties panel. Toggle on "Enable row deletion".

Enable row deletion from the properties panel

When row deletion is enabled, the user can mark a row to delete by hovering over it to reveal a context menu and then selecting the "Delete row" option.

One or more rows can be marked for deletion

Save edited data

When any change to the table data is made, the user has the possibility to either save the changes or cancel the changes by clicking on the buttons displayed at the bottom of the table:

Click on Save changes or Cancel to call the event handlers

The click of the buttons triggers a frontend event which can be reacted to with the help of event handlers. When the user clicks on Save 3 changes the onSaveChanges event handler is called and when the user clicks on Cancel, the onCancelChanges event handler is called.

Define what Action should be triggered by the event handler

Using the event handlers, any action type can be triggered in reaction of the changes. For example, the Run API Action Trigger can be used to save the changes the user made to the table to a database.

In the following example the Show Alert Action Type was triggered that displays a message of type success on the screen:

info

Note that the changes made by the user in the table have been undone at the moment the user clicked on Save 1 Changes. See below on how to permanently save the edited data.

The event handler has triggered a show alert action

While the user is editing the table data, the changes are stored in the local browser storage and will be removed as soon as the user clicks on either Cancel or on Save Changes as the Table Components reloads the data from the original data source.

info

If no onSaveChanges action handler is defined or if the save action handler fails, e.g. because an API triggers an error, the changes are not removed.

To store the changes permanently, and to retain the changes in the frontend table component after saving, the edited data must be written back to the backend data source.

success

Superblocks supports an easy to use Table bulk insert, update and delete SQL form that allows users to updated their SQL-type databases with edited data from frontend Table components.

There are three types of supported Reference Properties for the table component that let you access the edited data: Table1.editedRows, Table1.allEdits, Table1.currentEditValue.

In the example below frontend bindings were used to access the Table1.editedRows property from the onSaveChanges event handler. The event handler is called when user clicks on the Save Changes button:

Access the edited table data from a reference property

Table1.editedRows returns an object containing the inserted and deleted rows, as well as the updated and original values of all modified rows in the table. The updatedRows property can be used to write the edited data to a database and to save the changes permanently:

{
"insertedRows": [
{
"name":"Rihanna",
"twitter":"https://twitte.com/rihanna",
...
}
],
"deletedRows": [
{
"name":"Thom Yorke",
"twitter":"https://twitter.com/thomyorke",
...
}
],
"originalRows":[
{
"name":"Billie Eilish",
"twitter":"https://twitter.com/billieeilish",
...
}
],
"updatedRows":[
{
"name":"Julia",
"twitter":"https://twitter.com/billieeilish",
...
}
]
}

Columns

Rearrange and hide columns

To move the user_id column to be next to the user_email column, click on the table component to open the Properties panel on the right side of the screen and drag the user_id column to be right above user_email.

Reorder columns

To show/hide columns, click on the table component to open the Properties panel and then click on the visibility icon in the Columns section next to show or hide columns:

Hide a column

Freeze columns

To freeze/unfreeze columns, click on the down arrow in the column header to open the column properties panel, then select Freeze/Unfreeze Column. Now you can scroll the table sideways and the frozen column will stay pinned to the left side of the table.

info

Freezing columns from the column headers do not persist beyond the length of the specific user's session. If the application is refreshed, the frozen columns will reset back to the Table's default configuration. In order to freeze a column by default, enable Freeze Column in the Column Properties.

Freeze a column

Format table columns

To add formatting on columns (e.g. convert an image URL to display an image), click on a column in the properties panel, which opens the column properties menu. Use the Column Type dropdown to configure the columns type as Number, Currency, Date, Image, Video, Button, Link, and more:

Change column type example

Next, let's organize the data better by adding Tags. A special column type Tags can be added to all columns that contain a list of strings as their value (e.g. ['foo', 'bar']). Make the following change to the Tags column in Table1:

  • Tags > Column Type > Tags

Change column type to tags

Other column properties

This section is a compilation of table column properties that are explained in other parts of the documentation, providing a better contextual fit:

  1. Define the editing type of a column that is editable

Trigger actions on row click

Table rows can trigger actions when clicked. You can use the Slideout component to display the order details when any row in the table is clicked. You can do this in two simple steps:

  1. Open a slideout component when the onRowClicked event is triggered
  2. Populate the slideout with order details from a selected row using {{Table1.selectedRow}}

To open a slideout component every time you click on a row, go to Properties panel > click on the onRowClicked field > choose Open/close Slideout as the Action Type and select New Slideout as the slideout panel to open.

Open slideout onRowClicked

You can reference the selected row’s data from any component or API. For example, drag an image component to Slideout1 > set the Image URL to {{Table1.selectedRow.image}}.

Reference selected row from slideout

You can modify the code block to access any value from the table, e.g. {{Table1.selectedRow.price}} to give you the price of the selected row’s order, {{Table1.selectedRow.user_email}} will give you the email of the customer and so on.

When you click another row in the table, the slideout should automatically display that row’s order details.

info

Slideout Navigation: The Slideout component is hidden from the canvas because it only opens when an event is triggered. One way to open and edit event-based components like the slideout panel is to click on Navigation > Slideout1.

Open slideout from navigation panel

Add action buttons

Let’s say you want to add an action button to the Orders table that allows you to refund an order quickly. First, add a new column from the properties panel of the table component by clicking in the plus-icon in the Columns section, then name the column Refund. Next, change the Column Type to Button.

Add a button component to each table row

Choose Run API as the Action Type for the onClick trigger. Then add a new API that uses the REST API integration. We will use this API to call an internal API that refunds an order.

Run a backend API on button click

The internal API takes an Order ID alongside other fields of an order to process a refund. You can access the selected row’s fields such as an Order ID from an API with {{Table1.selectedRow.id}}.

Reference a selected row in an API call

info

This is not a real API from Superblocks, only for illustration

Table Properties

Component Properties

PropertyDescription
Table HeaderSet the table title
Table DataTakes in an array of objects to display rows in the table
Table Row DensitySelect table view density: Extra Small, Small, Medium, or Large
Enable Row InsertionAllow users to insert new rows into the table
Enable Row DeletionAllow users to delete rows from the table
Show Column BordersShow lines in table to divide columns
ColumnsAdjust how the columns display
Enable Multi Row SelectionAllows user to select multiple rows when enabled
Default Selected RowIndex of the row to select and highlight by default (starts at 0)
Enable SearchToggle the search bar on the table on/off
Default Table SortAllows specifying the sort options that will be used on page load
Default Search TextSet the default text to appear within the search bar
Search Placeholder TextSet the placeholder text to appear within the search bar when empty
Enable FilteringToggle per column filtering on/off
Default FiltersAllows specifying the filters that will be used on page load
Enable CSV DownloadToggle visibility of the data download
VisibleToggle the visibility of the table component
Loading AnimationControls the loading state of the component, values are a boolean
Pagination TypeSelect the pagination type: None, Client Side, or Server Side
Text SizeSelect the size of the text: Heading 1, Heading 2, Heading 3, Paragraph, or Paragraph 2
Max lines for wrappingMaximum number of lines a row can take up when a column has Text Wrap enabled

Settable Properties

Property Via Form / Via RunJSTypeExample Value
Selected Row / selectedRowIndexnumber0
Selected Rows / selectedRowIndicesArray<number>[0, 1]
Filters / filters{"byColumn": Object}{"byColumn": {"name": {"condition": {"type": "textStartsWith", "param": "b"}}}}. Note: The Value must be wrapped in bindings.
Search Text / searchTextstring"Search value"
Page Number / pageNonumber2
Hidden Columns / hiddenColumnsArray<string>["name", "date"]

Reference Properties

Properties can be accessed from other frontend components and backend APIs by adding the name of the Table, and dot referencing the property. For a Table named Table1:

PropertyDescription
Table1.selectedRow.<KEY>Access data from the selected row, for example Table1.selectedRow.product
Table1.tableDataAccess data from the table
Table1.filteredTableDataAccess data from the table preserving column ordering and filtering
Table1.selectedRowIndexAccess the index of the selected row, returned as a number, the first row starts at 0
Table1.filtersAccess the filters object for the currently selected filters on the table
Table1.isVisibleReturns the boolean value of the table's visibility (True, if it is visible)
Table1.pageNoAccess the table's current page number
Table1.pageSizeAccess the table's current number of rows per page
Table1.searchTextAccess the table's current inputted search text
Table1.selectedRowsAccess the selected rows as an array
Table1.editedRowsReturns an object containing the inserted, deleted, and modified rows in the table
Table1.allEditsReturns an array containing all table data with edits, insertions, and deletions
Table1.currentEditValueReturns a string containing the cell value of the in-progress edit (loses context when cell is unfocused by the user)

Default Filters

You can also set default filters for your table. In order to use these filter conditions by default, follow this format:

{
"byColumn": {
"<COLUMN_NAME>": {
"condition":
"type": "<CONDITION_TYPE>",
"param": "<PARAM_VALUE>"
}
}
}
}

For example, this is how the following code snippet would look within your application:

{
"byColumn": {
"user_email": {
"condition": {
"type": "textContains",
"param": "gmail"
}
}
}
}

Filter by condition

Filtering Properties

Tables support filtering columns by the following condition types:

  isEmpty
isNotEmpty
textIs
textContains
textDoesNotContain
textStartsWith
textEndsWith
isEqualTo
isNotEqualTo
isLessThan
isLessThanOrEqualTo
isGreaterThan
isGreaterThanOrEqualTo
isBetween
dateIs
dateIsBefore
dateIsAfter
dateIsBetween

Events

The following events are triggered by user interactions with Table components. Use event handlers to trigger actions in response to user events.

PropertyDescription
onRowClickedTriggers an action when a table row is clicked
onRowSelectedTriggers an action when a table row selection is changed
onPageChangeTriggers an action when a table page item is changed
onFiltersChangedTriggers an action when a table filter is changed
onSaveChangesTriggers an action when table edits are saved
onCancelChangesTriggers an action when table edits are canceled

Column Properties

PropertyDescription
Column TypeSelect how the column's data is displayed, see this section for more details
Computed ValueSet the value of the column, use {{currentRow.*}} syntax to set dynamically
VisibleSet true to show and false to hide. Set dynamically using JavaScript with {{}}
Text AlignLeft, center or right alignment
Text SizeSet the size of text to be displayed
Font StyleBold or italicize the text
Vertical AlignTop, middle, or bottom alignment
Text ColorSet the text color using the color picker or hex value
Cell BackgroundSet the cell background color using the color picker or hex value
Freeze ColumnFreezing a column keeps it visible on the left-hand side of the table while scrolling horizontally
EditableMakes the column editable in line, values are a boolean
Editing TypeSet the input type while editing. Options are: Text, Number, Email, Dropdown, Checkbox, DatePicker
Text WrapIf enabled, the text will wrap within the cell

Column types

When referencing a row in column properties, use {{currentRow.<column_property>}} in order to specify how a column is populated. currentRow Example

Plain Text

Value of cell will be treated as plain text. Text styling options are available such as size, alignment, and color.

Number

Value of cell will be treated as a number. The following options are available:

  • Number Formatting
  • Minimum Fraction Digits
  • Maximum Fraction Digits

Currency

Formats the current cell as a currency value. The following options are available:

  • ISO Currency Code
  • Number Formatting
  • Minimum Fraction Digits
  • Maximum Fraction Digits

Percentage

Formats the current cell as a percentage. The following options are available:

  • Minimum Fraction Digits
  • Maximum Fraction Digits

Image

If the value of the cell is a URL to an image, the image column type will display the image rather than the URL. Supported file types are jpeg, jpg, gif, and png.

Video

If the value of the cell is a URL to a video, the video column type will display an icon that opens the video when clicked.

Date

Formats the field to a specific date format, this allows for translation from one format into another. The following options are available:

  • Original Date Format
  • Display Date Format

Button

Display a button within each cell. The following options are available:

  • Label
  • Button Color
  • Label Color
  • onClick Trigger

Value of cell will be displayed as a clickable link, the label of the link can be altered with the Link Label option. The following options are available:

  • Link URL
  • Link Label
  • Open in new tab

Boolean

Accepts expressions that evaluate to true or false and displays accordingly. True values will display as check marks, false values will display based on the selection of the False Value property:

False Value Example

Tags

Formats each item in the field with a separate color. If the value is an array (e.g. ['foo', 'bar']) each value in the array will be tagged separately.

To customize tag colors, click the + sign next to Custom Tag Colors. For the newly added tag, select an available option in the dropdown or type to add a new one. Use the color picker to the left of the tag to assign a color to that tag along with configurable opacity.

configure custom tag colors in a table

Alternivately, custom tag colors can be configured with the <> Code tab using a JSON object:

{
"TAG_NAME_1": {
"color": "HEX_CODE"
},
"TAG_NAME_2": {
"color": "HEX_CODE"
},
...
"TAG_NAME_N": {
"color": "HEX_CODE"
}
}
configure custom tag colors with code mode

Email

Value of cell will be treated as plain text. Text styling options are available such as size, alignment, and color. If Editable is enabled, the default Editing Type is Email.