Class: GuideBridge

GuideBridge

new GuideBridge()

GuideBridge is bridge API using which, wrapper html (page hosting/embedding Adaptive Forms) or external window scripts like parent window javascript, can communicate with current Adaptive Form and manipulate or query it's current state.

This can be used for following purposes:

  • Actions and Toolbar Buttons: to get Adaptive Forms state to submit Adaptive Forms programmatically e.g.: save and restore drafts
  • Customization by Portal pages(that embed Adaptive Forms), to plug custom widgets, change certain visual configuration or query/ manipulate Adaptive Forms state
  • Analytics to collect events and data that can be pushed to Adobe SiteCatalyst (or other frameworks) for reporting

The API provides a method for external applications to connect with Adaptive Forms and formDom. The APIs are divided into two categories, synchronous and asynchronous.

Each Synchronous getter API returns a GuideResultObject which represents the result of the API whereas each setter API throws an exception in case of error 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.

Each Asynchronous API provides callback mechanism to return the result of the API. Each API takes a Javascript Object containing error, success Handlers and a context in which to invoke those functions. The syntax of the object is


{
  error: function(guideResultObject) {  } ,
  success: function(guideResultObject) {  },
  context: ObjectContext
}

Each of the functions is passed a GuideResultObject containing either the data of the operation or the errors.
Since:
  • 1.0.0

Methods

<static> 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:
  • 1.0.0

<static> on(eventName, handler, context)

Used to Register an event listener for specific Guide Bridge Event.
Parameters:
Name Type Argument Description
eventName string name of the event for which listener has to be added. It must be one of the events mentioned in the documentation.
handler function event listener which is called when the event is triggered.
context object <optional>
context is used as the this object inside handler function
Since:
  • 1.0.0

<static> reset()

This would reset the Adaptive Form state to initial state.
Since:
  • 1.0.0

connect(handler, context)

Specify a callback function which is called/notified when Adaptive Forms is ready for interaction
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>
context object that would be used as this object for callback function when it is called
Since:
  • 1.0.0
Example
guideBridge.connect(function() {
   console.log("Hurrah! Guide Bridge Activated");
})

getBridgeVersion() → {string}

returns the version of library
Returns:
the version of the library
Type
string

getDataXML(options)

Used to retrieve the Form data as XML. The API is an asynchronous API which calls the success/error handlers passed in the arguments upon completion
Parameters:
Name Type Description
options object The signature of the object is

  {
    success: function(guideResultObject) { },
    error:function(guideResultObject) { },
    context: obj
  }

success function function called in case of success. An object of type GuideResultObject will be passed as argument.

Note: If provided, submit would be ajax submit.

error function function called in case of error. An object of type GuideResultObject will be passed as argument
context object context will be used as this in the success/error handlers
Since:
  • 1.0.0

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 The signature of the object is

    {
     success: function(list) {}
    }
Since:
  • 1.0.0
Example

Example usage of the getFileAttachmentsInfo API

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

getFocus() → {Panel|Field}

Returns the current in Focus AF component
Since:
  • 1.0.0
Returns:
Adaptive Form component representing the field or panel.
Type
Panel | Field

getGuideState(options)

used to retrieve the current state of Adaptive Forms as json string. The JSON contains the state of all the AF components, their values, visiblity, enable property etc. The API is a asynchronous call which calls the success and error handlers with the data.
Parameters:
Name Type Description
options object The signature of the object is

  {
     fileUploadPath: string
     success: function(guideResultObject) {},
     error: function(guideResultObject) {},
     context: object
  }
fileUploadPath string

controls whether the files in the File Attachement 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

success function

function called in case of success. An object of type GuideResultObject will be passed as argument and the data member will have the following syntax

 {guideState: {   }}

error function

function called in case of error. An object of type GuideResultObject will be passed as argument

context object context will be used as this in the success/error handlers

