Adaptive Forms

Class: GuideBridge

GuideBridge

new GuideBridge()

GuideBridge provides an interface using which, wrapper html (page hosting/embedding adaptive forms) or external window scripts like Parent window javascript (in case form is embedded in an iframe), can communicate with current Adaptive Form and manipulate or query it's current state.

Some of the use cases for using this API

  • Submit Adaptive Form from a custom button present outside the Form.
  • Get current Adaptive Form state and save it in local storage for restoring it later on.
  • Plugging in custom widgets.
  • Manipulate the Adaptive Form component properties, like value, visibility from outside the Form
  • Listen to bridge events and send data to Analytics server for reporting

Accessing the Instance of GuideBridge

To access the GuideBridge APIs, one needs to get hold of an instance of GuideBridge. The object is available on the window after the GuideBridge script is loaded. One can directly access it by using window.guideBridge. But that requires the user script is written after the GuideBridge script is loaded. In certain cases, a user might not be aware of when their script gets loaded, in those cases the recommended approach is to listen to the bridgeInitializeStart event which provides an instance of GuideBridge object.

window.addEventListener("bridgeInitializeStart", function(evnt) {
     // get hold of the guideBridge object
     var gb = evnt.detail.guideBridge;
})

Or, if you are sure that your script will execute after GuideBridge Script is loaded, then you can directly use window.guideBridge. In cases like your script is present at the bottom of the page or you are executing on jquery dom ready event.

   $(function () {
         // one can directly access guideBridge object here.
         window.guideBridge.connect(function () {
             //call guideBridge APIs
         })
   })

Wait for Form to get ready

After getting the GuideBridge object one needs to wait for the Form to get initialized. This can be done by providing a callback to the connect API

guideBridge.connect(function (){
   //this callback will be called after adaptive form is initialized
   // do your custom processing
})

Note: There is no link between Dom ready events and the connect API. If one wants to access the HTML DOM from inside the connect callback, the recommended approach is to listen on the jQuery ready event or the native DOMContentLoaded event. Similarly if one wants to access GuideBridge APIs one needs to wait for the connect callback to get fired.

Using the GuideBridge API

APIs are provided for external applications to connect with Adaptive Form and FormDom. The APIs can be loosely divided into two categories, synchronous and asynchronous.

The synchronous getter API returns a GuideResultObject which represents the result of the API whereas each setter API throws an exception in case of error(s) and it is the responsibility of the API to catch those exceptions. The GuideResultObject either contains error or the return value of the API and provides easy mechanism to access each of them.

var result = guideBridge.hideGlobalToolbar()
if (result.errors) {
    console.error("Unable to hide toolbar");
    var msg = guideResultObject.getNextMessage();
    while (msg != null) {
        console.error(msg.message);
        msg = guideResultObject.getNextMessage();
   }
} else {
     console.log("toolbar hidden successfully");
}

Each asynchronous API provides callback mechanism to return the result of the API. Each API takes a Javascript Object having success and error handlers. The success and error handlers receive GuideResultObject as input. In the success callback, the arguments data property is set to the return value of the API, while in the error callback the errors property is set to true. Some APIs might need extra input and that will be defined by the API

guideBridge.getData({
    success : function (guideResultObject) {
         console.log("data received" + guideResultObject.data);
    }
    error : function (guideResultObject) {
         console.error("API Failed");
         var msg = guideResultObject.getNextMessage();
         while (msg != null) {
             console.error(msg.message);
             msg = guideResultObject.getNextMessage();
         }
    }
});

Note: Some APIs do not follow the above norm and it is mentioned in the documentation of that API

GuideBridge Events

GuideBridge API triggers a set of events to notify the current action a user has taken. Developers can listen on that event using the on API and perform some tasks. For example a developer can listen on elementFocusChanged and capture for how long a user spends time on that field. All the events triggered by GuideBridge are mentioned below.

GuideBridge provides an event object which contains extra information about the event. For example elementFocusChanged event provides information about the previous field that was in focus and the current field that came to focus.

The on API takes a GuideBridgeEventCallback as input. The callback is passed two arguments, event and payload where the extra information is passed in the payload argument. The documentation of each event lists the values of different properties of the payload object.

guideBridge.on(eventName, function (event, payload) {
     // access payload properties
     ...
})
Since:
  • 6.0

Methods

isConnected()

Whether the Adaptive Form has been initialized or not

All GuideBridge APIs (except connect) require Adaptive Form to be initialized. Checking the return value of this API is not necessary if guideBridge API is called only after the Form is initialized

Since:
  • 6.0
Returns:

true if the Adaptive Form is ready for interaction, false otherwise

Type
boolean

connect(handler [, context])

Register a callback to be executed when the Adaptive Form gets initialized

Specify a callback function which is called/notified when Adaptive Form gets initialized. After Adaptive Form is initialized GuideBridge is ready for interaction and one can call any API.

The callback can also be registered after the Form gets initialized. In that case, the callback will be called immediately.

Parameters:
Name Type Argument Description
handler function

function that would be called when guideBridge is ready for interaction. The signature of the callback should be

function() {
    // app specific code here
}
context object <optional>

this object in the callback function will point to context
Since:
  • 6.0
Example
guideBridge.connect(function() {
   console.log("Hurrah! Guide Bridge Activated");
})

getBridgeVersion()

returns the version of GuideBridge library

Since:
  • 6.0
Returns:

the version of the GuideBridge library

Type
string

registerConfig(key [, config])

Registers user/portal specific configurations to GuideBridge

Adaptive Form uses some default named configurations to provide its default behaviour. This configurations can be modified by providing a new configuration.

The API accepts the name of the configuration and updated configuration. Based on value of the new configuration the behaviour of the Form gets changed. Currently supported configurations are:

