Widget Documentation

In this article, you will find more details about the Widget API Functions and the Widget Events available to you in Gnatta. 

Widget API Functions

api.log()

• Syntax: api.log(input:any): undefined   
• Description: Will log a message out to the parent window to assist with debugging, output can be found in the developer console of the main Gnatta window. Input will be serialised to JSON.   

api.setState()

• Syntax: api.setState(input:object): undefined   
• Description: setState will update the state of the internal widget, this state can be used by the view to determine what and how to render the handlebars template. The object given will be merged into the existing state, meaning a partial update can be given without fear of overwriting existing data.   

Examples

(api) => {
    api.setState({
        displayMessage: "This is a message"
    });
}

async (api) => {
    api.setState({
        loading: true
    });
    const result = await myLoader();
    api.setState({
        loading: false,
        result
    });
}

api.http.get()

• Syntax: api.http.get(url: string[, options: object]):Promise<HttpResultDescriptor>
• Options:

{
    Headers: {
        "key": "value"
    },
    Body: "string body value"
}  

• Description: Performs a HTTP GET request to the given URL. This request will be sent via our server and will be signed with any HTTP security signature that is configured (See : Additional HTTP Security using Keys for more details).

Examples

async (api) => {
    const result = await api.http.get("https://google.co.uk");
    api.log(result);
}

(api) => {
    api.http.get("https://google.co.uk")
        .then(result => api.log(result));
}

api.http.post()

• Syntax: api.http.post(url: string[, options: object]):Promise<HttpResultDescriptor>   
• Options:    

{ 
    Headers:
{ "key": "value" },
    Body: "string body value" 
} 

• Description: Performs a HTTP POST request to the given URL. This request will be sent via our server and will be signed with any HTTP security signature that is configured (See either: Additional HTTP Security using Keys, or Additional HTTP Security using OAuth for more details).

Examples:    

async (api) => {
    const result = await api.http.post("https://google.co.uk");
    api.log(result); 
} 
 

(api) => { 
    api.http.post("https://google.co.uk") 
        .then(result => api.log(result)); 
}

api.on()

• Syntax: api.on("event_name", (payload) => { ... });   
• Description: This subscribes to an event from the parent window, informing of any events that you may wish to react to.   

Examples:

(api) => {
    api.on("interaction_loaded", interaction => api.setState({
        interactionId: interaction.id
    }));
}

Interaction Functions

api.interaction.setDataSet

Syntax: api.interaction.setDataSet(interactionReference: number, dataSetId: string)

Description: Sets the specified Dynamic Data Set against the Interaction. The user must have correct permissions to be able to set Dynamic Data Sets.

Examples

await api.interaction.setDataSet(1078, “482b613c-a023-45bb-8600-31673351477f”)

api.interaction.setDataType

Syntax: api.interaction.setDataType(interactionReference: number, dataTypeId: string, value: string)

Description: Sets the value against the specified Dynamic Data Type on the Interaction. The user must have correct permissions to be able to set Dynamic Data Type.

Status Data Types: The value should be the Name of the status. This name must exist in the list of available status types.

Option Data Types: The value should be the Value of the option. This value must exist in the list of available option types.

String Data Types: The value should be the string value to be set against the Data Type. This value can be any string.

Examples

Status Type

await api.interaction.setDataType(1078, “482b613c-a023-45bb-8600-31673351477f”, “Open”)

Option Type

await api.interaction.setDataType(1078, “482b613c-a023-45bb-8600-31673351455f”, “Website”)

String Type

await api.interaction.setDataType(1078, “482b613c-a023-45bb-8600-31673351433f”, “placeholder@email.com”)

Widget Interaction Events

interaction_loaded

Using interaction_loaded as an event in your widget will allow you to access the below when a user loads an interaction. 

{
    id: Number,
    queueId: String,
    dynamicData: [{
        id: String,
        name: String,
        databaseType: String,
        value: {
            ...
        },
    }],
} 

dynamicdata_updated

Using dynamicdata_updated as an event in your widget will allow you to access the below when dynamic data is updated on an interaction a user has open.  

{
    id: String,
    name: String,
    databaseType: String,
    value: {
        ...
    },
}

Global Variables

There are a few global variables provided for utility purposes.  

• Handlebars is exposed to provide access to extend as necessary such as using registerHelper (See the API on the handlebarsjs website)
• parseXmlAsJs is provided as a function to convert XML into a JavaScript object.  

🔍Check out next