Fields

Overview

Fields define the structure of Records in Collections. All the Records in a given Collection have the same structure.

Contents

• Collection Structure
• Editing Fields
• All Field Types

Collection Structure

Consider a simple "Customers" Collection with the following Fields:

• "Name" - Text field
• "Telephone No." - Phone field
• "Email" - Email field

Every Record in this collection will have "Name", "Telephone No.", and "Email" fields.

It is not possible for Records in the same Collection to include extra fields or omit other fields. The values of Fields in Records may be left empty, if particular Fields are not useful for a particular Record.

Some Field types allow a large degree of customisation and flexibility in editing, in particular the Rich Text field.

Editing Fields

To edit the Fields within a Collection, first open the "Edit Collection" modal. Within a Project, click the Project button at the right side of the header, then select the Collections tab, then click the Edit button for the target Collection.

In the Edit Collection modal, select the Fields tab. This tab displays the list of all the Fields in the Collection.

Add a new Field by clicking the + Add Field button. The new Field will be added to the bottom of the list.

Duplicate an existing Field by clicking the button on an existing Field. The Field and all of it's settings will be copied into a new Field.

Edit the settings for a Field by clicking the Field row. The "Edit Field" modal is shown where the main properties of the field can be edited, including:

• Name - The main identifier for the field, this should be a short descriptive name.
• Description - An optional longer description, if more information is required.
• Key - An identifier used when reading from or writing to the field in code as an alternative to using the Field's unique identifier, see the Developer pages for more information.
• Type - The type of data to be stored in this field, see the individual Field Types section below for more information.

Reorder the Fields by dragging their drag handle up of down. The order defines the order that the field will be displayed in the Record Preview Modal, and in various dropdown menus.

Delete a Field by clicking the button.

All Field Types

There are a wide range of Field types available. Any number and combination of Fields can be included in a Collection.

• Attachment
• Boolean
• Button
• Checklist
• Code
• Colour
• Created By
• Created Time
• Currency
• Date
• Email
• Formula
• Image
• Image Url
• Join
• Key-Value
• Lookup
• Modified By
• Modified Time
• Multi-line Text
• Number
• Percent
• Phone
• Rating
• Reference
• Rich Text
• Select
• Summary
• Text Line
• Time
• Timestamp
• Url
• User

Attachment

Attachment fields link to one of more Attachments in the Project.

Settings

The attachment field has a number of options to control how users can interact with it:

• allow multiple attachments to be selected
• allow new attachments to be uploaded from this field
• allow existing attachments in the Project to be selected

Boolean

A true or false value. The value is edited and displayed using a checkbox.

Settings

• The field can optionally be configured with a default value.

Button

A button is displayed that calls a selected Custom Function.

The current record is provided in the context of the selected Custom Function, providing an easy mechanism to perform operations to a particular Record. This is similar to Record Actions in Collections, but the button is more easily accessible to the user.

Note: The Button field is commonly used in List Views and other Views where the displayed fields are not editable by default. To enable clicking the button, the field must be editable in the View.

Settings

• Label - the label to display in the button
• Colour - the background colour of the button (the foreground colour is calculated to contrast with any selected colour)
• Function - the Custom Function to run when the button is clicked

Checklist

A list of "to do" items, each with a text label and a checkbox.

When the field is editable, the checkbox can be checked and unchecked, the label can be edited, and items can be added, removed, and reordered.

When the field is not editable, by default the checklist items are displayed as read-only. If the field setting is enabled, then a summary of the checklist items is displayed instead.

Settings

• whether the checklist should be summarised when it is not editable, instead of displaying all the checklist items
• whether the summarised value should be displayed in a progress bar

Code

Some pre-formatted code as text. This is intended to be used for inline snippets of code, or preformatted strings like a JSON or XML object.

If the type of text or programming language is among the available options in the field settings, then field's value can be edited with an editor appropriate to the type, including limited syntax checking. If the type "Other" is selected, the field acts as a multi-line preformatted text box with no syntax checking.

Settings

• the type of text or language stored in the field

Colour

A colour value stored as a string, e.g. #007ba7. A colour can be selected using the preset colours modal, or using the browser's built-in colour picker.

Settings

• whether the selected value should be displayed, and in what format

Created By

The user who created the record. The user's ID is stored, and the user's name and icon are displayed.

