Created by

The FormEvent object is a top-level, predefined MetaScript object. You can automatically access it without using a constructor or calling a method.

Description

The FormEvent object is designed to allow event listeners in MetaScript 2.x to access the events that caused them to be executed. The top-level FormEvent object always refers to the most recent event fired for the form.

Form events are distinct from form control events: each form control event is local to a particular form control, while form events represent events that affect the entire form (for example, the loading of a Virtual Ticket object for display in the form). For information on handling form control events, refer to the description of the Event object.

Property Summary

Method Summary

Event Types

List of all form event types by category:

Event Type	Cancelable	userData	Description
Form Loading
"loadForm"			Sent immediately after form is loaded.
Object Creation / Loading
"newObject"	yes		Sent before a new object is created.
"loadObject"	yes	present	Sent right before existing object is loaded. Not sent on creation of new objects.
"objectLoaded"		present	Sent immediately after "loadObject". Good place to setup controls and variables that depend on the object state.
"objectUnloaded"			Sent immediately after object is unloaded. New in package 164
"objectSet"		present	Sent immediately after "objectLoaded", "newObject", "attach", "modify", "newTemplate" and "templateLoaded" events. New in package 164
Object Editing
"editObject"	yes		Sent after "objectSet" and before editing of an existing object is started, i.e. before "editingStarted".
"startEditing"
"editingStarted"		present
"editingFinished"
"cancelEditing"	yes
"okEditing"	yes
Object Saving
"saveObject"	yes
"meta_objectSaved"			Deprecated, not available in Form API version 2.3 or greater.
Object Deletion
"meta_okDeleting"	yes		Internal, subject to change.
"meta_deleteObject"	yes		Internal, subject to change.
"meta_beforeObjectDeleted"	yes		Internal, subject to change.
"meta_objectDeleted"	yes		Internal, subject to change.
User Input
"elementChanged"			The value of a form field has changed.
"propertiesChanged"			The document's properties have been changed using the Properties window.
Attach / Modify
"attach"	yes
"modify"	yes
Templates
"newTemplate"	yes
"loadTemplate"	yes
"templateLoaded"	yes
"editTemplate"	yes
"saveTemplate"	yes
"meta_templateSaved"

Event Sequences

Form.object property is re-assigned a new FormObject instance before dispatching any event that witnesses Form.objectState's transition from "none" to "new" or "existing" state.

Creation of a new object (New button)

Changing properties of a new object (Properties button, object is not added to the database yet)

Adding newly created object to the database (Add button)

	Event.type	Form.mode	Form.objectState	Event.cancelable	Notes
↪	"okEditing"	"edit"	"new"	true
↪	"saveObject"	"edit"	"new"	true
↪	"meta_objectSaved"	"edit"	"new"	false	Deprecated, not available in Form API version 2.3 or greater.
↪	"editingFinished"	"show"	"new"	false

↪ Newly added object is unloaded and re-loaded anew.

Canceling creation of a new object (Cancel button)

↪ The object is unloaded and previously loaded existing object is re-loaded.

Loading of an existing object

Unloading of an object

Starting editing of an existing object (Edit button)

Changing properties of an existing object (Properties button, during editing)

Updating of an existing object (Update button)

	Event.type	Form.mode	Form.objectState	Event.cancelable	Notes
↪	"okEditing"	"edit"	"existing"	true
↪	"saveObject"	"edit"	"existing"	true
↪	"meta_objectSaved"	"edit"	"existing"	false	Deprecated, not available in Form API version 2.3 or greater.
↪	"editingFinished"	"show"	"existing"	false

↪ The object is unloaded and loaded anew.

Canceling editing of an existing object (Cancel button)

↪ The object is unloaded and loaded anew.

Form closing

Examples

Using FormEvent.type property

The following code illustrates the use of the FormEvent.type property in an event listener:

Handling "elementChanged" event

If the below code is added into the Global MetaScript for a form, an alert will appear if the "Job Name" field is changed when a Job document is edited using that form.

See also

Form.addEventListener