Perspective - Form

💡Have feedback for this page? Let us know on the IA Forum.

Component Palette Icon:

Description

The Form component is a versatile container for creating dynamic and responsive forms in Perspective. It simplifies collecting and validating user input, making it easy to create professional and interactive forms.

Key features include:

• Responsive Design: Automatically adapts layouts for different screen sizes.
• Validation Support: Provides built-in and custom validation rules.
• Flexible Layouts: Configure rows, columns, and widgets to meet your needs.
• Dynamic Visibility: Conditionally display or enable form elements based on user input.

Properties

Most properties support binding options. For more information, see Types of Bindings in Perspective.

Name	Description	Property Type
disabled	Disables all inputs and actions in the form. Default is false.	Boolean
readOnly	Sets all inputs to read-only. Inputs remain focused but cannot be edited. Default is false.	Boolean
columns	Array of column configuration objects defining the form structure. See the Columns Properties below for more detail on configuration options.	Array
actions	Configuration object for submit and cancel buttons, including text, style, and behavior settings. See the Actions Properties below for more detail on settings.	Object
context	Provides additional context for the form, including metadata and configurations.	Object
data	Stores user input values using unique widget IDs. Can be used to pre-fill fields dynamically.	Object
validation	Object containing live validation checks and fields in violation.	Object
style	Sets a style for this component. Full menu of style options is available for text, background, margin and padding, border, shape and miscellaneous. You can also specify a style class.	Object

Columns Properties

Columns define the overall structure of the form by organizing rows.

Name	Description	Property Type
align	Defines the horizontal alignment of row contents within the column.	String
justify	Determines how rows are spaced within the column.	String
visible	Controls whether the column is visible. Default: true.	Boolean
rows	An array of row objects that define the structure of the form. See the Rows Properties below for more information.	Array
style	Sets a style for this component. Full menu of style options is available for text, background, margin and padding, border, shape and miscellaneous. You can also specify a style class.	Object

Rows Properties

Rows group widgets inside a column, determining their layout and visibility.

Name	Description	Property Type
align	Defines the vertical alignment of widgets within the row.	String
justify	Determines how widgets are spaced within the row.	String
visible	Controls whether the row is visible. Default: true.	Boolean
enabled	Enables or disables user interaction with the row. Default: true.	Boolean
widgets	An array of widget objects contained within the row. See the Widgets Properties below for more information.	Array
style	Sets a style for this component. Full menu of style options is available for text, background, margin and padding, border, shape and miscellaneous. You can also specify a style class.	Object
visibleWhen	Defines a condition that determines when the row should be visible. If true, the row will be displayed.	Object
enabledWhen	Defines a condition that determines when the row should be enabled. If false, user input is disabled for all widgets within the row.	Object

Widgets Properties

Name	Description	Property Type
id	A unique identifier for the widget, used to reference it in scripts and bindings.	String
domID	The HTML id attribute applied to the widget for styling or scripting purposes. Optional.	String
type	The type of widget (e.g., text, number, email, dropdown, checkbox, button).	String
input	An object defining the input properties specific to the widget type.	Object
visible	Controls whether the widget is visible. Default: true.	Boolean
defaultValue	The initial value of the widget when the form loads.	Any
layout	Configuration settings that control how the widget is displayed within the row.	Object
label	The text displayed as the label for the widget.	String
info	Additional help text or tooltip for the widget.	String
validation	Validation rules for the widget, such as required fields or regex patterns.	Object
tabIndex	The tab order index for keyboard navigation. Default: 0.	Integer
style	Sets a style for this component. Full menu of style options is available for text, background, margin and padding, border, shape and miscellaneous. You can also specify a style class.	Object

Actions Properties

Actions define the behavior of the form's submit and cancel buttons.

Name	Description	Property Type
submit	Configuration for the submit action. Includes properties such as: disabled: A boolean defining the enabled state of the submit button. text: Button text. icon: Button icon configuration. style: Button style configuration object. fireComponentEvent: Triggers the onSubmitActionPerformed event when the button is pressed. fireSubmissionEvent: Sends the form data to a Form Submission Event for processing. autoDisable: Automatically enables or disables the button based on form validity and submission state. resetOn: Determines when the form resets, either with success or action. The success option resets the form on successful submission. The action option resets it immediately after submission. awaitResponse: When enabled, the form waits for a response before resetting. Only applicable when fireSubmissionEvent is true.	Object
cancel	Configuration for the cancel action. Includes properties such as: text: The text displayed on the cancel button. icon: The icon displayed on the cancel button. style: Defines the appearance of the cancel button using inline styles or CSS classes. fireComponentEvent: If true, triggers the onCancelActionPerformed event when the cancel button is clicked. disabled: If true, disables the cancel button, preventing user interaction. reset: If true, resets all form fields to their default values when the cancel button is clicked.	Object
disabled	Controls whether the action buttons are disabled. Default is false.	Boolean
fixed	When true, the action bar remains visible at the bottom of the form. Default is false.	Boolean
style	Sets a style for this component. Full menu of style options is available for text, background, margin and padding, border, shape and miscellaneous. You can also specify a style class.	Object

Scripting

See the Perspective - Form Scripting page for the full list of scripting functions available for this component.

Examples

Basic Form Layout with Validation

This example demonstrates a simple form layout consisting of a single column with multiple input fields, action buttons, and validation rules for required fields.

Property	Value
props.columns.items[0].rows.items[0].widgets[0].id	header
props.columns.items[0].rows.items[0].widgets[0].label.text	Simple Name and Address Entry Form
props.columns.items[0].rows.items[1].widgets[0].id	firstName
props.columns.items[0].rows.items[1].widgets[0].type	text
props.columns.items[0].rows.items[1].widgets[0].text.placeholder	Enter your first name...
props.columns.items[0].rows.items[1].widgets[0].label.text	First Name
props.columns.items[0].rows.items[1].widgets[1].id	lastName
props.columns.items[0].rows.items[1].widgets[1].type	text
props.columns.items[0].rows.items[1].widgets[1].text.placeholder	Enter your last name...
props.columns.items[0].rows.items[1].widgets[1].label.text	Last Name
props.columns.items[0].rows.items[2].widgets[0].id	email
props.columns.items[0].rows.items[2].widgets[0].type	email
props.columns.items[0].rows.items[2].widgets[0].text.placeholder	Enter your email...
props.columns.items[0].rows.items[2].widgets[0].label.text	Email Address
props.columns.items[0].rows.items[2].widgets[0].email.validation.pattern.enabled	true
props.columns.items[0].rows.items[2].widgets[0].email.validation.pattern.value	^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
props.columns.items[0].rows.items[2].widgets[0].email.validation.required.enabled	true
props.columns.items[0].rows.items[3].widgets[0].id	phoneNumber
props.columns.items[0].rows.items[3].widgets[0].type	tel
props.columns.items[0].rows.items[3].widgets[0].text.placeholder	Enter your phone number...
props.columns.items[0].rows.items[3].widgets[0].label.text	Phone Number
props.columns.items[0].rows.items[3].widgets[0].tel.validation.required.enabled	true
props.columns.items[0].rows.items[3].widgets[0].tel.validation.pattern.enabled	true
props.columns.items[0].rows.items[3].widgets[0].tel.validation.pattern.value	^\+?[1-9]\d{1,14}$