Screen Fields

Last updated 11/04/2025

What are Screen Fields?

Screen fields are fields that are not attached to a database. Adding screen fields enables you to add fields that can be used as arguments for your process. You can use the screen fields for tasks such as filtering data, getting data that is required for your process to work, and entering data into your database.

A process does not have to have any screen fields, however, if you need additional values, screen fields can be used to get this data.

Add Screen Fields to a Process

1. Click the Screen Fields tab.

Figure 1 - Screen Fields tab

2. Click the Add Screen Fields button.

Figure 2 - Add Screen Fields button

3. Type a caption in the Caption field.

4. Click the lookup icon in the Display Type field and select a type.

Figure 3 - Add screen field

5. Click the Save button in the form app bar.

Figure 4 - Save button

info

Continue to add as many screen fields as you require. For this example, two more screen fields were added, an Email field with a display type of _Email, and a Message field with a display type of _Memo.

6. Click the Save button in the form app bar on completion.

Figure 5 - Save button

Data Entry Screen Fields

info

For full documentation on how to build the Button Demo app, please refer to the Action Buttons chapter under Events.

Let's take a look at the Send Message process in an application. In the image below, three screen fields have been added to the process: Name, Email, and Message. These fields are not tied to a database they are purely to enter values and the recipient will receive an email with the message.

Figure 6 - Send Message process

The

ValidateData()

function is attached to the On Run event.

Figure 7 - On Run event

This function will validate that the values entered into the Name, Email, and Message fields are valid. If the values are not valid an error will be created using Five's

createError()

function when the Run button is clicked on the process.

Validate data

function ValidateData(five, context, result) {
    if (five.field.Name === '') {
        return five.createError('Please enter the name for the recipient');
    }

    if (five.field.Email === '') {
        return five.createError('Please enter an email address to send the message');
    }

    if (five.field.Message === '') {
        return five.createError('Please enter a message to send to : ' + five.field.Email);
    }

    return five.success(result);
}

An error is created when the Run button is clicked as no value is in the Email field.

Figure 8 - Create error message

Using Screen Fields to Filter Data

Let's take a look at the Find Books dashboard, it holds a process at the top which has three screen fields: Title, ISBN, and Search. The Title and ISBN fields can take a value and when the Search button is clicked the filtered results that correspond with the values entered into the Title and/or ISBN screen fields will be returned.

Figure 9 - Find Book dashboard

This is because the Find Book process (positioned at the top of the Find Books dashboard) has the Title, ISBN, and SEARCH screen fields.

Figure 10 - Find Book process screen fields

The Search screen field has a display type of Button.

Figure 11 - Search screen field

When a screen field has a display type of _Button, it requires a function to be attached to the On Click event. For this scenario, the process will execute when the Search button is clicked.

Figure 12 - On Click event

The function attached to the On Click event for the Search screen field is called

SetSearchISBN()

. This function sets several variables using Five's

setVariable()

function. The Find Book process uses these global variables for the ISBN and Title screen fields to filter the results. The value in the Title field uses the SQL

LIKE

operator to find zero, one, or multiple characters in the value entered in the Title field.

Set variables and refresh tables

function SetSearchISBN(five, context, result)  {
    five.setVariable('ISBN', five.field.ISBN);
    five.setVariable('Title', `%${five.field.Title}%`);
    five.setVariable('UserKey', five.currentUserKey());
    five.refreshTable('Book');
    five.refreshTable('iUser');
    return five.success(result);
}

When the Search button is clicked in the application, the filtered results using the screen field values will be returned.

Figure 13 - Using screen fields to filter