Reference Guide

Data Table

The Data Table component allows you to display a list of data records from your Nutshell database, or any other source of data, such as a web service or API.

Data Tables can be displayed in either horizontal format (a conventional matrix with sortable columns, ideal for more complex data-sets with lots of columns) or vertical format (a menu-like list of items, better for shorter, simpler data-sets).

Fields can be displayed horizontally across the screen or stacked vertically down the screen

Horizontal Format

If you’ve ever created a table in Microsoft Word, you’ll be familiar with this concept. Horizontal format displays columns of data horizontally across the screen, with sortable headers across the top.

Horizontal tables are great for bigger screens and data-sets containing lots of critical fields

This kind of table is ideal for larger data-sets, where you need to see lots of information on screen at once. It’s also more comfortable for Tablet devices, as there’s more space available to fit plenty of columns.

To display your data table in horizontal format, choose the Horizontal (tablet) option at the top the Properties panel.

Vertical Format

If you have a relatively simple data-set and only want to show a simple label for each item – for example, a list of names in an address book – then the vertical format might work better for you.

Vertical tables are great for shorter lists containing only a little critical information

In this format, records are stacked vertically like a conventional menu, which is much better suited to a smartphone device, where space is limited.

To display your data table in vertical format, choose the Vertical (smartphone) option at the top the Properties panel.

Sorting Options

Whether you’re using vertical or horizontal format, you can decide what order you want the results to be listed in by default. In vertical format, you can sort on either the primary or secondary label. In horizontal format, you can sort on any of the columns you’ve set up.

Default sorting options can be set in the Properties Panel

If you’re displaying data in horizontal format, you have the additional option of allowing end-users to control the sort order themselves, by tapping on the column headers.

Allow your end-users to re-sort the table themselves by tapping on the column headers

Paginating Results

If your data-set contains lots of records, you may not want to display them all on screen at once. It’s possible to split your results into separate ‘pages’ when the result-set grows beyond a specific limit; this is called pagination, and can make radically improve the experience for your end-user when dealing with heavy data-sets.

Very long tables can be broken down into shorter pages of results

If pagination is enabled and your data-set exceeds the threshold you set, arrow buttons will appear under the table, allowing the end-user to skip through pages of results quickly and easily.

Item Count

It’s generally good practice to let your end-user know how many items have been returned in total, and how many of them they can see at a given time; especially if the results have been paginated.

Tell your end-user how many items have been returned with the item count option

The Data Table component comes with this as an option. Just turn it on in the Properties panel, and it will display the number of records returned above the data table.

Managing Columns

If you’re displaying your data in a horizontal format, you’ll want to add some custom columns that relate to your data. In the Properties panel, if you have Horizontal format selected, you’ll see a list of Columns.

Add, delete and re-order columns in your table within the Properties Panel

Click the “+” button to add a new Column to the list. You can edit the column by clicking on it and typing a name. When you’re finished, just click anywhere outside of the list. Nutshell allows you to add as many columns as you like, move them up or down the list, and delete them.

Behaviour

Sometimes data tables are used to display read-only information. Other times, they’re used to list items that can be selected or interacted with. Nutshell allows you to specify what you want to happen when the end-user taps on a row in your table.

You decide what should happen when the end-user taps a row in the Data Table

The options are:

Auto-submit
The row acts just like a button, causing the workflow to progress to the next logical step. This is ideal for viewing an item in more detail – for example, displaying the profile of a customer by tapping on their name in a list.

Select item
The row is selected, but the workflow doesn’t move forward – it waits for further input. This is ideal where there are several things you can do with the item – for example, deleting or editing a selected row.

Do nothing
If your table is just for display, you can ignore an end-user’s tap altogether.

Resizing a Data Table

You can resize a Data Table component by clicking and dragging a corner of its bounding box. Because Data Tables are populated from dynamic (i.e. changeable) data-sources, you might not know exactly how many items will be displayed. This makes it difficult to know how much space to allow on your screen.

You get to decide what should happen when your Data Table gets really big

To help you, there are two options:

Flexible Height
If enabled, this setting effectively ignores the height of the data table on the Canvas, and will simply grow the table as tall as it needs to be to accommodate the data it receives. In this instance, anything below the data table on your screen will be pushed down along with it. This can, of course, be controlled to some degree by enabling pagination.

Fixed Height
If enabled, this setting makes sure your table never takes up more space on-screen than the height you’ve set it on the Canvas. If there are more records than will fit in the available space, the end-user will be able to scroll through them within that fixed space.

Populating a Data Table

Data Table components can only be populated from a dynamic data-source. What do we mean by dynamic? Dynamic data is content that is changeable – namely a Nutshell database table or a Nutshell Connector (i.e. a web service or API).

Data Tables are populated by data components in a process called ‘mapping’

Data Tables are populated by mapping the results from a database query to the table. This process is part of the Data component, which is detailed elsewhere in the Nutshell Reference Guide.

Data Table Properties

When a Data Table component is selected on the Canvas, the following settings are available in the Properties panel:

(note that some options may only be visible when others are enabled)