Events make Forms more dynamic. They allow you to run custom code, search other systems using bridges, and set fields with data when something happens on a Form.

Accessing Events

Events are available on almost all the different elements of a Form. Sections, HTML/text elements, and the preconfigured buttons (Save for Later, Submit, and Previous Page) are the exceptions. The location to find events is always the same: near the end of the Form Details pane.

Click on the Add Event button to open the event dialog.

Event Types

Not all event options are available for every element. For example, you shouldn't have a Submit event on an Attachment question. The Type of Event determines when the event is fired.

Here's a list of the types of events available for each Form Element:

Page & Confirmation Page

• Load
• Submit

Section

• No Events Available

HTML and Plain Text

• No Events Available

Custom Buttom (No other button has Events)

• Click

All Questions have a Change event type. While this is easy to see how it works with drop-down lists and radio buttons, questions like Attachments and Date/Time fields are a little trickier. The event is triggered on every change, so you need to use the Run If condition (see below) to monitor exactly when to fire the events. For example, you may not want to fire an event if the field value is null; or you may only want to fire the event if another question contains a specific value.

Event Actions

Unlike Types, there are opnly two options available to select when an Event fires, Custom and Set Fields.

Custom. Provides the opportunity to fire javascript. A field is provided with some basic formatting help. Optionally, you can call other available functions from your bundle.

Set Fields. Allows you to set a value to any existing question on the form. You have the option to use a bridge to collect the values, or you can use the standard set of variables provided. The variables provided include the values of the questions on the form, the form information, the identity information (for the logged in user when the even fires), the kapp and space information, etc.

Advanced Features

A couple of other features enhance Events usefulness. The first is the Run If condition. This feature lets you stop the event from firing if the condition evaluates to false.

The other feature is Bridge Resource. This option is often used with Set Fields events and can pull fields from an external source. The option can also provide data for tables or other custom javascript events.

Builder Defined Events

Page Load

The page load event happens after the bundle page load event as defined in the Ready Options (see below). Use this when you want to do something before the user interacts with the page.

Variables available to custom code by default:

• element - The page object
• event - Empty for page load events
• action - Contains no actions for page load events
• resource - Result of the bridged resource AJAX call if one was made

Page Submit

The page submit event happens before the page is submitted to the server.

Variables available to custom code by default:

• element - The page object
• event - Empty for page submit events
• action - Contains stop/continue methods that control timing of the form submission when event contains asynchronous functions, see example below
• resource - Result of the bridged resource AJAX call if one was made

Stop/Continue in submit events

In the example below we demonstrate how to use the stop and continue methods defined on the action object. Note that if you are using a bridged resource in a page submit event, these make asynchronous calls but we automatically stop and continue submission.

// signals that the submission process should stop/wait, forgetting this call
// will result in the form being submitted before the response is received 
action.stop();
// make the ajax call
$.ajax({
    url: '...',
    type: 'GET',
    success: function(data, textStatus, jqXHR) {
        console.log(data);
        // signals that the submission process should resume, forgetting this 
        // call will result in never submitting the form
        action.continue();
    }
});

Field Change

The field change events fire on changes to their data, not necessarily just changes to the input element by the user. If a field change event changes another field’s value, that field will also fire a change event if one is defined.

Variables available to custom code by default:

• element The field object
• event The event object contains the members listed below
  • newValue The new value of the field when the change event was triggered
  • constraints The field constraint messages after constraints are evaluated using the new value
• action Contains no actions for field change events
• resource Result of the bridged resource AJAX call if one was made

Button Click

The button click events can be defined on custom button elements and fire when the button is clicked.

Variables available to custom code by default:

• element The button object
• event The event object contains the members listed below
  • domEvent The original DOM event that resulted from the button click
• action Contains no actions for button click events
• resource Result of the bridged resource AJAX call if one was made