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 handlingIn 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
guideBridge.setProperty(["SOM_OF_FIELD_1", "SOM_OF_FIELD_2"...... "SOM_OF_FIELD_N"] "value" [VALUE_1, VALUE_2 .... VALUE_N]);
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
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
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
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 } })
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 } })
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])
-
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
guideBridge.submit({ validate: false, error : function (guideResultObject) {//log 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
-
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
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 } })
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 } })
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
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
- Since:
-
- 6.0
- Deprecated:
-
- since 6.3 this configuration is deprecated. One must do the handling in GuideBridge.events:bridgeInitializeStart event
- See:
Properties:
Name Type Description postExternalHandler
GuideBridge~postExternalCallback callback to be executed when GuideBridge instance is available
-
submitConfig
-
Type:
- object
- Since:
-
- 6.0
- See:
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
-
FileAttachementObject
-
File Attachment object
Type:
- object
- Since:
-
- 6.0
Properties:
Name Type Description name
string name of the uploaded File
path
string path of the uploaded File
-
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
- Since:
-
- 6.0
Properties:
Name Type Description detail
Object an object containing guideBridge
Properties
Name Type Description guideBridge
GuideBridge GuideBridge Instance
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.
-
- Since:
-
- 6.0
- Deprecated:
-
- since 6.3 this event is deprecated. Please use connect API
Properties:
Name Type Description payload
object payload passed to the event listener
Properties
Name Type Description target
object instance of GuideBridge object
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.
-
- Since:
-
- 6.0
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
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.
-
- Since:
-
- 6.0
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
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.
-
- Since:
-
- 6.0
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
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
- Since:
-
- 6.0
- See:
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
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
-
- Since:
-
- 6.0
- See:
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
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)
-
- shortDescription (if Short Description becomes visible)
- longDescription (if Long Description becomes visible)
- Since:
-
- 6.0
- See:
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
prevText
string empty string
newText
object object containing the help content
Properties
Name Type Description help
string help content of the component
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.
-
- Since:
-
- 6.0
- See:
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
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.
- Since:
-
- 6.0
- See:
Properties:
Name Type Description payload
object payload containing more information about the event
Properties
Name Type Description target
Button Button which was clicked
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.
- Since:
-
- 6.0
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.
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
- Since:
-
- 6.1
- See:
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
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
-
- Since:
-
- 6.1 FP1
- See:
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
Example
guideBridge.on("elementLazyLoaded" , function(event, payload) { var component = payload.target; console.log("Panel " + component.name + " loaded"); }