Note In some scenarios the file will not be uploaded

  • The folder should have the security permissions.
  • The folder where file is uploaded should be of type sling:Folder

Since:
  • 1.0.0

isConnected() → {boolean}

Checks whether the Adaptive Forms has been initialized and ready for interaction with external/wrapper html

Since:
  • 1.0.0
Returns:
true if the Adaptive Forms is ready for interaction, false otherwise
Type
boolean

registerConfig(key, config) → {GuideResultObject}

Registers user/portal specific configurations to GuideBridge and returns the old configuration against the same key.Currently supported configurations are:
  • postExternalMessageConfig: The configuration is used provides a function which will be called whenever the bridgeEventInitialize event is triggered. This can be used to interact with the parent page (when the AF is loaded within an Iframe) which is not in the same domain as the AF page.

    
    guideBridge.registerConfig("postExternalMessageConfig", {"postExternalHandler" : function(data) { } });
    
    
    where data will be a JavaScript object with the following signature
    
    {
       name: "bridgeInitializeStart",
       data: {
          "guideBridge": 
       }
    }
    
    

  • widgetConfig: The configuration is used to provide which jquery widgets to use with which AF component.

    
    guideBridge.registerConfig("widgetConfig", {""});
    
    
    where can be either the name or classname of Adaptive Form component, while widget name is the name of the jquery widget.
Parameters:
Name Type Argument Description
key string configuration name. one of postExternalMessageConfig or widgetConfig
config object <optional>
configuration object.
Since:
  • 1.0.0
Returns:
with GuideResultObject#data having the old configuration against same key
Type
GuideResultObject

resolveNode(somExpression) → {object}

Given a somExpression, returns the Adaptive Form component having the same somExpression.
Parameters:
Name Type Description
somExpression string somExpression of the Adaptive Form component
Since:
  • 1.0.0
Returns:
AF component matching the som expression or null if not found
Type
object

restoreGuideState(options)

Restores the Adaptive Forms fill state from the passed in json data. The JSON data must be the one that is returned from the GuideBridge#getGuideState API
Parameters:
Name Type Description
options object The signature of the object should be

