On Show
Last updated 30/11/2021
On Show Event
The OnShow
event executes on the client
.
Function Signature
OnShow(five, context, result) : FiveError;
Parameter | Type | Description |
---|---|---|
five | FiveInstance | An instance of the Five object. |
context | Map<string,any> | Optional map of string to values. |
result | FiveError | A 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:
- Clicking the Add Item button to receive a new form.
Figure 1 - Add Item button
- Clicking the Add button on a subform.
Figure 2 - Sub-form Add button
- Selecting a saved form record.
Figure 3 - Form record
- Selecting a saved 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
- Select Forms in the menu.
- Select the required form record in the list.
- Click the Events tab.
- Click the Edit button in the form app bar.
- Use the lookup icon in the On Show field and select the required Function ID.
- Click the Save button in the form app bar.
Figure 5 - Attach a function to the On Show event