selectRecord() and selectAction() with recordKey

Last updated 12/02/2025

This documentation is to demonstrate the difference between using the

selectRecord()

function and the

selectAction()

function and passing in the optional

recordKey

parameter. The

recordKey

parameter is mandatory when using

selectRecord()

, however, it is optional when using

selectAction()

. Both functions will select a record and can only be used with form actions when using the

recordKey

parameter.

When using the

selectRecord()

function, the form record returned will take the area of the list and form and there is no list of records.

Figure 1 - Form record

When using the

selectAction()

function, and passing in the optional

recordKey

parameter, the list of records will display with the record highlighted in the list and the form record displayed.

Figure 2 - Form record

info

The Action Navigation application is created to demonstrate the

selectRecord()

function and

selectAction()

function with the

recordKey

parameter, the creation of this application is documented in the Introduction chapter so you can perform the tutorial. The

selectRecord()

and

selectAction()

with

recordKey

tutorial follows on from the

selectAction()

,

previousAction()

,

replaceAction()

, and

restoreAction()

tutorials.

To demonstrate how to use these functions the following has been added into the Action Navigation application:

• Customer table - The Customer table has two fields LastName and FirstName.
• Customers form - The Customers form uses the Customer table as its main data source.
• Customers menu item - The Customers menu item references the Customers form in the Action field. This menu item was created by default in the Form Wizard.

Multiple actions and functions are used to demonstrate selecting a form record.

In this tutorial, the following will be performed to demonstrate the differences between the

selectRecord()

function and the

selectAction()

function with the optional

recordKey

parameter.

• Add the
  SelectCustomerRecord()
  function - To demonstrate using
  selectRecord()
  to select and display a form record.
• Add the
  SelectCustomerRecordKey()
  function - To demonstrate using
  selectAction()
  to select a form record.
• Edit the Process A record - To add three screen fields, one to select a customer, and the other two will select a record using two different methods based on the primary key of the selected customer.

Add the SelectCustomerRecord Function

The

SelectCustomerRecord()

function will use Five's

selectRecord()

function on the

Five

object to select and display a customer record and have the record take the area of the list and the form, ie, a single record is displayed without the list of records. The action ID

Customers

needs to be passed in as the first parameter to know what action (form) to select and display. The second parameter needs to be the primary key field of the customer record being selected. In this scenario a screen field with a display type of _Lookup will be added to the Process A record which enables you to select the primary key for the customer records in the lookup. The

Customer

field ID is passed in using the

field

property on the

Five

object.

1. Select Logic in the menu.

2. Select Functions in the sub-menu.

Figure 3 - Functions menu item

3. Click the Add Item button.

4. Type SelectCustomerRecord in the Function ID field.

5. Click in the Code Field to open the Code Editor.

Figure 4 - Add SelectCustomerRecord function

6. Copy and paste the code block below.

note

The code block needs to be pasted over the template that Five creates in the editor.

Select a form action and associated form record

function SelectCustomerRecord(five, context, result) {
    five.selectRecord('Customers', five.field.Customer);
    return five.success(result);
}

7. Click the Save button in the Code Editor app bar.

Figure 5 - Save button

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

Figure 6 - Save button

Add the SelectCustomerRecordKey Function

The

SelectCustomerRecordKey()

function will use Five's

selectAction()

function on the

Five

object and passes in the optional

recordKey

parameter to select a customer record in the list. The action ID

Customers

needs to be passed in as the first parameter to know which action (form) to select. The second optional

recordKey

parameter needs to be the primary key field of the customer record being selected. In this scenario, a screen field with a display type of _Lookup will be added to the Process A record which enables you to select the primary key for the customer records in the lookup. The

Customer

field ID is passed in using the

field

property on the

Five

object.

1. Click the Add Item button.

2. Type SelectCustomerRecordKey in the Function ID field.

3. Click in the Code field to open the Code Editor.

Figure 7 - Add SelectCustomerRecordKey function

4. Copy and paste the code block below.

note

The code block needs to be pasted over the template that Five creates in the editor.

Select a form action and associated form record

function SelectCustomerRecordKey(five, context, result) {
    five.selectAction('Customers', five.field.Customer);
    return five.success(result);
}

5. Click the Save button in the Code Editor app bar.

Figure 8 - Save button

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

Figure 9 - Save button

Edit Process A

The Process A record that was added in the previous chapters, needs to be edited to add the following three screen fields:

• Customer field - To select a customer, the primary key for the selected customer is used to know which customer record to select and display the record.
• Select Customer Record field - This will have a display type of _Button and have the
  SelectCustomerRecord()
  function attached to the On Click event.
• Select Customer Record Key field - This will have a display type of _Button and have the
  SelectCustomerRecordKey()
  function attached to the On Click event.

1. Select Tasks in the menu.

2. Select Processes in the sub-menu.

Figure 10 - Processes menu item

3. Select the Process A record in the list.

4. Click the Screen Fields tab.

Figure 11 - Screen Fields tab

5. Click the Add Screen Fields button.

Figure 12 - Add Screen Fields button

6. Type Customer in the Caption field.

info

The field ID for this field needs to be exactly the same as in your functions that were passed in using

five.field

7. Click the lookup icon in the Display Type field and select _Lookup.

8. Click the lookup icon in the Dependent Field and select Customers.

info

The Customers form will be referenced and the primary key will be used to know which form record to select.

Figure 13 - Add Customer screen field

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

Figure 14 - Save button

10. Click the Add Screen Fields button.

Figure 15 - Add Screen Fields button

11. Type Select Customer Record in the Caption field.

12. Click the lookup icon in the Display Type field and select _Button.

Figure 16 - Add Select Customer Record screen field

13. Click the Events tab.

Figure 17 - Events tab

14. Click the lookup icon in the On Click field and select SelectCustomerRecord.

Figure 18 - On Click field

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

Figure 19 - Save button

16. Click the Add Screen Fields button.

Figure 20 - Add Screen Fields button

17. Type Select Customer Record Key in the Caption field.

18. Click the lookup icon in the Display Type field and select _Button.

Figure 21 - Add Select Customer Record Key screen field

19. Click the Events tab.

Figure 22 - Events tab

20. Click the lookup icon in the On Click field and select SelectCustomerRecordKey.

Figure 23 - On Click field

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

Figure 24 - Save button

22. Click the Save button in the form bar above the list.

Figure 25 - Save button

How This Works in An Application

Deploy/run your application, you will be positioned on Process A. Select a Customer in the Customer field and click the Select Customer Record button.

Figure 26 - Process A

The event will execute the

SelectCustomerRecord()

function and selects and displays the customer form record. The record will take the area of the list and the form as

selectRecord()

is used in the

SelectCustomerRecord()

function. Select the Process A menu item again.

Figure 27 - Customer form record

On Process A, select a Customer in the Customer field and click the Select Customer Record Key button.

Figure 28 - Process A

The event will execute the

SelectCustomerRecordKey()

function and selects the customer form record. The record will be selected in the list with the form record next to the list. This is because the

recordKey

parameter was passed into

selectAction()

in the

SelectCustomerRecordKey()

function.

Figure 29 - Customer form record