postExternalMessageConfig

Deprecated : since 6.2 this configuration is deprecated. Use the GuideBridge.events:bridgeInitializeStart event to do the same handling
In case Adaptive Form is embedded inside an iframe, this configuration allows developers to provide GuideBridge Instance to parent or child windows.

By default, GuideBridge instance is only available to the current window and to the parent window if it doesn't violate the cross-origin policy. Now there may be a case when this doesn't solves the problem, then one can take advantage of this configuration to extend this functionality.

For the signature of the configuration see postExternalMessageConfig

Example

To provide the GuideBridge instance to a child window

window.on("bridgeInitializeStart", function (evnt) {
     var gb = evnt.detail.guideBridge;
     gb.registerConfig("postExternalMessageConfig", {
         "postExternalHandler" : function(data) {
             // assume we have a child window with an id 'childWindowId'
             var childWindow = document.getElementById("#childWindowId").contentWindow;
             var tmpEvent = document.createEvent("CustomEvent");
             tmpEvent.initCustomEvent(data.name, true, true, data.data);
             childWindow.dispatchEvent(tmpEvent);
         }
     });
});

widgetConfig

The configuration is used to modify the appearance of a specific Field. Adaptive Form allows developers to create custom widgets and use them in their Forms.

The signature of the config is

{ "<component-identifier> : "<widget-name>"}

where <component-identifier> can be either the name or classname of Adaptive Form Field, while widget name is the name of the jQuery Widget.

submitConfig

To modify the default submit behaviour one can provide this configuration. The signature of the config is defined below

guideBridge.registerConfig("submitConfig", {"useAjax" : true});
Parameters:
Name Type Argument Description
key string

configuration name. one of the following

  • postExternalMessageConfig
  • widgetConfig
  • submitConfig
config widgetConfig | GuideBridge~submitConfig | GuideBridge~postExternalMessageConfig <optional>

configuration object for the configuration
Since:
  • 6.0
Returns:

GuideResultObject with data having the old configuration against the same key

Type
GuideResultObject

setProperty(somList, propertyName, valueList)

Modify a property for a set of Nodes

Sets the value of a property for a set of GuideNode to a different value. Property must be a valid writable property for that Node

Each entry in somList should have a corresponding entry in the valueList. Mismatch in the length of these two arguments will make the function do nothing

Parameters:
Name Type Description
somList Array.<string>

an array having someExpression for the nodes. Invalid SomExpressions and the corresponding value in the valueList are ignored.
propertyName string

name of the property which has to be modified
valueList Array.<*>

an array containing value of the propertyName for each element in somList
Since:
  • 6.0
See:
Examples

Modifying the value of a set of fields

guideBridge.setProperty(["SOM_OF_FIELD_1", "SOM_OF_FIELD_2"...... "SOM_OF_FIELD_N"]
                         "value"
                         [VALUE_1, VALUE_2 .... VALUE_N]);

Hiding a single field

guideBridge.setProperty(["SOM_OF_FIELD_1"]
                         "visibility"
                         [false]);

getDataXML(options, options)

Return Form data as XML.

Used to retrieve the Form data as XML. The API gets the data xml synchronously/asynchronously based on the async option and invokes the success/error handlers passed in the arguments upon completion.

In the success callback the data parameter contains the xml string.

The success and error handlers receive GuideResultObject as input.

Parameters:
Name Type Description
options object

input to the getDataXML API

Properties
Name Type Argument Default Description
success function <optional>

callback which receives the result of the API in case of success.
error function <optional>

callback which receives the result of the API in case of failure. errors property as true.
context object <optional>

this object inside the success and error callback will point to this object
async boolean <optional>
 true

whether to make the server call asynchronously or not. If false, the browser will wait for the server to return the XML and then execute the success or error callbacks object
options
Since:
  • 6.0
Deprecated:
  • since 6.3 this API is deprecated. Use getData API instead.
See:
Example
guideBridge.getDataXML({
    success : function (guideResultObject) {
         console.log("xml data received" + guideResultObject.data);
    }
    error : function (guideResultObject) {
         console.error("API Failed");
         var msg = guideResultObject.getNextMessage();
         while (msg != null) {
             console.error(msg.message);
             msg = guideResultObject.getNextMessage();
         }
    }
});

getData(options)

Return Form data as XML or JSON depending on the Schema Type.

Used to retrieve the Form data as XML or JSON depending on the Schema Type. Only for JSON Schema based Forms and Form Data Model based forms, the data will be in JSON format while for others, the data will be in XML format. The API gets the data synchronously/asynchronously based on the async option and invokes the success/error handlers passed in the arguments upon completion.

In the success callback the data parameter contains the data string.

The success and error handlers receive GuideResultObject as input.

Parameters:
Name Type Description
options object

input to the getData API

Properties
Name Type Argument Default Description
success function <optional>

callback which receives the result of the API in case of success.
error function <optional>

callback which receives the result of the API in case of failure. errors property as true.
context object <optional>

this object inside the success and error callback will point to this object
async boolean <optional>
 true

whether to make the server call asynchronously or not. If false, the browser will wait for the server to return the data (XML or JSON) and then execute the success or error callbacks object
Since:
  • 6.3
Deprecated:
  • use GuideBridge#getFormDataString instead
See:
Example
guideBridge.getData({
    success : function (guideResultObject) {
         console.log("data received" + guideResultObject.data);
    }
    error : function (guideResultObject) {
         console.error("API Failed");
         var msg = guideResultObject.getNextMessage();
         while (msg != null) {
             console.error(msg.message);
             msg = guideResultObject.getNextMessage();
         }
    }
});

hideSubmitButtons()

Hides all the submit buttons present in the Adaptive Form

Since:
  • 6.0
Returns:

the data property of GuideResultObject would be undefined. The API will fail if the Form is not initialized which would be indicated by the errors property.

Type
GuideResultObject

getGlobalMetaInfo()

this API returns the globalMetaInfo stored in global context (in globalMetaInfo tab).

Deprecated:
  • since 6.3
Returns:
Type
object

hideFileAttachmentListingButtons()

Hides all the file attachment listing buttons present in the Adaptive Form

Since:
  • 6.0
Returns:

the data property of GuideResultObject would be undefined. The API will fail if the Form is not initialized which would be indicated by the GuideResultObject#errors property.

Type
GuideResultObject

hideFileAttachments()

Hide all the File Attachment component present in the Adaptive Form

Since:
  • 6.0
Returns:

the data property of GuideResultObject would be undefined. The API will fail if the Form is not initialized which would be indicated by the GuideResultObject#errors property.

Type
GuideResultObject

hideGlobalToolbar()

Hides the global toolbar of the Adaptive Form.

Since:
  • 6.0
Returns:

the data property of GuideResultObject would be undefined. The API will fail if the Form is not initialized which would be indicated by the GuideResultObject#errors property.

Type
GuideResultObject

hideSaveButtons()

Hides all the save buttons present in the Adaptive Form

Since:
  • 6.0
Returns:

the data property of GuideResultObject would be undefined. The API will fail if the Form is not initialized which would be indicated by the GuideResultObject#errors property.

Type
GuideResultObject

getElementProperty(options)

returns the value of a specific property for a set of Adaptive Form Components

The API can be used to retrieve the value of a specific property for a list of AF components. If the property doesn't exists for a component then the corresponding value in the resulting array will be null.

The data element of the return object will be an array containing the values of the property for each component in the list of components

The API fails if the Form is not initiailzed

Note: If a somExpression provided doesn't points to a valid GuideNode null is returned for that element and an error message is added in the returned object

Parameters:
Name Type Description
options object

input object containing the propertyName and the list of components

Properties
Name Type Description
propertyName string

name of the property whose value has to be returned
somExpression Array.<string>

list of somExpression of the components for which the value is to be returned.
Since:
  • 6.0
Deprecated:
  • since 6.3
See:
Returns:

The data member of the object contains the property values

Type
GuideResultObject
Example
var result = guideBridge.getElementProperty({
   propertyName: "value",
  somExpression: ["somExpression1", "somExpression2"]
});
if (result.errors) {
     console.log("some som expressions were invalid");
     var err = result.getNextMessage();
    while(err != null) {
         //err.somExpression will point to the invalid somExpression in the Field.
         console.log(err.message);
    }
}
for(var i = 0; i< result.data.length; i++) {
     console.log(result.data[i]);
}

getFileAttachmentsInfo(options)

The API provides a list containing File Names and File URLS for the Files Attached by the user using the File Attachment component. The API is a asynchronous API and takes success handler which is called with the list of File Names and URLs.

Parameters:
Name Type Description
options object

Object containing the callback which will be invoked with the result of this API

Properties
Name Type Argument Description
success function

success callback which will be invoked. The signature of the callback should match the signature of FileAttachmentInfoHandler
context object <optional>

this parameter in the success handler will point to this object
Since:
  • 6.0
Example

Example usage of the getFileAttachmentsInfo API

guideBridge.getFileAttachmentsInfo({
       success:function(list) {
            for(var i = 0; i< list.length; i++) {
                 console.log(list[i].name + " "+ list[i].path);
            }
       }
});

visit(callback [, context])

Traverse all the components in the Adaptive Form and invoke callback function for each of the component

Iterates over all the components in the Adaptive Form and invokes its visit method passing the callback to the API.

Parameters:
Name Type Argument Default Description
callback function

Function to be called for every Adaptive Form Component present in the Form. The signature of the callback matches the signature of VisitorCallback
context object <optional>
 window

this object in the callback will point to this object
Since:
  • 6.0
Example

Creating a list of all components having name testName

var myList = []
guideBridge.visit(function(cmp) {
    if(cmp.name === "testName") {
         myList.push[cmp];
    }
}};

hideSummaryPanel()

Hides the panel that contains the summary component.

In Adaptive Form there is a summary component to show the summary of submission. This API hides the parent panel of the summary component. If the component is not present inside the Form, this operation doesn't do anything

Since:
  • 6.0
Returns:

the data property of GuideResultObject would be undefined. The API will fail if the Form is not initialized which would be indicated by the GuideResultObject#errors property.

Type
GuideResultObject

getGuideState(options)

Retrieve the current state of Adaptive Form as json string

Adaptive Form stores its state in the form of JSON. The Files attached in the component are uploaded onto the server and their paths are returned in the JSON state except in certain conditions mentioned below. The API is an asynchronous call which calls the success and error handlers with the data.

In the below mentioned scenarios the file will not be uploaded

  • User doesn't have write permissions on the fileUploadPath provided
  • The fileUploadPath property doesn't point to a node of type sling:Folder
Parameters:
Name Type Description
options object

Input object containing the callbacks that will be invoked to provide the result of the API

Properties
Name Type Argument Description
success function <optional>

callback which receives the result of the API in case of success. errors property as false.
error function <optional>

callback which receives the result of the API in case of failure. errors property as true.
context object <optional>

this object inside the success and error callback will point to this object
fileUploadPath string <optional>

controls whether the files in the File Attachment component have to be uploaded or not. If fileUploadPath is non null, only then file gets uploaded and the model's value is updated with the file url
Since:
  • 6.0

validate(errorList [, somExpression] [, setFocus])

validate the entire Form or a component in Adaptive Form

Validates the Adaptive Form or it's specific panel and return the validation status. The API also moves focus to first invalid element

Parameters:
Name Type Argument Default Description
errorList Array.<Field~ValidationError>

Input must be an empty array. The array will be filled with list of Adaptive Form Components that failed validation.
somExpression string <optional>

SOM Expression of the Guide Node for which validation should be triggered. If not provided, it would validate the entire Adaptive Form
setFocus boolean <optional>
 true

If true, set focus to the first invalid element.
Since:
  • 6.0
See:
Returns:

true if the component/form was valid, false otherwise

Type
boolean

restoreGuideState(options)

restore/prepopulate the state of Adaptive Form from an earlier saved state

Adaptive Form can be restore in three ways

  • by passing the JSON data obtained from GuideBridge#getGuideState. This can be done by setting data property .
  • by passing a URL pointing to a resource that returns JSON/XML data that should be used. This can be done by setting dataRef property. The data can be obtained by calling the getData API.
  • by passing a URL pointing to a resource that returns JSON data obtained from GuideBridge#getGuideState. This can be done by setting guideStatePathRef property .

When restoring from dataRef, only values and other properties, that are dependant on value, are restored. For example, If a Field was hidden based on the click of a Button then when restoring from data XML/JSON the Field will not remain hidden.

NOTE: The data, dataRef and guideStatePathRef must not be null simultaneously and only one property must be specified. Specifying more than one can lead to undesired results.

Parameters:
Name Type Description
options object

object containing the callbacks to be invoked on success/failure and data from where to restore the object.

Properties
Name Type Argument Description
success function <optional>

callback which receives the result of the API in case of success errors property as false.
error function <optional>

callback which receives the result of the API in case of failure. errors property as true.
context object <optional>

this object inside the success and error callback will point to this object.
data object <optional>

It must be the value of the data property passed to the success handler of getGuideState API.
dataRef string <optional>

URL pointing to the data XML/JSON.
guideStatePathRef string <optional>

URL pointing to the JSON state of Adaptive Form.
Since:
  • 6.0
Examples

Restoring from JSON data

var jsonData;
guideBridge.getGuideState({
     success : function (guideResultObj) {
         jsonData = guideResultObj.data;
     },
     error : function (guideResultObj) {
         // log error
     }
});

// after some time or on click of a button or reloading the page
guideBridge.restoreGuideState({
     guideState : jsonData.guideState,
     error : function (guideResultObject) {
         // log the errors
     }
})

Restoring from data XML/JSON

guideBridge.getData({
     success : function (guideResultObj) {
         var data = guideResultObj.data;
         //post the data to a server that saves it at say http://abc.com/my/data.xml
         //or http://abc.com/my/data.json
     },
     error : function (guideResultObj) {
         // log the errors
     }
});

// after some time or on click of a button or reloading the page
guideBridge.restoreGuideState({
     dataRef : "http://abc.com/my/data.xml",
     error : function (guideResultObject) {
         // log the errors
     }
})

Restoring from URL to a JSON

guideBridge.getGuideState({
     success : function (guideResultObj) {
         var json = guideResultObj.data;
         //post the JSON to a server that saves it at say http://abc.com/my/data.json
     },
     error : function (guideResultObj) {
         // log the errors
     }
});

// after some time or on click of a button or reloading the page
guideBridge.restoreGuideState({
     guideStatePathRef : "http://abc.com/my/data.json",
     error : function (guideResultObject) {
         // log the errors
     }
})

resolveNode(somExpression)

Given a somExpression, return the GuideNode having the same somExpression.

Parameters:
Name Type Description
somExpression string

somExpression of the Adaptive Form component
Since:
  • 6.0
See:
Returns:

GuideNode matching the som expression or null if not found

Type
GuideNode

reset()

Reset the values of all the Fields to their default values.

Invokes Field#resetData API for all the Fields inside the Form to reset their values to default

Since:
  • 6.0

getFocus(options)

return the somExpression of the Panel or Field that is currently in focus

Returns the somExpression of the current Panel or current Field in Focus. The API can also be used to get the somExpression of the Navigable Panel that contains the current Element in Focus.

Parameters:
Name Type Description
options object

configuration to be passed to the API to get the desired result

Properties
Name Type Argument Description
focusOption string <optional>
<nullable>

Currently the following value of this option are supported

  • navigablePanel: if one wants to get the somExpression of the Navigable Panel
Since:
  • 6.0
See:
Returns:

somExpression of Adaptive Form component representing the field or panel.

Type
string
Example
guideBridge.getFocus({"focusOption": "navigablePanel"})

setFocus(somExpression [, focusOption] [, runCompletionScript])

Sets focus to a Field or Panel

In Adaptive Form one can focus a Field/Panel. Setting focus on a Panel means setting focus to its first child. This can be controlled using the focusOption provided in this API.

The API provides two mechanism to focus a Field/Panel.

  • Direct : By providing the somExpression of the Field/Panel. If the somExpression of Panel is provided, then based on the focusOption one of its child (or their child) is set to Focus
  • Indirect : By providing an item's relative position inside a Panel, first or last item inside of a Panel, sibling of current focussed Item of a Panel, etc. If the item is a Panel then the First Item of that Panel (if that is again a Panel, this process continues until a Field is found) is activated.

The first way is trivial, by providing the somExpression of a Field to the API, the focus will be set to the Field.

If that Field is inside a Panel that is not currently open because of tabbed/wizard navigation, then that tab would be opened and focus would be set to the Field/Panel.

The API can also execute the completion expression of the current Panel and only if the expression returns true set focus to the required element.

Note:

  • If focusOption is either of nextItemDeep or prevItemDeep then somExpression parameter must not be passed. Otherwise the API will throw an exception
  • If somExpression points to a Field and focusOption is not nextItemDeep or prevItemDeep then focusOption is ignored.
Parameters:
Name Type Argument Default Description
somExpression string <nullable>

SOM Expression of the Adaptive Form Field or Panel which has to be activated.
focusOption string <optional>
 firstItem

The option provides the mechanism to focus onto an sibling of the current active item.

  • firstItem - Focuses to the first focusable item of the Panel whose SOM Expression is provided
  • lastItem - Focuses to the last focusable item of the Panel whose SOM Expression is provided

If either the firstItem or lastItem is a Panel, then the firstItem of that Panel (until a Field is found) is set to Focus.

  • nextItem - Next sibling component of the current active Item of the Panel whose somExpression is provided. It is equivalent to the result of panel.navigationContext.nextItem API.

  • prevItem - Previous sibling component of the current active Item of the Panel show somExpression is provided. It is equivalent to the result of panel.navigationContext.prevItem API.

  • nextItemDeep - Focus is set to the next Navigable Panel of root Panel in DFS Order

  • prevItemDeep - Focus is set to the next Navigable Panel of root Panel in DFS Order
runCompletionScript boolean <optional>
 false

indicating whether to execute the completion expression or not.
Since:
  • 6.0
Returns:

true if the focus was set to requested field successfully otherwise false

Type
boolean
Example
setFocus(somExpression); // Focus is set to the specified somExpression.
setFocus(this.panel.somExpression,'nextItem',true); // Focus is set to next item in the Panel.
setFocus(null,'nextItemDeep',true); // Focus is set to next navigable Panel in rootPanel

submit(options)

submits the Adaptive Form

Validate and submits the data of the Adaptive Form to the pre-configured submit action.

The success handler provided in the argument is executed only if the Adaptive Form is configured to use AJAX for submission using registerConfig API

Parameters:
Name Type Description
options object

options to control the behaviour of submit API.

Properties
Name Type Argument Default Description
submissionSelector string <optional>

url selector governs the submission behaviour at server Default value is "submit", other options are "agreement", "signSubmit"
success function <optional>

callback which receives the result of the API in case of success. errors property as false.
error function <optional>

callback which receives the result of the API in case of failure. errors property as true.
context object <optional>

this object inside the success and error callback will point to this object
validate boolean <optional>
 true

whether to validate the form before submission or not
Since:
  • 6.0
Examples

Submitting the form without validation

guideBridge.submit({
   validate: false,
   error : function (guideResultObject) {//log message}
});

Submitting the form and showing a success message

guideBridge.registerConfig("submitConfig" : {"useAjax" : true});
guideBridge.submit({
  validate: false,
  error : function (guideResultObject) {//log message}
  success : function (guideResultObject) {alert("data submitted successfully")
});

handleServerValidationError(errorJson)

Displays validation error messages at field level

This API displays validation error messages at the field level corresponding to the input errorJson object

Parameters:
Name Type Description
errorJson object

json object containing the error messages in the standard format
See:

on(eventName, handler [, context])

add a listener on a GuideBridge Event.

The API can be used to add an event listener for events triggered by GuideBridge object

Parameters:
Name Type Argument Description
eventName string

name of the event for which listener has to be added. It must be one of the following events

  • bridgeInitializeComplete
  • elementEnableChanged
  • elementFocusChanged
  • elementHelpShown
  • elementLazyLoaded
  • elementNavigationChanged
  • elementValidationStatusChanged
  • elementValueChanged
  • elementVisibleChanged:
  • guideAutoSaveStart
  • submitStart
  • validationComplete
handler function

callback to be invoked whenever the event is triggered. The signature of the callback is GuideBridgeEventCallback
context object <optional>

The this object in the handler will point to context
Since:
  • 6.0

off(eventName [, selector] [, handler])

Unregister the event registered using the on function

Parameters:
Name Type Argument Description
eventName string

name of the event to un-register.
selector string <optional>

selector which should match the one originally passed to guideBridge's on() while registering handlers
handler function <optional>

handler which needs to un-registered. If not provided all the event listeners will be unregistered
Since:
  • 6.0

getAutoSaveEnabledStatus()

Whether autoSave is enabled for this Adaptive Form or not

Adaptive Form can be configured to save draft automatically. This property indicates whether Adaptive Form is configured to save draft automatically or not.

Enabling auto save doesn't mean that AF will create the draft when the Form is loaded. Based on the result of Auto save start expression the draft will be created. Once the expression returns true, drafts will be saved at regular interval or at specific events as configured.

Since:
  • 6.1 FP1
See:
Returns:

true if auto save is enabled otherwise false.

Type
boolean

hasAutoSaveStarted()

Whether Adaptive Form data is being saved as draft or not.

This API indicates that auto save is enabled and draft is being saved at the configured location.

Since:
  • 6.1 FP1
See:
Returns:

whether autoSave has started.

Type
Boolean

getAutoSaveInfo()

the autoSaveinfo that is stored at the guideContainer.

Since:
  • 6.1 FP1
Deprecated:
  • since 6.3
Returns:

object contains the additional meta information stored along with form data

Type
object

afSubmissionInfo(property [, value])

store or retrieve submission related information

The API is used to provide extra information to be saved in Final data XML. It can also be used to retrieve that information.

If value is null then the value of the property is returned

Parameters:
Name Type Argument Description
property string

name of the property against which to save the value or retrieve the value of property
value string <optional>

value to save.
Since:
  • 6.1 FP1
Deprecated:
  • since 6.3
Returns:

old value of the property

Type
*

getSubmissionMetadataInfo()

this API returns the metadata configured for submission. Value depends on the selection of metadata type, local or global.

Since:
  • 6.1 FP1
Deprecated:
  • since 6.3
Returns:
Type
Object

getComputedSubmissionMetadata()

returns the globalMetaInfo object after all the computation. This object will be set in guideContext for submission

Since:
  • 6.1 FP1
Deprecated:
  • since 6.3
Returns:

In a format {"key 1": computation result of registered expression, "key 2":...}

Type
object
Example
{
  "key 1": computation result of registered expression,
  ...
}

setEnabledAutoSave(value)

enable auto save in Adaptive Form.

The API enables auto save in Adaptive Form

Parameters:
Name Type Description
value boolean

true to enable auto save otherwise false.
Since:
  • 6.1 FP1
See:

setFocus(options)

An alternate signature to the setFocus API

The API is equivalent to calling guideBridge.setFocus(options.somExpression, options.focusOption, options.runCompletionScript)

Parameters:
Name Type Description
options object

options passed to the API

Properties
Name Type Description
somExpression string

somExpression to set the focus to
focusOption string

item inside the Panel to focus to
runCompletionScript string

whether to run the completion script or not.
Since:
  • 6.1 FP1
Returns:

true if the focus was set successfully otherwise false.

Type
boolean

loadAdaptiveForm(options)

load an Adaptive Form given its path

This API returns the HTML content of another Adaptive Form and optionally load the Form inside an HTML element

The data property of the result passed to success handler will contain the HTML of the Form

Parameters:
Name Type Description
options object

object to pass to the API

Properties
Name Type Argument Description
success function <optional>

callback which receives the result of the API in case of success. errors property as false.
error function <optional>

callback which receives the result of the API in case of failure. errors property as true.
context object <optional>

this object inside the success and error callback will point to this object
path string

Path of the Adaptive Form whose HTML is required. If sever is running at a context path, this parameter must have the context path
dataRef string <optional>

URL of the resource that returns the XML. The protocol of the URL must match the supported URL protocols
containerSelector string <optional>

jquery Selector of the HTML element where to insert the HTML of the form.
Since:
  • 6.1 FP1
See:
Example
guideBridge.loadAdaptiveForm({
     success : function (guideResultObj) {console.log("html is " + guideResultObj.data)},
     error : function (guideResultObj) { //log errors},
     dataRef : "http://url/of/the/dataRef",
     path : "/contextpath/content/dam/formsanddocuments/form1"
})

unloadAdaptiveForm(containerSelector)

Unloads an adaptive Form from the browser, removing all the existing event listeners, data, html.

Unloads the Form loaded using the loadAdaptiveForm API

Parameters:
Name Type Description
containerSelector

jQuery Selector of the container, which contains the HTML of the Adaptive Form
Since:
  • 6.1 FP1
See:

hideResetButtons()

Hides all the reset buttons present in the Adaptive Form

Since:
  • 6.3
Returns:

the data property of GuideResultObject would be undefined. The API will fail if the Form is not initialized which would be indicated by the GuideResultObject#errors property.

Type
GuideResultObject

setData(options)

Populate the Adaptive Form from the data.

Adaptive Form can set data in three ways:

  • by passing the JSON data obtained from GuideBridge#getGuideState. This can be done by setting data property .
  • by passing a URL pointing to a resource that returns data JSON/XML that should be used. This can be done by setting dataRef property. The data can be obtained by calling the getData API.
  • by passing a URL pointing to a resource that returns JSON data obtained from GuideBridge#getGuideState. This can be done by setting guideStatePathRef property .

When setting data from dataRef, only values and other properties, that are dependant on value, are set. For example, If a Field was hidden based on the click of a Button in the data passed then when setting data from XML/JSON the Field will not remain hidden.

NOTE: The data, dataRef and guideStatePathRef must not be null simultaneously and only one property must be specified. Specifying more than one can lead to undesired results.

Parameters:
Name Type Description
options object

object containing the callbacks to be invoked on success/failure and data from where to restore the object.

Properties
Name Type Argument Description
success function <optional>

callback which receives the result of the API in case of success errors property as false.
error function <optional>

callback which receives the result of the API in case of failure. errors property as true.
context object <optional>

this object inside the success and error callback will point to this object.
data object <optional>

It must be the value of the data property passed to the success handler of getGuideState API.
dataRef string <optional>

URL pointing to the data JSON/XML.
guideStatePathRef string <optional>

URL pointing to the JSON state of Adaptive Form.
Since:
  • 6.3
Examples

Setting data from JSON data

var jsonData;
guideBridge.getGuideState({
     success : function (guideResultObj) {
         jsonData = guideResultObj.data;
     },
     error : function (guideResultObj) {
      // log the errors
     }
});

guideBridge.setData({
     guideState : jsonData,
     error : function (guideResultObject) {
         // log the errors
     }
})

Setting data from XML/JSON

guideBridge.getData({
     success : function (guideResultObj) {
         var data = guideResultObj.data;
         //post the XML/JSON to a server that saves it at say http://abc.com/my/data.xml
         //or http://abc.com/my/data.json
     },
     error : function (guideResultObj) {
         // log the errors
     }
});

guideBridge.setData({
     dataRef : "http://abc.com/my/data.xml",
     error : function (guideResultObject) {
         // log the errors
     }
})

Setting data from URL to a JSON

guideBridge.getGuideState({
     success : function (guideResultObj) {
         var json = guideResultObj.data;
         //post the JSON to a server that saves it at say http://abc.com/my/data.json
     },
     error : function (guideResultObj) {
         // log the errors
     }
});

guideBridge.setData({
     guideStatePathRef : "http://abc.com/my/data.json",
     error : function (guideResultObject) {
         // log the errors
     }
})

<static> disableForm()

Disables the adaptive form, i.e. it disables all the fields and buttons, including toolbar's button

Since:
  • 6.3

enableSwipeGesture(swiptLeft, swipeRight)

Enable/Disable the swipe gesture for navigation on touch devices.

Parameters:
Name Type Description
swiptLeft

boolean flag to enable(true)/disable(false) the swipe left gesture to perform next item navigation
swipeRight

boolean flag to enable(true)/disable(false) the swipe right gesture to perform previous item navigation
Since:
  • 6.3

loadLazyFragment(somExpression)

Loads the lazy fragment specified by somExpression

Parameters:
Name Type Description
somExpression string

somexpression of the lazy loaded fragment
Since:
  • 6.4
Example

Loading a lazy loaded fragment with somexpression x[0].y[0].z[0]. If both y and z form objects are lazy loaded, this API would load both

guideBridge.loadLazyFragment("x[0].y[0].z[0]");

Type Definitions

postExternalCallback(name, data)

Callback to execute when bridgeInitializeStart is triggered.

Parameters:
Name Type Description
name string

constant string bridgeInitializeStart
data object

object containing the GuideBridge instance

Properties
Name Type Description
guideBridge GuideBridge

instance of GuideBridge
Since:
  • 6.0
Deprecated:
  • since 6.3 this callback is deprecated. One must do the handling in GuideBridge.events:bridgeInitializeStart event
See:

postExternalMessageConfig

Type:
  • object
Properties:
Name Type Description
postExternalHandler GuideBridge~postExternalCallback

callback to be executed when GuideBridge instance is available
Since:
  • 6.0
Deprecated:
  • since 6.3 this configuration is deprecated. One must do the handling in GuideBridge.events:bridgeInitializeStart event
See:

submitConfig

Type:
  • object
Properties:
Name Type Description
form HTMLFormElement

During submission Adaptive Form creates a new HTMLFormElement and puts all the value in that Form. One can provide an existing HTMLFormElement that will be reused for submitting the Form. The action and method property of the Form element will be ignored.
useAjax boolean

submit the form via a XMLHttpRequest rather than using a HTMLFormElement instance is available
submitSuccessHandler function

success Handler to be called post submission. This option is ignored if useAjax is set to false
Since:
  • 6.0
See:

FileAttachementObject

File Attachment object

Type:
  • object
Properties:
Name Type Description
name string

name of the uploaded File
path string

path of the uploaded File
Since:
  • 6.0

FileAttachmentInfoHandler(fileAttachementList)

Success callback that is called from GuideBridge#getFileAttachmentsInfo with the list of File Attachments

Parameters:
Name Type Description
fileAttachementList Array.<GuideBridge~FileAttachementObject>

list of file attachement objects uploaded in the Form

GuideBridgeEventCallback(event, payload)

Signature of the callback for the GuideBridgeEvent Listener. It must be passed as handler in the on API.

Parameters:
Name Type Description
event jQuery.Event

jQuery Event Object with target property being the instance of GuideBridge
payload Object

Payload containing extra information in the API
Since:
  • 6.0
See:

Events

bridgeInitializeStart

Notifies when the instance of GuideBridge is available.

Dispatched when the instance of GuideBridge is available. The GuideBridge object will be passed to the listener and further communication can be done using that object.

Note : bridgeInitializeStart event is dispatched at window

Properties:
Name Type Description
detail Object

an object containing guideBridge

Properties
Name Type Description
guideBridge GuideBridge

GuideBridge Instance
Since:
  • 6.0
Example
window.addEventListener("bridgeInitializeStart", function(evnt) {
     // get hold of the guideBridge object
     var gb = evnt.detail.guideBridge;
     //wait for the completion of adaptive forms
     gb.connect(function (){
        //this function will be called after adaptive form is initialized
     })
})

bridgeInitializeComplete

Dispatched when the initialization of Adaptive Form is complete.

Properties:
Name Type Description
payload object

payload passed to the event listener

Properties
Name Type Description
target object

instance of GuideBridge object
Since:
  • 6.0
Deprecated:
  • since 6.3 this event is deprecated. Please use connect API
Example
guideBridge.on("bridgeInitializeComplete" , function(event, payload) {
     var gb = payload.target;
     assert(gb === guideBridge)
}

elementVisibleChanged

Dispatched when visibility of any Adaptive Form component(Panel or Field) changes.

Properties:
Name Type Description
payload object

payload containing more information about the event

Properties
Name Type Description
target Scriptable

Adaptive Form component whose visible property has changed.
oldText boolean

old value of the visible property
newText boolean

new value of the visible property
Since:
  • 6.0
Example
guideBridge.on("elementVisibleChanged" , function(event, payload) {
     var component = payload.target; // scripting model of the component whose visibility has changed
     var newValue = payload.newText;
     if (newValue) {
         console.log(component.name + " is visible now";
     } else {
         console.log(component.name + " is hidden now";
     }
}

elementEnableChanged

Dispatched when any Adaptive Form component is enabled/disabled, i.e. enabled property of a component changes.

Properties:
Name Type Description
payload object

payload containing more information about the event

Properties
Name Type Description
target Scriptable

component whose enabled property has changed
oldText boolean

old value of the enabled property
newText boolean

new value of the enabled property
Since:
  • 6.0
Example
guideBridge.on("elementEnableChanged" , function(event, payload) {
     var component = payload.target; // scripting model of the component whose enabled property has changed
     var newValue = payload.newText;
     if (newValue) {
         console.log(component.name + " is enabled now";
     } else {
         console.log(component.name + " is disabled now";
     }
}

elementValueChanged

Dispatched when value of any Field changes.

Properties:
Name Type Description
payload object

payload containing more information about the event

Properties
Name Type Description
target Field

Field whose value has changed
oldText string | number

old value of the Field
newText string | number

new value of the Field
Since:
  • 6.0
Example
guideBridge.on("elementValueChanged" , function(event, payload) {
     var component = payload.target; // Field whose value has changed
     console.log("Value of component " + component.name + " was " + payload.oldText);
     console.log("Value of component " + component.name + " is " + payload.newText);
}

elementNavigationChanged

Event to notify that the user has navigated from one Panel to another.

In layouts like Wizard or Tabbed layout, when a user navigates from one tab to another, this event is triggered

Properties:
Name Type Description
payload object

payload containing more information about the event

Properties
Name Type Description
target Panel

Panel to which the user moved to
prevText string

SomExpression of the panel from which user moved
newText string

SomExpression of the panel to which user moved
Since:
  • 6.0
See:
Example
guideBridge.on("elementNavigationChanged" , function(event, payload) {
     var component = payload.target;
     console.log("old panel's SOM Expression: " + payload.oldText);
     console.log("new panel's SOM Expression: " + payload.newText);
}

elementFocusChanged

Dispatched whenever a Field/Panel gets Focus

Properties:
Name Type Description
payload object

payload containing more information about the event

Properties
Name Type Description
target Panel | Field

new focused component
oldText string

SOM Expression of component that was previously in focus or null
newText string

SOM Expression of the component that is currently in focus or null
Since:
  • 6.0
See:
Example
guideBridge.on("elementFocusChanged" , function(event, payload) {
     var component = payload.target;
     console.log("old elements's SOM Expression: " + payload.oldText);
     console.log("new elements's SOM Expression: " + payload.newText);
}

elementHelpShown

Dispatched when a user looks at the help description of any Adaptive Form component(Panel or field)

Properties:
Name Type Description
payload object

payload containing more information about the event

Properties
Name Type Description
target Panel | Field

component whose help is being shown
_property string

what kind of help is being shown. The value can be

  • shortDescription (if Short Description becomes visible)
  • longDescription (if Long Description becomes visible)
prevText string

empty string
newText object

object containing the help content

Properties
Name Type Description
help string

help content of the component
Since:
  • 6.0
See:
Example
guideBridge.on("elementHelpShown" , function(event, payload) {
     var component = payload.target;
     console.log("component whose help is shown " + payload.target.name);
     console.log("Help shown: " + payload._property);
     console.log("Help Content: " + payload.newText.help);
}

elementValidationStatusChanged

Dispatched when validity of a Field changes.

Properties:
Name Type Description
payload object

payload containing more information about the event

Properties
Name Type Description
target Field

Field which either became valid/invalid
prevText boolean

old validation status
newText boolean

new validation status
Since:
  • 6.0
See:
Example
guideBridge.on("elementValidationStatusChanged" , function(event, payload) {
     var component = payload.target;
     if (payload.prevText) {
         console.log("component became invalid" );
     } else {
        console.log("component became valid" );
     }
}

elementButtonClicked

Dispatched when a Button component is clicked.

Developers must not modify the Form Fields inside the listener. This is mostly use to update the UI outside the Form or capture some data for analytics. If you want to modify form field value on the click of a button please use the Click Expression provided in the Forms Authoring.

Properties:
Name Type Description
payload object

payload containing more information about the event

Properties
Name Type Description
target Button

Button which was clicked
Since:
  • 6.0
See:
Example
guideBridge.on("elementButtonClicked" , function(event, payload) {
     var component = payload.target; // Button which wass clicked
     console.log("Button which was clicked " + component.name);
}

validationComplete

Dispatched when the validation of all the Adaptive Form fields are completed.

Whenever the full form validations are run via the validate API, this event is triggered.

Properties:
Name Type Description
payload object

payload containing more information about the event

Properties
Name Type Description
target GuideContainerNode

root Node of the Adaptive Form
prevText boolean

result of running the validation. true if validations are successful, false otherwise
newText Array.<Field~ValidationError>

List of objects containing error messages.
Since:
  • 6.0
Example
guideBridge.on("validationComplete" , function(event, payload) {
     if (payload.prevText) {
         console.log("validation success");
     } else {
         console.log("validation failure");
         if (payload.newText.length) {
             payload.newText.forEach(function (error) {
                console.log("validation failed for " + error.som + " with message " + error.errorText);
             })
         }
     }
}

submitStart

Dispatched when the user clicks on the submit button

Users can add some pre submit code in the listener to this event.

Since:
  • 6.0
Example
guideBridge.on("submitStart" , function(event) {
   // do some pre submit processing
}

guideAutoSaveStart

Dispatched when auto save gets enabled in the Form

Adaptive Form can be configured to be saved automatically at regular intervals. This can be controlled dynamically based on the values filled in the Form. Authors can write custom scripts which can enable/disable auto save functionality dynamically

Properties:
Name Type Description
payload object

payload containing more information about the event

Properties
Name Type Description
target GuideContainerNode

root Node of the Adaptive Form
Since:
  • 6.1
See:
Example
guideBridge.on("guideAutoSaveStart" , function(event, payload) {
     console.log("Forms is now being saved as draft automatically");
}

saveStarted

Dispatched when save of adaptive form data has started

Since:
  • 6.1
Example
guideBridge.on("saveStarted" , function(event) {
     console.log("Save of Adaptive Form data is about to start");
}

saveCompleted

Dispatched when save of adaptive form data is completed

Since:
  • 6.1
Example
guideBridge.on("saveCompleted" , function(event) {
     console.log("Save of Adaptive Form data is completed");
}

elementLazyLoaded

Dispatched when an Adaptive Form fragment is lazily loaded successfully

Properties:
Name Type Description
payload object

payload containing more information about the event

Properties
Name Type Description
target Panel

Adaptive Form Fragment which is lazily loaded
Since:
  • 6.1 FP1
See:
Example
guideBridge.on("elementLazyLoaded" , function(event, payload) {
     var component = payload.target;
     console.log("Panel " + component.name + " loaded");
}