This information is always stored in every record regardless of whether or not this field is added to a Collection, but the field must be added in order to read the information.

Created Time

The timestamp at which the record was created. The timestamp is stored as an ISO 8601 string, and is displayed as a more readable date and time string.

This information is always stored in every record regardless of whether or not this field is added to a Collection, but the field must be added in order to read the information.

Currency

An amount of currency as a number, with a configurable currency symbol in the field settings.

Settings

• the currency symbol to display
• an optional default value

Date

A date specifying a single day. The date is displayed in the format of the current user's locale. The date is stored as a string in the form: yyyy-mm-dd.

The browser's built-in date picker is used for editing (e.g.: ).

Email

An email address stored as a string.

Formula

A Formula field can calculate a value based on the values of other fields in the same Record.

A Formula can be any Javascript expression.

As an example, a formula field can be used to create a "Full Name" field using "First Name" and "Surname" fields. The formula itself would look like this:

return r.field("First Name") + " " + r.field("Surname");

There are two restrictions on the calculations that can be performed:

• the formula can only read the other fields in the same Record
• the Javascript expression must be synchronous (i.e. you cannot use await or .then(() => ...) after a Promise)

For a detailed guide with example for common calculations, see the Formula Field guide.

Settings

• the return type of the formula
• display returned value without formatting
• the formula expression

Image

One or more images, uploaded to or selected from the Project's Attachments.

Depending on the field's settings, the field displays the thumbnails of the currently selected image(s), and:

• an Upload button for users to upload new image files to the project
• a Select button for users to select existing image attachments in the project

Settings

• allow uploading/selecting multiple images
• enable uploading new images
• enable selecting existing images

Image Url

A image URL stored as a string.

Join

A Join field enables links between Collections to be defined using Collection Joins.

When editing, Join fields act like Reference fields, allowing the user to select related Records. However, the related Records are also updated, so both Records reference each other.

For more information, see the Joins page.

For comparisons between References and Joins, see the guide on Related Records.

Settings

• the join definition
• enable colouring of related Records

Key-Value

Key-Value fields enable a number of "key-value pairs" to be defined.

A key-value pair consists of:

• a "key" as text
• a "value", which is one of:
  • some text
  • a number
  • a true/false value, displayed as a checkbox

Any number of key-value pairs can be defined in a single field. The pairs can be added, removed, and reordered in the list.

Key-Value fields can be useful where a list of "checklist" items is required, but one or more of the items needs to be something other than a checkbox (e.g. an "Other" option as text). If a simple checklist is required, consider the Checklist field type.

Settings

• if the "keys" in the field should be editable

Lookup

A Lookup field displays data from a selected field in a related Record.

To configure a Lookup field, a Reference or Join field in the current Collection must first be selected which defines which related Record(s) should be read. Next, one of the fields from the related Record is selected to display in the Lookup field.

This field is similar to Summary fields, however Summary fields condense the related data into a single calculated value.

Settings

• the field in the current Collection defining the related Record
• the field in the related Record to display

Modified By

The user who last modified the record. The user's ID is stored, and the user's name and icon are displayed.

This information is always stored in every record regardless of whether or not this field is added to a Collection, but the field must be added in order to read the information.

Modified Time

The timestamp at which the record was last modified. The timestamp is stored as an ISO 8601 string, and is displayed as a more readable date and time string.

This information is always stored in every record regardless of whether or not this field is added to a Collection, but the field must be added in order to read the information.

Multi-line Text

A text value longer than a single line. This may be used for a description of a record, an address, some notes or comments, etc.

Simple formatting using markdown can be enabled in this field. For more information about markdown formatting, please see our markdown introduction. If more formatting options are required, consider the Rich Text field.

This field is edited using a text area, which can be resized by the user. When displaying the value, if markdown formatting is enabled the value will be displayed with any markdown formatting applied, otherwise the entered text will be displayed.

The entered value is stored internally as a string.

Settings

• Default - optionally specify a default value for this field in new Records
• Markdown formatted - enable markdown formatting for this field

Number

A simple number. Edited using the browser's built-in input control (e.g. ).

Percent

A simple number, formatted as a percentage. Edited using the browser's built-in input control (e.g. ).

Settings

• an optional default value
• whether the value should be displayed as a progress bar

Phone

A telephone number stored as a string.

Rating

