Developer JavaScript API : Knowledge Base

NOTE: The Formulayt developer JavaScript API is a beta feature. As such it is subject to change with no notice, and may contain unstable features. Please report any bugs that you find.

The Formulayt script dispatches various custom window-level events through it's life cycle. You can bind to these events to implement your own custom, on-page logic. This functionality can be utilised to do things like:

Change the value of fields on a form on the basis of custom business logic
Perform a custom action on the page on a form load or form submit
Change the available options within a dropdown based on external data

An example of how to bind to a Formulayt event is shown in the code below. NOTE: Your code MUST be executed BEFORE the Formulayt script loads and begins to execute. This can normally be achieved by placing your code inline on the page.

// Bind to the Formulayt script setup complete event
window.addEventListener('gcdcSetupComplete', function(event){
	var gcdcObj = event.detail;

	// Take some action here
});

// Bind to the Formulayt gate ready event
window.addEventListener('gcdcGateReady', function(event){
	var gateInstance = event.detail;
	
	// Take some action here
});

Available events

The following table lists the complete set of custom events you can attach listeners to:

Event name	Trigger	Can fire multiple times	Value of event.detail
gcdcSetupComplete	Fires once when the Formulayt script has finished setting up, but BEFORE any gates have been initialised.	N	The main Formulayt object in browser memory. Use this to interact with the Formulayt on-page application.
gcdcGateReady	Fires every time a gate has finished building.	Y	The gate instance which has loaded. Use this to interact with the gate and it's form.
gcdcGateSubmit	Fires every time a form is about to submit. This event fires AFTER successful validation, but BEFORE any data leaves the page.	Y	The gate instance which is about to submit. Use this to interact with the gate and it's form.
gcdcGateSubmitted	Fires every time a form has submitted. This event fires AFTER submission has completed and data has left the page.	Y	The gate instance which has submitted. Use this to interact with the gate and it's form.
gcdcModalOpened	Fires every time a Formulayt modal opens.	Y	The main Formulayt object in browser memory. Use this to interact with the Formulayt on-page application.
gcdcModalClosed	Fires every time a Formulayt modal closes.	Y	The main Formulayt object in browser memory. Use this to interact with the Formulayt on-page application.

Retrieving a gate AFTER it has finished loading

If you are unable to use the above window-level events, for example if your code will be running after Formulayt gates have finished loading, then you can retrieve a gate with a specific ID from the page using the below code. Note that this approach will not work if it is used before gates have finished being setup up.

// Get a specific gate by ID AFTER it has finished loading
gcdc('getGateByID', 'a123a-a123a-a123a-a123', 
  function(gateInstance){
    // Do something with this gate...
  });

Useful properties and methods

The following code samples demonstrate some useful methods you can use to interact with gates from within a gcdcGateReady, gcdcGateSubmit or gcdcGateSubmitted event listener. Each of these examples assumes you have assigned the value of event.detail to a local variable called gateInstance, as shown in the example code above.

Gate ID

This is useful if you have used the window-level events to retrieve gates, and you only want to work with particular gates.

// Get the ID of a gate
gateInstance.id;

// You can use this to check if this is a specified gate:
if (gateInstance.id === "a123a-a123a-a123a-a123") {
    // Do something with this gate...
}

Gate methods

// Check if a gate is currently open; returns true or false
gateInstance.gateOpen();

// Get a config attribute from the gate, e.g. gateType
gateInstance.getConfigAttribute('gateType');

// You can retrieve any gate attribute that can be set in the gate 
// editor, e.g. formType, lang, downloadUrl etc.
gateInstance.getConfigAttribute('formType');

// Make a modal gate open now 
// (NOTE - this will only work with gates embedded using the modal gate method)
if (gateInstance.isModal) {
    window.gcdc.Modules.UI.openModal(gateInstance.wrapperElem);
}

Form methods

// Request fields by their Formulayt ID. Field IDs are listed in the admin area.
// This is normally, but not always, the same as the field's HTML name.
gateInstance.form.getFieldById("email");

// Loop through every field on the form to do something with each one
gateInstance.form.eachField(function(field){
    // Do something with field here
});

Field methods

Note that you should always interact with fields via Formulayt methods where available, especially when setting or getting values. If you do this directly using the native javascript .value property, Formulayt will not be able to track the value of the field which may result in unexpected behaviour on the page. Importantly, you should avoid directly manipulating the underlying DOM element for the field, as this can cause unexpected bugs.

// Let's get a field to work with...
var emailField = gateInstance.form.getFieldById("email");

// Get the current value of this field
emailField.getValue();

// Set a new value for this field. The second parameter causes any rules watching
// this field to update and should normally be set to true
emailField.setValue("a new value", true);

// Check or uncheck the field if it is a checkbox
var optinCheckboxField = gateInstance.form.getFieldById("optinCheckbox");
optinCheckboxField.check(true);
optinCheckboxField.uncheck(true);

// Change the options for a select field
var industryField = gateInstance.form.getFieldById("industry");
industryField.setOptions([
	{
		value: "option1", //the html value for this option
		description: "Option 1" // the label displayed to the user
	},
	{
		value: "option2",
		description: "Option 2"
	},
	{
		value: "option3",
		description: "Option 3"
	}
]);

// Show or hide a field - note that rules can override this
emailField.hide();
emailField.show();

email.hidden; // <- This indicates if the field is currently hidden or not. This includes cases where the field is on a multistep form but is not displayed on this step, conditions, switchable fields etc.

// Get DOM elements associated with the field
emailField.elem; // <- This is the wrapping DIV element that contains the field, it's label, and any associated elements
emailField.inputElem; // <- This is the actual field input element
emailField.labelElem; // <- This is the field's label element

Working with JS objects retrieved within the event manager

The above method examples are primarily written for on-page JS that is using our JS API. However, the same methods are available when working with data sources within the event management area that return a JS object. The example below demonstrates two scenarios in this context:

// Loop through every field on the form to do something with each one
var gateInstance = gcdc.getValue("gateAttribute.gateObj");
gateInstance.form.eachField(function(field){
    // Do something with field here
});

// Let's get the label of the last field that the user interacted with
var field = gcdc.getValue("formAttribute.lastInteractedFieldObject");
var fieldLabelText = field.labelElem.innerHTML;

Developer JavaScript API Print