{
  data: {  },
  success: function(guideResultObject) {  },
  error: function(guideResultObject( {  },
  context: object
}
data object JSON Object to use for setting the AF state. It must be the object returned by GuideBridge#getGuideState
success function function called in case of success. An object of type GuideResultObject will be passed as argument
error function function called in case of error. An object of type GuideResultObject will be passed as argument
context object context will be used as this in the success/error handlers
Since:
  • 1.0.0

setFocus(somExpression, focusOption, runCompletionScript:)

Sets focus to the given Adaptive Forms Panel or Field as specified by the somExpression If that field is in a tab (for tabbed navigation) that is not currently open, then that tab would be opened and focus would be set to that field. In case, set focus is called for a Panel, focus would be set to first focussable field of that Panel. After the focus is set, runs applicable completeExp.
Parameters:
Name Type Description
somExpression string somExpression of the Adaptive Form component which has to be focussed.
focusOption string one of the value
  • nextItem
  • prevItem
  • lastItem
  • firstItem
  • nextItemDeep
  • prevItemDeep
Note: nextItemDeep and prevItemDeep are not supported with somExpression and would work for entire Adaptive Form context
runCompletionScript: boolean indicating whether to execute the completion expression or not.
Since:
  • 1.0.0
Returns:
boolean indicating setFocus was successful(true) or not(false)

setProperty(somList, propertyName, valueList)

Sets the values for the list of SOMs for the mentioned property. Property can only be "value", "access", or "presence".
Parameters:
Name Type Description
somList array should be an array having someExpression for the fields
propertyName string is the property for the fields to be set
valueList array should be an array containing values for the property for that field.
Example
guideBridge.setProperty(["SOM_OF_FIELD_1", "SOM_OF_FIELD_2"...... "SOM_OF_FIELD_N"]
                        "value"
                        [VALUE_1, VALUE_2 .... VALUE_N]);

validate(errorList, somExpression)

Validates the Adaptive Forms or it's specific panel and return validation status. Also, moves focus to first invalid element.
Parameters:
Name Type Argument Description
errorList array list of Adaptive Form Components that failed validation. Each Array item would have the signature

    {
      som: "somExpression",
      errorText: "error message"
    }
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

Since:
  • 1.0.0
Returns:
boolean indicating validation was successful(true) or not(false)

visit(callback, context)

Traverse all the components in the AF. callback is called for each component and that component is passed as the argument. context is used as the this object in callback
Parameters:
Name Type Argument Description
callback function function to be called for every AF component
context object <optional>
used as the this object
Since:
  • 1.0.0
Example
myList = []
guideBridge.visit(function(cmp) {
    if(cmp.name === "testName") {
         myList.push[cmp];
    }
}};

Events

bridgeInitializeComplete

Dispatched when the bridge object is initialized and ready for communication.

Payload:

Properties:
Name Type Description
target Object guideBridge
Since:
  • 1.0.0

bridgeInitializeStart

Dispatched when the bridge object is available but not ready for communication. The GuideBridge object will be passed to the listener and further communication can be done using that object

Note : bridgeInitializeStart event would be dispatched at window

Payload:

Properties:
Name Type Description
detail Object an object containing guideBridge
Since:
  • 1.0.0
Example
window.addEventListener("bridgeInitializeStart", function(evnt) {
     // get hold of the guideBridge object
     var gb = evnt.detail.guideBridge;
     //wait for the completion of AF
     gb.connect(function (){
        //this function will be called after Adaptive Form is initialized
     })
})

elementButtonClicked

Dispatched when an AF Button component is clicked. Button node has a special property called type which can be changed via edit dialog of Button component which can be used to describe its functionality

Payload:

Properties:
Name Type Description
click String
Since:
  • 1.0.0

elementEnableChanged

Dispatched when any AF component is enabled/disabled

Payload:

Properties:
Name Type Description
target: Object component whose Field#enabled property has changed
oldText: Boolean old value of the enabled property
newText: Boolean new value of the enabled property
Since:
  • 1.0.0

elementFocusChanged

Dispatched when focus comes to any AF component(Panel or field).

Payload:

Properties:
Name Type Description
target: Object new focused component
oldText: String SOM Expression of field that was previously in focus or null
newText: String SOM Expression of the field that is currently in focus or null
Since:
  • 1.0.0

elementHelpShown

Dispatched when help description is shown of any AF component(Panel or field).

Payload:

Properties:
Name Type Description
target: Object component whose help is being shown
_property: String what kind of help is being shown. can be either Short Description / Long Description
newText: Object object of the form
{help: help content of the field}
Since:
  • 1.0.0

elementValidationStatusChanged

Dispatched when AF Field becomes valid/invalid. Please refer to validationState

Payload:

Properties:
Name Type Description
target: Object component whose validationStatus property has changed
oldText: Boolean old validation status
newText: Boolean new validation status
Since:
  • 1.0.0

elementValueChanged

Dispatched when value of any AF component(Panel or field) changes.

Payload:

Properties:
Name Type Description
target: Object component whose Field#value has changed
oldText: String old value of the Field
newText: String new value of the Field
Since:
  • 1.0.0

elementVisibleChanged:

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

Payload:

Properties:
Name Type Description
target: Object AF component whose Field#visible property has changed
oldText: Boolean old value of the visible property
newText: Boolean new value of the enabled property
Since:
  • 1.0.0

submitStart

Dispatched when the submit action starts

Since:
  • 1.0.0

validationComplete

Dispatched when the validation of all the AF Fields are completed

Payload:

Properties:
Name Type Description
target: Object guide object
oldText: Boolean true or false, true if no validation error
newText: Array List of objects containing SOM and error.
Since:
  • 1.0.0