Articles in this section

Grid

Avatar
Max Bateson
  • Updated
Follow

Overview

A Grid Field is a structured table of data composed of DataSets and SubFields, displayed as rows and columns. Unlike a List field, each individual cell within a Grid has a unique identifier, allowing it to be referenced independently in expressions, templates, reports and workflows across the application.

Common use cases include:

  • Financial tables
  • Checklists
  • Milestone or stage tracking tables

Grid fields can have adjusted column widths but rather than fully follow responsive design principles, it takes the preferable option to and a horizontal scroll when content exceeds the available horizontal space so make sure to test if narrower device screens are likely to be using the App.

To add a new Feld see the support article for Adding and Editing Fields which will also cover common properties. This article will focus on properties and what is useful to know in the specific context of a Grid Field.

 

 

Label & Identifier

When deciding on the Grid Field Label, know that the label isn't shown in the workspace, but is still useful to have if you want to search for it in your fields.

The Identifier is a unique reference to this Grid Field. When choosing your identifier its best not to make it too long because if you want to reference an individual cell in an expression it will be will make it longer and harder to understand (especially if it's a long expression).

Each cell in a Grid Field has it's own Grid Cell Identifier. This is generated in the format

[GridFieldIdentifier_DataSetIdentifier_SubFieldIdentifier]

Example: We have a Schedule Grid that tracks date SubFields including ActualStartDate for Project Phase DataSets including Initiation.

The individual Cell Identifier would be:

[Schedule_Initiation_ActualStartDate]

 

 

Grid Orientation

Orientation determines how Datasets and SubFields are displayed as rows or columns. The way to remeber which orientation a Grid has is to think of it as the direction of the data within the DataSets. Orientation can be changed after the Grid Field has been created.

Vertical means that SubFields are horizontal (Rows) and DataSets are vertical (Columns):

Horizontal means that DataSets are horizontal (Rows) and SubFields are vertical (Columns):

 

 

Grid Row Title Visibility

Hide grid row titles means that whatever is entered into the label for the field or dataset (depending or orientation) will be hidden.

This feature is commonly used to increase the available horizontal screen space available when the row titles fo not add functional value.

With Grid Row Titles:

Hidden Grid Row Titles:

 

 

Click to Edit

This feature allows for the formatting of grid cells whilst still allowing you to input and edit data within the grid. Toggle the Clilck to Edit option on as shown here:

An example of when to use this feature is in a Grid Field that is showing financial information. Suppose that we are tracking Budget and Actual Spend for a financial year so entering these into a Grid and calculating the delta. Without click to edit it would look as follows:

The values need to be editable as they are being typed in but we want to show the numbers in a formatted presentation. Without the formatted values showing it is easy to misread the number of zeros so 120000 could easily be misread as £12,000 not £120,000 which could lead to errors. With Click to Edit enabled, the easily readable formatted vlaues will show whilst preserving the ability to make edits.

Note: To display a formatted value for the SubField, you will need to use the formatting options given for the SubField in the Table and NOT the Format String with display formatted enabled as the latter would make the Field ReadOnly.

 

 

DataSets & SubFields

A DataSet is a predefined row (or column depending on orientation) in a GridField that represents a specific, fixed context (such as a month, a project phase, a cheklist item, ...). For each DataSet, you define SubFields which are data values captured against each DataSet (such as budget spend, target completion date, current status, ...). 

Let's explain the difference between Data Sets and Fields using the financial example from above

 

Data Sets

In the Financial Grid Field, the DataSets are the months of the year (Apr, May, June, ..., Mar) so each column is a DataSet.

DataSets only require a Label and an Identifier as the data types are handled by the SubFields. The identifier is important for referencing cells in expressions, templates and workflows, while the label is what will be displayed as the heading for the row or column.

Note: There are a fixed number of DataSets defined in the GridField, if you have a solution where you need to have a dynamic number of items added in the Workspace then consider a ListField. These are less flexible, particularly with expressions but allow for a dynamic number of items. Typical scenarios would be adding Agenda items against a Meeting or Tasks against and Action.

 

Sub Fields

Sub Fields define the type and behaviour of each cell within the Grid. So in our Financial Grid, we set Budget to be a Number SubField, whereas we set Status to be a Multi-State RAG SubField.

The label and identifier work the same as they do on datasets. You then set the properties for the SubField based on the Field Type selected (as you would when adding a Field)

The Field Types currently supported to use in a Grid Field are:

Barcode, Bit, Date, DateTime, Document, Draw, Email, Image, Image List, Integer, Literal, Long, Long Text, Money, Multi-State, Notes, Number, Period, Person, Person By Team, Range, Selection, Team, Text, Time, URL, URL Download

Useful properties to remember to consider when adding SubFields that are relevant to most Fields are Format String, Default Initial Values, Required and Read Only. 

 

 

Header Text

Header Text appears as a Row above a DataSet (or Field depending on orientation) and allows you to give more context or instruction to the row labels. The Header Text is added into the DataSet or SubField configuration.

The result is the ability to enhance the Grid layout such as our financial grid below

 

 

Column Sizes

In the column size configuration, you can adjust the width to fit the data that will be entered so that the grid columns are well proportioned. The column size is configured on the DataSet or SubField depending which are columns based on the Grid Orientation.

Column sizes will be set by choosing from a range of 'Tiny' to 'Wider'. The other options available are:

  • Default: This will give each column an equal width
  • Auto: This will decide the width of the Column based on the Field Type

There is also the option to set Elasticity. Elasticity works by sharing any extra horizontal screen width available in a ratio between the Fields that have elasticity. If one Field has an elasticity of 1 and two Fields have an elasticity of 2 then the remaining screen space available would be spread between them in a ratio of 1:2:2.

Without setting preferred column widths our Schedule Grid would look like this:

By setting column widths and elasticities, we can have an improved representation like so:

 

 

Expressions

Each individual grid cell can contain an expression. So, if there are 12 datasets and 5 fields there will be 20 cells that can each optionally have an expression. These expressions work the same as they do in standalone fields.

When working on a lot of expressions it can be difficult to keep up with the changes you've made so we have added a state column that shows you which ones have been modified. 

We have also added the ability to search expressions which is particularly useful when you have larger Grids with many DataSets and SubFields.

 

Adding a Single Grid Cell Expression

To add an expression click on the Field Identifier in the Expression section of App Builder and then add the expression in the pop out. For examples of what expressions can be used, refer to the Expression Articles.

This is also where we can set two more properties for the Grid Cell:

  • Use Expression as default value only? - This will mean that the expression will run when the Record is created but then be manual edit for any value changes after the Record creation.
  • Exclude This Field From Templated Record Copy? - When copying a Record via UI or Workflow and selecting for it to be a Templated copy then any Grid Cells with this property set will be excluded from the copy.

 

Adding Expressions for a full DataSet or SubField

The Grid Field has a function that saves a lot of time when expressions across a DataSet or Field all have the same structure. This to Add Expression Template.

This allows for the entry of an expression structure like in the below where the Delta between Budget and Actual Spend in a Financial Grid is always the Budget minus the Actual.

If we were writing this expression across 12 months then we would need to individually add:

Month 1: [Financials_M01_Budget] - [Financials_M01_Actual]
Month 2: [Financials_M02_Budget] - [Financials_M02_Actual]
...
Month 12: [Financials_M12_Budget] - [Financials_M12_Actual]

By using the structure

[Financials_{{DataSet}}_Budget] - [Financials_{{DataSet}}_Actual]

This will add 12 expressions, one for each Monthly Delta Cell

For a full explanation on how this expression is structured see the Grid Expression Template article

 

Tips & Best Practices

When creating a grid that is mostly made of expressions it's best to put the expression in chunks, then saving and repeating this process. If you put them all in in one go and there is an error it can take a long time to find the error.

If you're creating a checklist, milestone tracker or similar grid fields it is better to use a standard identifier like 'I01' for item 1 or 'S01' for stage 1 instead of something like 'TrainPersonal' or 'Definestage' as it's easier to reference and if you change the label you don't have a mismatch to the identifier.

A common issue when trying to save a field and it failing is that the dataset and field identifiers aren't valid i.e. there is a space or invalid character.

If you are going to use this grid on a mobile or tablet it's best to test it first because screen sizing can have a big impact on usability

If you’re creating a large checklist to be completed over a long period, consider splitting it into multiple grid fields instead of using Header Text to separate sections. This allows each section to be placed in its own template, so users only see the parts of the checklist that are currently relevant.

 

 

 

 

Related articles

Comments

0 comments

Article is closed for comments.