To perform any preliminary processing before the first page is displayed to the user e.g. load information from a database or some other external system.

Considerations:

There is no current page when this event runs, so any commands such as HIDE, SHOW etc which effect how a field is displayed must include the ON PAGE syntax.

This event runs when the user clicks the form’s finish button. All pages of the form will normally have been fully validated at this point. After this event completes, form execution is terminated and the form's final page is displayed.

Typical uses:

To perform any final processing: this might include inserting database records, sending emails, preparing messages to be displayed on the form's final page etc.

Considerations:

It is not possible to continue execution of the form after this event so, for example, commands such as GOTO PAGE cannot be issued. The form’s final page is the only page that can be displayed after execution of this event.

Execution of this event is linked to the use of a finish button. It should be noted that a form is not required to have a finish button, and there are many cases where it is more practical to perform any such “final” processing as a result of a normal page button e.g. button with text “Submit”.

On Error Event

When executed:

Whenever a error occurs while executing a form. If this event is not specified, the form will terminate and the standard form failure error page is displayed.

Typical uses:

To allow a form to “fail gracefully”; to route control to an error display page; possibly to continue form execution.

Considerations:

The following system variables are available in an on error event:

$ABORT_MESSAGE – contains the failure reason

$ABORT_PAGE – contains the name of the current page at the time of the failure. Note that this will contain null when there is no current page e.g. when a failure occurs during execution of a before or after form event.

Failures that occur during the execution of on error events will result in the display of the standard form failure error page.

Browser Back Button Event

When executed:

This event runs when the user clicks the browser back button and then clicks on a control (usually a button or hyperlink) from a previous page. See support for browser back button for further details.

Typical uses:

To reset any application flags.

Considerations:

See support for browser back button.

Integration Service Events

See Integration Server for details of events supported by an Integration Service.

Page Events

Before Page Event

When executed:

This event runs before each new page is displayed. It runs prior to displaying the first page of a form, and subsequently each time a user navigates to a page using the next page button or a page is displayed as a result of a GOTO PAGE command. It does not fire when the user returns to an earlier page using the previous page button.

Typical uses:

To perform any preliminary processing for the page e.g. loading database data, displaying or hiding fields, making fields display only or enterable etc.

Considerations:

It is possible for a page to have no displayable fields. In this circumstance, the page will not be displayed to the user, however the before and after page and any control field events will still fire in the appropriate sequence.

After Page Event

When executed:

This event runs when all fields on a given page have been successfully validated (see field validation event) and the user has clicked the next page button or the form’s finish button.

An exception to this occurs when the after page event for a page has already been executed and issued one or more warning messages. In this circumstance, if the user clicks again on the same next page button or the finish button and does not make any other changes to any field on the page, execution of the after page event is bypassed.

Typical uses:

To perform page level validation or cross field validation; to set the next page.

Considerations:

Previous Page Event

When executed:

This event runs when the user clicks the previous page button to return to the previous page.

Typical uses:

To perform field validation – field validation events are not executed when the user clicks the previous page button.

Considerations:

Warning messages should not be issued from this event. A warning message will not stop the re-display of the previous page; the message is only displayed when the user navigates back to the original page.

Field Events

Before Field Event

When executed:

This event runs when the page containing the field is displayed for the first time i.e. the event will only be fired once for each field. The event does not fire when a page is re-displayed - either paging forwards or backwards. Before field events are run immediately after the before page event, and are processed in the sequence that the fields appear on the page.

Typical uses:

To set an initial value for a field.

Considerations:

Please note that processing is different for control fields.

Validation Event

When executed:

This event runs whenever input is received from a page, the field has a value (i.e. it’s not null), the field is enterable (i.e. not display only) and visible (i.e. not hidden) and the system considers that the field is currently invalid. All fields are initially invalid – the status is only changed to valid when the field’s validation event executes successfully i.e. the event does not end by issuing an error message. Any subsequent change to the field value will result in the status being changed to invalid again – this includes all possible ways in which a field value might be set i.e. entered by the user, read from an external resource, set from a script, set from a dynamic list etc.

The events are processed in the sequence that the fields appear on the page. This process continues until either all fields on the page have been validated, a script issues an error message, or a field is reached where the user has clicked some type of immediate event: immediate validation, a button or a hyperlink.

If all fields on a page have been validated successfully and no immediate event has occurred, the page is marked as valid, the after page event is executed, and the system loads the next page.

When fields appear in a table, validation events run only for rows within the currently visible vertical set; however, validation events are run for all fields within the current horizontal set even though a field might only be visible to the user by scrolling horizontally. See table concepts for further details.

Typical uses:

To perform field validation.

Considerations:

A special case exists for fields which were hidden or display-only when page event processing started and are then dynamically changed to be visible and enterable using FPL commands; validation events are not executed in this circumstance. The converse is also true: validation events are executed for fields which were visible and enterable when page event processing started, even if they have been dynamically changed to be hidden or display-only.

Please note that processing is different for control fields.

On Click Event

When executed:

This event runs whenever a button or hyperlink field is clicked.

Typical uses:

To perform some sort of explicit task e.g. display detailed information, go to another page, insert a row in a table etc.

Considerations:

Any validation events for fields higher on the same page are run prior to executing an on click event.