A visual rating. By default, the field allows the user to select a number of stars out of 5, but the symbols and maximum value can be configured in the field's settings.

Settings

• the "selected" symbol
• the "empty" symbol
• the maximum selectable value

Reference

A Reference field enables the user to select one or more Records from another Collection, which are then displayed as links.

Reference fields are similar to Join fields, however the Record being referenced is not updated and has has no knowledge of the reference. References are generally easier to configure than Joins, but are generally not as powerful. References can be used to link to Records in Remote Collections, which Joins cannot.

Depending on the field's settings, the field can reference either one related Record or multiple records. The field can also be configured to allow the user to only select related Records, or to enable them to additionally create or delete Records in the other collection via the Reference field.

For more information on References and Joins, see the guide on Related Records.

Settings

• the Collection to link to
• allow the user to reference multiple Records
• allow the user to select related records
• allow the user to create related records
• allow the user to delete related records
• enable colouring of related records

Rich Text

The rich text field allows users to edit longer pieces of text and apply a range of formatting options in a "WYSIWYG" editor. Other elements may also be embedded within the text, including images, tables, and task lists.

When editing, the field shows all applied formatting options and embedded elements while the user edits the value. This is in contrast to the more simple Multi-line Text field, where markdown formatting is only displayed when the field is not being edited.

The Rich Text editor provides control and keyboard shortcuts to apply all the possible formatting options.

Please see the Rich Text guide for a complete list of all the available options.

The entered value is stored as an HTML string.

Select

A "select box" or "dropdown box". Used to select one of a configured set of options.

When editing, a dropdown box is displayed containing the configured options. When the field is not editable, the selected value (if any) is displayed on its own.

The options in the field can optionally be configured to have separate "values" and "labels". If this option is selected, the option will be displayed to the user using its label, but the value of the selected option will be stored. This setting lets the options have their labels changed at a later time while not breaking any existing selections. Enabling this option is generally recommended.

Settings

• Use separate label - optionally configure the options to use separate values and labels
• Select options - configure the available options in the select box
  • Each option has the following settings:
    • the "value" of the option
    • the "label" of the option (if use separate label is selected)
    • the background colour of the option
    • the foreground colour of the option
  • Options may be added, removed, and reordered

Summary

A Summary field displays a summary of a set of related Records.

Summary fields are similar to Lookup fields, however they do not display the values from the related Records. Instead, they summarise the related data using a selected operation.

To configure a Summary field, a Reference or Join field in the current Collection must first be selected which defines which related Record(s) should be read. Next, one of the fields from the related Record is selected to be summarised by the summary operation. Finally, a summary operation is selected.

The available summary operations are:

• Count - Count related records
• Count empty - Count records with empty values
• Count non-empty - Count records with non-empty values
• Sum - Find the sum of related values
• Average - Find the average of related values
• Minimum - Find the minimum value from related values
• Maximum - Find the maximum value from related values
• And - True if all related values are true
• Or - True if any related values are true
• Concatenate - Concatenate related values into one string
• Concatenate with comma - Concatenate non-empty values separated by ", "
• Unique - Find unique values from related values
• Unique non-empty - Find non-empty unique values from related values

Settings

• the field in the current Collection defining the related Record
• the field in the related Record to summarise
• the summary operation to apply to the values from the related Records

Text Line

A simple text value. Useful for a short line of text, the name of a person or company, etc.

Time

A time of day or short length of time, displayed as HH:mm. This can be used to indicate a time of day without requiring a date, or a number of hours and minutes as a duration. If it is required to specify both a date and time, use a Timestamp field instead.

The browser's built-in time picker is used for editing (e.g.: ).

Timestamp

A date and time.

The browser's built-in date and time pickers are used for editing (e.g.: ). An additional button is provided for quickly entering the current time (click the button in the field).

The value is stored internally as an ISO 8601 string (e.g. 2020-12-25T13:37:00.000Z).

Url

A simple URL stored as text.

User

The User field enables one of more Members of the current Workspace to be selected. The list of available Users is kept up to date based on the current members of the Workspace.

The User field has a special option when filtering, enabling the field value to be compered against "the current User", whoever is logged in at the time. For example, this enables a single "My To Do Items" filtering to display all Records assigned to "the current user" to be used by all the members of the Workspace.

Settings

• allow multiple Users to be selected