Forms › The Form Designer › Form Element Events

Form Element Events

onBlur

Occurs when a form element loses focus. For example, a form contains a User Name field. A user establishes focus in the field by tabbing to it or clicking it. The onBlur event occurs when the user takes either of the following actions:

• The user clicks another object or clicks another window.
• The user presses the Tab key to navigate to the next field (for example, the Password field).

onChange

Occurs when a form element loses focus and the new value of a form element is different from its old value. For example, a form contains a field named Quantity with a value of 10. After the user changes the value to 15, the user does not move focus to another field. The onChange event occurs only after the user takes either of the following actions:

• The user clicks another object or clicks another window.
• The user presses the Tab key to navigate to the next field.

onClick

Occurs when a user clicks a form element. A valid click includes both the onMouseDown and onMouseUp events on the same object. This requirement helps prevent calling functions or other code accidentally because the mouse must remain on the clickable object.

onFocus

Occurs when a form element receives focus. To establish focus, a user tabs to or clicks a form element. You can also write scripts or code to establish focus in a form element.

onKeyDown

Occurs when a user first presses a key down (for example, when a user tabs to or clicks a Name field). A script that is associated with the onKeyDown event for the Name field alerts users when they attempt to type number keys.

onKeyPress

Occurs after a user presses a key down and continues to hold the key down. For example, the onKeyPress event occurs after a user tabs to or clicks a Select field called Name and presses some key representing an alphabet. A script that is associated with the onKeyPress event for the Name field cycles through names that match the pressed alphabetic key.

onKeyUp

Occurs when a user releases a key after pressing it down. For example, the onKeyUp event occurs when a user tabs to or clicks a Spinner field named Temperature. A script that is associated with the event increases or decreases the field value each time the user presses and releases a specific key.

onLoad

Occurs when the form first opens for the user to complete.

onLookup

Occurs when a user clicks Browse in a Lookup field to view values that are calculated (or "looked up" as directed by the script) based on other field values.

onMouseDown

Occurs when a user presses the left mouse button down on a form element.

onMouseMove

Occurs when a user moves the mouse pointer inside the boundary of a form element.

onMouseOut

Occurs when a user moves the mouse pointer outside the boundary of a form element.

onMouseOver

Occurs when a user moves the mouse pointer over a form element and the user stops moving the mouse.

onMouseUp

Occurs when a user releases the left mouse button after pressing the mouse button down on a form element.

onMouseWheel

Occurs when a user with a wheel-equipped mouse rolls the wheel forward or backwards to scroll a form element.

onSubmit

Occurs when the user submits the form. Any of the following actions can submit the form:

• The user clicks a Submit button.
• The user presses a specific key or combination of keys.
• The value of a field changes.
• The user reaches the end of the form in the tab order.

onValidate

Occurs when the associated code verifies a field value against business rules before one of the following actions occurs:

• The field value is stored in the data buffer.
• The field value is written to the database.

For example, the user tabs to or clicks a Serial Number field that must start with the letters SN and contain 10 numeric digits. Before the user can tab to the next field or click away from the field, the onValidate event and its associated code verify the data. You can alert the user if the serial number does not meet validation rules so they can adjust their entry.

You can use onValidate for custom validation of the field input. For example, to ensure that a field input is at least three characters in length, you can write a custom function in the Script dialog:

validateValue:function(_val) {

if(_val.length < 3) {
return "Please enter more than 3 characters for this field";
} else {
return null;
}

In the Form Designer, include the onValidate attribute value for the text field on which to run the validation. For example:

ca_fd.js.validateValue(_val)

The custom function replaces the required parameter _val with the correct field value when the script runs.

If the validation script returns a null value, the field input passes validation. Otherwise, the field input fails validation and the script returns an error (for example, "Enter more than 3 characters for this field").