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

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

Table from component panel

The table will load with an example dataset.

Example table dataset

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 Create API in the bottom panel and click on [Demo] Orders to create an API that uses the [Demo] Orders Postgres Database.

Table API example using Postgres

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

SELECT *
FROM orders

Table Postgres example

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

Table results

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. 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. Furthermore, the user has the possibility to either save the changes or cancel them 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 1 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 change made by the user in the table (Billie Eilish -> Julia) has been undone at the moment the user clicked on Save 1 Changes. Read in the next chapter how to permanently save the edited data.

The event handler has triggered a show alert action

Save edited data

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.

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 old and new values of all modified rows in the table. The newRows property can be used to write the edited data ("name":"Julia") to a database and to save the changes permanently:

{
"oldRows":[
{
"name":"Billie Eilish",
"twitter":"https://twitter.com/billieeilish",
...
}
],
"newRows":[
{
"name":"Julia",
"twitter":"https://twitter.com/billieeilish",
...
}
]
}

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

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

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
ColumnsAdjust how the columns display
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 Search TextSet the default text to appear within the search bar
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
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

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 old and new values of all modified rows in the table
Table1.allEditsReturns an array containing all table data with edits
Table1.currentEditValueReturns a string containing the cell value of the in-progress edit (loses context when cell is unfocused by the user)

Events

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

PropertyDescription
onRowClickedTrigger an action when a table row is clicked
onRowSelectedTrigger an action when a table row selection is changed
onPageChangeTrigger an action when a table page item is changed
onFiltersChangedTrigger an action when a table filter is changed
onSaveChangesTriggers an action when table edits are saved
onCancelChangesTriggers an action when table edits are canceled

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

Column types for tables

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

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.

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

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.

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