Perspective - Form Scripting
This page details the various scripting, component, and extension functions available for Perspective's Form component. Scripting allows you to customize form behavior, handle validation dynamically, and respond to user actions.
Component Events​
The Perspective Event Types Reference page describes all possible event types for Perspective components. Not all event types apply to every component. For more information on configuring events, see Component Events and Actions.
onChange​
This event triggers whenever a form's input value changes.
Properties​
| Property | Type | Description |
|---|---|---|
| event.inputKey | String | The unique key identifying the input that triggered the change. |
| event.newValue | Object | The new value of the input after the change. |
| event.oldValue | Object | The previous value of the input before the change occurred. |
| event.index | Integer | The index of the input if multiple inputs share the same key, such as in a repeater or table. Optional. |
onSuccess​
This event triggers when a form submission completes successfully.
Properties​
| Property | Type | Description |
|---|---|---|
| event.response | Object | The success response object returned after submission. |
See Form Submission for handling form data on submission.
onError​
This event triggers when a form submission fails.
Properties​
| Property | Type | Description |
|---|---|---|
| event.errorMessage | String | A detailed error message describing the issue. |
| event.errorCode | Integer | A numeric code identifying the type of error. |
| event.response | Object | The full error response object returned from the submission. |
See Form Submission for handling errors.
onCancelActionPerformed​
This event triggers when a form's cancel action is performed.
Properties​
| Property | Type | Description |
|---|---|---|
| event.formContext | Object | The context of the form at the time of cancellation. |
| event.sessionContext | Object | Information about the session, including user and device data. |
| event.timestamp | Long | The timestamp of when the cancel action occurred. |
onSubmitActionPerformed​
This event triggers when a form's submit action is performed.
Properties​
| Property | Type | Description |
|---|---|---|
| event.data | Object | A dictionary containing all form input data to be submitted. |
| event.formContext | Object | The context of the form at the time of submission. |
| event.sessionContext | Object | Information about the session, including user and device data. |
| event.timestamp | Long | The timestamp of when the submit action occurred. |
Component Functions​
.setCustomValidity(inputKey, message, index)​
Description​
Sets a custom validation message for a specific input field in the form.
Parameters​
| Parameter | Type | Description |
|---|---|---|
| inputKey | String | The unique key identifying the input field. |
| message | String | The custom validation message to display for this input. |
| index | Integer | The index of the input if multiple inputs share the same key. Optional. |
Return​
None
Example​
To set a custom validation message for an email input field:
self.getSibling("Form").setCustomValidity("email", "Please provide a valid email address.")
This message will persist until the field is corrected or the form is reset.
.reset()​
Description​
Resets all form inputs to their default values.
Parameters​
None
Return​
None
Example​
To reset the form inputs to their default state:
self.getSibling("Form").reset()
.submit(preventInvalid)​
Description​
Submits the form, triggering onSuccess if successful or onError if submission fails.
Parameters​
| Parameter | Type | Description |
|---|---|---|
| preventInvalid | Boolean | When true, prevents the form from submitting if it is invalid. Optional. |
Return​
None
Example​
To submit the form with validation check enabled:
self.getSibling("Form").submit(preventInvalid=True)
Extension Functions​
This component does not have any extension functions associated with it.