The Ebase Designer allows configuration of on click events for all fields. This is to support the possibility that a field is dynamically changed to become a hyperlink using the SET FIELDNAME HYPERLINK command.

On Change Event

When executed:

This event runs whenever the value of an immediate validation field is changed by the user.

Typical uses:

To fetch additional information from a database; to hide or show subsequent fields on the page.

Considerations:

Any validation events for fields higher on the same page are run prior to executing an on click event.

This event should not be used to perform validation where error messages are issued to the user – use the validation event instead. The reason for this is that this event is only fired when the user changes the value of a field. It is not executed in any other circumstances e.g. when the user clicks the next page button. This issue is illustrated by the following example:

An order form contains a checkbox “Express Delivery” which is only valid when the order destination country is “US”. This is checked by a script on the onchange event of the immediate validation field EXPRESS_DELIVERY. The user clicks the checkbox with a destination country of “UK” and the script issues an error message; the user then clicks next page and is allowed to move to the next page, even though the EXPRESS_DELIVERY checkbox is invalid.

The solution to this problem is to move the validation scripts from the onchange event to the validation event.

This event can only be configured for fields with the immediate validation option.

Table Events

Before Table Event

When executed:

This event runs when the page containing the table is displayed for the first time i.e. the event will only be fired once for each table. The event does not fire when a page is re-displayed - either paging forwards or backwards. Before table events are run within the sequence of before field events.

Typical uses:

To load a table from a database or from an XML document; calculate totals fields etc.

Considerations:

After Table Event

When executed:

This event runs after all table cell validation events have been processed and after any table internal events such as sorting or scrolling have been processed.

Typical uses:

Can be used for any processing that needs to be performed against the table as a whole. This event is not commonly used.

Considerations:

Add Row Event

When executed:

This event runs when the user clicks the add row button of a table.

Typical uses:

To initialize values for the new row.

Considerations:

Control fields

Ebase supports two types of field: display fields (the default – normal fields), and control fields. The previous description of field events applies only to display fields. Control fields have the following characteristics:

· they are never displayed to the user

· before field events are always fired when moving forwards to a page via either the user clicking on a next page button or a goto page FPL command. Events are not fired when a page is re-displayed (e.g. with error messages) or when the user clicks the previous page button.

· validation events are always fired when input is received from the page (so long as event processing is not interrupted by an event earlier on the page e.g. issues an error message). A validation event on a control field might be used for validation across multiple fields.

The main purpose of control fields is to provide a mechanism whereby a script is always executed at a certain point in the processing regardless of whether input has been received from the user. One use for this type of processing is for validating multiple fields that need to be validated as a group.

Ebase validation concepts

Validation of input data entered by the user is performed using a mixture of client side and server side validation, and a mixture of system supplied validation and validation provided by the form designer. As each page is submitted by the user, the following processing is performed:

Client Validation:

Client-side system supplied validation processing is only performed when Javascript is enabled. This includes:

· Checking for mandatory fields

· Checking data entered is appropriate for the field type

· Checking data entered against any system validators configured for client validation

If client validation fails, an error message is issued and the field in error is highlighted.

When client validation is successful the page is submitted to the server.

Server Validation

Server-side validation is performed in the following sequence:

Firstly, when Javascript is disabled, the system checks for missing mandatory fields and input data that does not match each field type.

Then any system validators configured for server validation are run for all fields on the page. If any of these system validators fail, an error message is issued to the user and no further processing is performed.

Secondly, all fields requiring validation are then validated in the sequence that they appear on the page by:

· checking entered data against a list (if applicable)

· executing any validation scripts

At the start of each form execution, all pages and all fields on all pages are marked as invalid and therefore require validation. As each field is validated, it will retain its invalid status only when:

· an entry is not found in a list (if applicable) or

· an error message (message type 'E') is issued by a script associated with the validation event for the field

When either of these two conditions occurs, processing is stopped immediately and control is returned to the end-user displaying the error message. Otherwise the field is marked as valid.

The system continues processing all fields on the page in sequence until all fields have been validated. The page itself is then marked as valid and the system proceeds to the next page (or the end of the form if there are no more pages).

If the user clicks the previous page button, the current page and all fields on the current page are marked as invalid. This is because the user (or a script) may change data on a previous page that could affect the validity of fields on the current page.

Adding and removing scripts from events

As each event occurs, the system will run all the scripts associated with the event in the order that they have been specified (so long as processing is not interrupted e.g. by issuing an error message or a GOTO command). Associating a script with an event or removing a script from an event is done using the events tab of the properties of either the form, page, or field-on-page, or in some cases by right clicking and selecting Edit actions. This brings up the events dialog as shown below.

Initially, the default event for the element is displayed. Other events can be displayed by clicking on the appropriate tab key. A superscripted * character to the right of the event name indicates that at least one script is configured for the event. The sequence of script execution can be altered by selecting a script and clicking on the and icons.

Scripts can be added and removed by clicking on the Add and Delete buttons underneath each The Add button will present a list of all available scripts – firstly all scripts within the project are displayed, followed by all scripts in the shared GLOBAL project.

Clicking the wizard icon presents a dialog that can be used to automatically create scripts for some common functions as shown below:

Displaying all events for a form or component

A map of all events for a form or component can be displayed by clicking on the display event map icon or Selecting Tools --> Display Event Map from the Form Editor. This opens the References panel which is displayed display underneath the tree.