Enabling User Actions

Add interactive elements to your integration

By making use of the onMessage hook and the sendIntegrationMessage utility you can allow user's to trigger actions right from your integration in the overlay window.

To begin, you need to create a way for the user to trigger an action. In your handlebars template we can do this by adding a button that triggers an action "doSomething" on our component file.

templates/block.hbs

<button {{action "doSomething"}}>Click Me!</button>

On the component file, we then need to add a function that is run when the action doSomething is triggered by a user clicking on the "Submit" button we created.

components/block.js

polarity.export = PolarityComponent.extend({
    message: '',
    actions: {
        doSomething: function (type) {
            let self = this;

            // The payload can contain any properties as long as you send a 
            // javascript object literal (POJO)
            let payload = {
              type: 'doSomething',
              action: 'Button Clicked'
            };

            // This is a utility method that will send the payload to the server 
            //where it will trigger the integration's `onMessage` method
            this.sendIntegrationMessage(payload).then(function (response) {
                // We set the message property to the result of response.reply
                self.set('message', response.reply);
            }).catch(function (err) {
                // If there is an error we convert the error into a string 
                // and append it to the string ERROR!
                self.set('message', "ERROR! " + JSON.stringify(err));
            });
        }
    }
});

The sendIntegrationMessage here will send the payload {action: 'Button Clicked'} to the integration's onMessage method implemented on the integration.js file running on the server.

On the server, you should listen for the message coming from the component using the onMessage hook.

integration.js

let counter = 0;
function onMessage(payload, options, cb) {
    if(payload.type === 'doSomething'){
        cb(null, {
            reply: "Hello World! " + (++counter)
        });
    }else{
        // we must always call the `callback` and return an empty object
        cb(null, {});
    }
}

The onMessage implementation above simply responds back to the component with the message "Hello World!" with a server incremented counter appended to it.

After setting up your onMessage function within the integration.js file on the server, you will need to export the function so the Polarity Server is able to run it:

integration.js

module.exports = {
   doLookup,
   startup,
   onMessage
};