Form Synergy: JavaScript API

JavaScript API

An overview to the JavaScript API. This API provides the necessary tools, to trigger an interaction by combining a sequence of events.

Including the API

/**
 * 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>

Getting started

Prepare and import all settings at one.

FS.prepare({
    heartBeat: 7500,
    localMode: {
        endPoint: 'https://...',
        request: {}
    },
    debug: false,
});

hearBeat

number

Set a frequency to enable the heartBeat, min(7500ms).

localMode

object

When encountering connection problems, requests can be routed to an alternative endpoint.

localMode.endPoint

string

While in localMode, any data passed using localMode.request will be included in the request.

localMode.request

object

While in localMode, any data passed using localMode.request will be included in the request.

Debug

boolean

Setting debug to true will force the API to use the localMode feature.

Engage

Keep in mind that you must create your custom event and methods before engaging.

FS.engage();

Preventing code collision with sequence blocking

Code withing a sequence block, can only run when its matching data attribute is present.

// Using a data attribute.
data-fs-sequence='my-code-block'

// creating sequence block.
let block = FS.createSequence('my-code-block');

block.event('onScroll:my-tag', (ev, elem) => {
    ...
});

Creating counters

Create counters and keep track of multiple events.

// Creating a counter.
FS.counter('name', 'create');

// Will add one.
FS.counter('name', 'add'); 

// Will add 20.
FS.counter('name', 'add', 20);

// Will set the count to 15.
FS.counter('name', 'update', 15);

// Will subtract count by 1.
FS.counter('name', 'subtract');

// Will subtract count by 10.
FS.counter('name', 'subtract', 10);

// Will retrieve the count.
FS.counter('name', 'get');

// Will delete the counter.
FS.counter('name', 'delete');

Creating options

Create options to manage process and status of interactions.

// Creating an option.
FS.option('name', 'create');

// Set an option as completed.
FS.option('name', 'update', true); 

// Set an option as incomplete.
FS.option('name', 'update', false); 

// Will get the status of an option.
FS.option('name', 'get');
 
// Will delete the option.
FS.option('name', 'delete');

Default events

Certain events are already available through this API, and can be applied using data attributes.

onScroll

Use an element to set a threshold. An interaction will be triggered once a user scrolls beyond this threshold/element. onScroll examples

onLoad

Will trigger an interaction on page load onLoad examples

onExit

Will trigger an interaction before exiting a certain page, by specifying a path. This type of interaction is trigger once per path. onExit examples

onClick

Will trigger an interaction when a click event is triggered on a related element. onClick examples

Scroll event

Use an element to set a threshold. An interaction will be triggered once a user scrolls beyond this threshold / element.

/**
 * A real world example.
 * Implement the essential data attributes.
 **/
<div
data-fs-etag='onScroll:div-name'
data-fs-etag='{
    "trigger": {
        "moduleid": "$moduleid"
    }
}'></div> 

// Set display options
<div
    data-fs-el='@$module'
    data-fs-opt='{
        "placement": "left-start",
        "theme": "white",
        "size": "lg"
    }'></div> 

// Create the threshold
<div data-fs-scroll="div-name"></div>

Event binding

Allows you to bind an etag and its related element, to one or multiple methods. Related tag

/**
 * A real world example.
 * Implement the essential data attributes.
 **/
FS.event('onInput:input-name', (ev, elem) => {
    15 == elem.value 
    ? elem.fire(true)
    : false;
});
 <div
    data-fs-etag='onInput:input-name'
    data-fs-etag='{
        "trigger": {
            "moduleid": "$moduleid"
        }
    }'></div> 

// Set display options
<div
    data-fs-el='@$module'
    data-fs-opt='{
        "placement": "left-start",
        "theme": "white",
        "size": "lg"
    }'></div> 

// Create the input
<div class="form-group"> 
    <label for="example-fire-input" class="strong">if b = 5; What is the value ( b x 3 )</label> 
    <input 
        id="example-fire-input" 
        class="form-control" 
        type="text" 
        placeholder="Type in the correct answer"
        value=""
        data-fs-input="input-name"
        /> 
</div>

The event method, allows you to bind an etag and its related element to .

/**
 * Fire an interaction  
 **/ 
FS.event('onInput:input-name', (ev, elem) => {
    15 == elem.value 
    ? elem.fire(true)
    : false;
});

Creating methods

One or multiple methods can be used to evaluate information and trigger an interaction.

// Create a counter
FS.counter('counterName', 'create');

// Create an option
FS.option('requiredCount', 'create', 3)

// Create a method
FS.createMethod('methodName', () => {
    // Retrieve the counter
    let counter = FS.counter('counterName', 'get'),
        // Retrieve the option
        default = FS.option('requiredCount', 'get');
    // Evaluate and return    
    return counter => default
        ? true
        : false;
});

/**
 * When using a method to trigger an interaction, it must return true or false.
 **/
FS.event('onInput:input-tag', (ev, elem) => {
    // Update the counter
    FS.counter('counterName', 'update', 3);

    // When method returns true it will trigger an interaction.
    elem.fireMethod('methodName');
});

Creating a callback

A callback will return the processed data of an interaction. This method can be used to implement local functionality

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