Skip to main content

On Show

Last updated 30/11/2021

On Show Event

The OnShow event executes on the client.

Function Signature
OnShow(five, context, result) : FiveError;

ParameterTypeDescription
fiveFiveInstanceAn instance of the Five object.
contextMap<string,any>Optional map of string to values.
resultFiveErrorA Five error to set the result and return the error.

Description

When the form shows the event will be detected and the code will execute. The event occurs in your end-user application when the form is shown on the screen either by:

  1. Clicking the Add Item button to receive a new form.
Add Item Button
Figure 1 - Add Item button

  1. Clicking the Add button on a subform.
Sub-Form Add Button
Figure 2 - Sub-form Add button

  1. Selecting a saved form record.
Form Record
Figure 3 - Form record

  1. Selecting a saved sub-form record.
Sub-Form Record
Figure 4 - Sub-form record

Example

In the Production application, we can programmatically populate a lookup list in a field (Registration State field) to select the Australian state the car is registered. When the form with the field is shown (Cars form) on the screen the OnShow event will fire and populate all the state options in the lookup list.

The below function is performing the following:

  • Uses the sender parameter to get the General form page.
  • Five's DataManager is used on the General form page to get the Registration State form field. The form field is a display type of _LookupCustom, we clear its current options in case there are options already populated from a previous OnShow event.
  • Populate the lookup list with the options as key value pairs.
OnShow event is executed to programmatically populate the lookup list when the form is shown.
function stateOptions(sender: any, context: any, result: FiveError) : FiveError {
const generalFormPage = sender.getPage('General');
const stateField = generalFormPage.dataManager.getFormFieldTypeByID('RegistrationState');
stateField.clearOptions();
stateField.addOption("QLD", "Queensland");
stateField.addOption("NSW", "New South Wales");
stateField.addOption("Vic", "Victoria");
stateField.addOption("SA", "South Australia");
stateField.addOption("WA", "Western Australia");
stateField.addOption("Tas", "Tasmania");
stateField.addOption("NT", "Northern Territory");
sender.refresh();
return result;
}

Prerequisites

  • Function must be saved in the Functions view.
  • Form must be saved in the Forms view.

Steps to Attach a Function to the On Show Event

  1. Select Forms in the menu.
  2. Select the required form record in the list.
  3. Click the Events tab.
  4. Click the Edit button in the form app bar.
  5. Use the lookup icon in the On Show field and select the required Function ID.
  6. Click the Save button in the form app bar.
Attach Function to On Show Event
Figure 5 - Attach a function to the On Show event