---
title: "Perspective - Form Scripting"
---

# Perspective - Form Scripting

> This page details the various scripting, component, and extension functions available for [Perspective's Form](perspective-form.md) component. Scripting allows you to customize form behavior, handle validation dynamically, and respond to user actions.

## Component Events

The [Perspective Event Types Reference](appendix/reference-pages/perspective-event-types-reference.md) 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](ignition-modules/perspective/working-with-perspective-components/component-events-and-actions.md).

### 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        | Object   | The success response object returned after submission. |

See [Form Submission](ignition-modules\perspective\scripting-in-perspective\perspective-session-events-scripts.md#form-submission) for handling form data on submission.

### onError

This event triggers when a form submission fails.

#### Properties

| **Property** | **Type**   | **Description**                                              |
|--------------|------------|--------------------------------------------------------------|
| event        | Object     | The error response object returned from the submission.      |

See [Form Submission](ignition-modules\perspective\scripting-in-perspective\perspective-session-events-scripts.md#form-submission) for handling errors.

### onCancelActionPerformed

If configured, this component event fires when the Form's cancel action is clicked.

#### Properties

| **Property** | **Type** | **Description** |
|--------------|------------|---------------|
| event | Object |  A JSON object containing all form input data to be cancelled. |

### onSubmitActionPerformed

If configured, this component event fires when the Form's submit action is clicked.

#### Properties

| **Property** | **Type** | **Description** |
|--------------|------------|---------------|
| event | Object |  A JSON object containing all form input data to be submitted. |

## Component Functions

### .setCustomValidity(message, inputKey, index)

#### Description

Sets a custom validation message for a specific input field in the form.

#### Parameters

| **Parameter**   | **Type**   | **Description**                                                      |
|------------------|------------|----------------------------------------------------------------------|
| message        | String     | The custom validation message to display for this input.            |
| inputKey       | String     | The unique key identifying the input field.                         |
| 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:  

```python
self.getSibling("Form").setCustomValidity("Please provide a valid email address.", "email")
```

:::info
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:

```python
self.getSibling("Form").reset()
```

### .submit(preventInvalid)

#### Description

Submits the form, triggering [onSuccess](#onsuccess) if successful or [onError](#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:

```python
self.getSibling("Form").submit(preventInvalid=True)
```

## Extension Functions

This component does not have any extension functions associated with it.