JavaScript Client

This JavaScript client provides flexible management of interactions using data attributes, including triggers, display, placements, and callbacks, over a RESTful JSON interface.


Including the library

		/**
 * Class expression
 */ 
<script 
    src="https://formsynergy.com/fs-js/m/fs-2.1.3.js" 
    integrity="sha256-dcCUR6iJQeSr6cYlYtl3GZDAxChEpRcbERaIPCgFH6g=" 
    id="fs-2.1.3" 
    crossorigin="anonymous">	
</script>	
	

Instantiate the class

Instantiate the Form Synergy class, enable heart beat by setting recurrence frequency in milliseconds

// Instantiate the Form Synergy class 
const FS = new FormSynergy();
	

Heart beat

// Heart beat is disabled by default. 
FS.heartBeat(10000) // Set heartbeat recurrence frequency in milliseconds. 
  .engage();
	

How to start an interaction

An interaction must be triggered in order to appear in front of a visitor, this can be done automatically when strategy conditions are met, by applying a trigger in data attributes or programmatically using JavaScript.

Data attributes

Name Type Description
Etag String The Etag is a combination of event type and an objective eg: click:contact-us, read more
Params JSON | Object Any information passed in the parameters will override the behavior and will be directly applied, read more
El String Unique identifier that can be applied to an element in order to handle a response, read more
Opt JSON | Object Will provide display and placement parameters to responses, read more

Event tags

[data-fs-etag]
<button 
   id="request-call-back"
   data-fs-etag="click:request-call-back">
   Call me please
</button>

Event parameters

[data-fs-params]
<button 
   id="request-call-back"
   data-fs-etag="click:request-call-back"
   data-fs-params='{
     "trigger": {
          "moduleid": "..."	   
     },
     "rel": {
          "message": {
             "subject": "Call me regarding this page"
          }
     }
 }'>
   Call me please
</button>
Name Type Example Values Description
trigger Object | JSON {    moduleid: “…” } Must be a valid moduleid Used to instantly display a module.
classNames string classNames: “my-class my-other-class” CSS class Will wrap the html with the provided classNames.
delay alphanumeric delay: 10 Seconds Will delay an interaction by the amount of seconds.
term alphanumeric delay: 50 Seconds Will terminate an interaction by the amount of seconds.
rel Object | JSON “rel”: {   “message”: {      “subject”: “Call me …”   } } Must be wrapped inside an envelop ‘message’ Will parse relevent data into an interaction.

Display and placement

[data-fs-el=”@…”], [data-fs-opt]
<div 
    id="display-call-back"
    data-fs-el="@...",
    data-fs-opt='{
        "placement": "bottom"
    }'></div>
	
Name Type Example Values Description
display string “display”: “fixed” embed; fixed If display options are not found, the default display will be used.
placement string “placement”: “bottom-end” Complete list of placement options Will apply placement on viewport for modals, will apply placement relative to the [data-fs-el] tag when using popover
size string “size”: “lg” sm; md; lg; xl For fixed and related positions
theme string “theme”: “white-translucent” white; white-translucent; dark; dark-translucent Will apply the style of the selected theme to an interaction.

Using JavaScript

FS.bind();

A trigger can be created using JavaScript as well, it can be used when data-fs-etag does not apply such as: on page load, as exit strategy, long wait time, inactivity…

Fs.bind( '#element', 'click:request-call-back', {
     trigger: {
         moduleid: '...'
     },
     el: '@moduleid',
     opt: {
         placement: '...',
         size: '...',
         theme: '...'
     },
     rel: {
         message: {
             subject: 'Call me regarding this page'
         }
     }
});
	

Creating a callback

FS.createCallback();

When applying connections to a module, instead of connecting a module, you can create a connection to a callback. Provided callback must match callback method


FS.createCallback( 'myCallback', ( response, interaction ) => {
    console.log(response);
});
	

Push contents

interaction.contents();

When using callbacks, an easy method is to use interaction.contents() to push text to the body of an interaction.

FS.createCallback( 'myCallback', ( response, interaction ) => {
    /**
     * contents(), only supports text.
     */
    interaction.contents('Hello World'); 
});
    

Create an element using virtual DOM

interaction.createElement();

When using callbacks, the safest way to add html to the body of an interaction is interaction.createElement().

FS.createCallback( 'myCallback', ( response, interaction ) => {
    /**
     * createElement(), uses a virtual DOM technique.
     * Supports: JSON, and Object
     */
    interaction.createElement({
        tagName: "div",
        attrs: {
            class: "alert alert-info"
        },
        children: [{
            tagName: "p",
            children: [{
                tagName: "strong",
                children: [{
                    tagName: "content",
                    content: "Example alert"
                }]
            }]
        }]
    });
});
    

Creating a custom event

FS.createEvent();

A quick overview on creating and implementing custom events:

1) Creating the trigger

/**
 * NOTE: The specified event within the etag, always starts with "on" and always lowercase.
 **/
<div 
    data-fs-etag='on{custom}:some-element-or-tag-name'
    data-fs-params='{
        "trigger": {
            "moduleid": "{moduleid}"
        }
    }'></div>
    

2) Creating a listener by tagging the appropriate element

 /**
  * In this example we will tag a text input, 
  * and create a relationship between the text input
  * data-fs-custom='some-element-or-tag-name'
  * and the trigger in this case the 
  * etag = on{custom}:some-element-or-tag-name,
  * NOTE: data-fs-{custom} is always lowecase, no "on". 
  **/   
    data-fs-custom='some-element-or-tag-name'
    

3) Setting display and placement options

<div 
    data-fs-el='@{moduleid}'
    data-fs-opt='{
        "display": "embed",
        "size": "full"
        "theme": "translucent"
    }'></div>
    

4) Creating the custom event

/**
 * Create the event.
 * NOTE: The event name must always start with a capital letter, and preceded with "on" like so: onCustom, onMove, onDrag...
 * Once we have a match, you will have to fire an interaction if your set of conditions are met.
 **/    
FS.createEvent( 'on{Custom}', ( e, elem ) => {
    /**
     * Retrieve the element, check if the value is correct.
     **/
    if( 'Interact now' == elem.value ) {
        /**
         *  If successful, fire the interaction, on the elem object.
         **/
        elem.interaction('fire');
    }
});
    

Add offset to all interactions

FS.offsetPositions(options);

Offset all interactions.

FS.offsetPositions({
    up: 0.01,
    right: 0.01,
    down: 0.01,
    left: 0.01
});
        

Localize modules

FS.setLocalMode(options);

This feature, creates a fallback system in case the connection with the Form Synergy server is lost or broken.

NOTE: You will need to download the strategy in order to user this feature, read more, You must enable heart beat as well, heart beat

FS.setLocalMode({
    endPoint: '',  //Where to send request
    request: {
        key: 'value' // Passing additional data to the request
    },
    response: {
        'success': 'Successful response',
        'error': 'Error response'
    },
});