Inter Gadget Communication with WSO2 UES

The main objective of this blog post is to explain how to implement inter-gadget communication with WSO2 User Engagement Server (UES). 

Inter - Gadget Communication

Inter-gadget communication that we are talking here is the capability of one gadget to talk with some other gadget. In simple words "is Gadget A capable of sending some data to Gadget B" and "is Gadget B capable of updating itself with the received data". The message paradigm that is used underneath is the publisher - subscriber model.

Publisher - Subscriber Model

As shown in the image given below, publisher publishes the message to a channel and subscribers listen to that channel. Upon a new message in the channel by the publisher, subscribers fetch the message and update their selves accordingly.

In a complex scenario, there can be one publisher publishing to multiple channels and also number of subscribers listening to multiple channels. 

The role of WSO2 User Engagement Server is to act as the Message Broker in this paradigm.

Implementation

I will explain the implementation of this publisher - subscriber (pub-sub) model with a simple example scenario.

Let's say publisher-gadget publishes a random number to a channel and that random number will be shown up in the subscriber-gadget each time that publisher-gadget will publish.

Gadgets usually communicate with the gadget-container via features and those features are declared in the the ModulPrefs section of gadget.xml file.

Gadgets convey their interest to either publish or subscribe to a channel via the gadgets.Hub.* API. Therefore the feature titled "pubsub-2" needs to be imported in-order to load the necessary API fragments . As I mentioned earlier this feature can be declared in the ModulePrefs section of our gadget.

OK. Now let's make our hands dirty with the sample that I described earlier.

Hint : Once we are done with the implementation we will have two gadgets with the following folder/file structure.

Publisher Gadget
Let's see how we can declare this in the publisher - gadget.xml file.

       <Require feature="pubsub-2">
                <Param name="topics">
                          <![CDATA[
                               <Topic title="randomNumber name="my-channel" publish="true"/>
                          ]]>
               </Param>
      </Require>

Pay attention to the sections I have marked in red in the above code snippet.  Feature that we have to import is pubsub-2. And my-channel is the channel that the publisher wishes to publish into. To indicate that this is the publisher gadget we have set publish="true".

In the sample that I'm going to describe in this post, when somebody clicks the button named "Publish a random number" in the publisher gadget, a random number will be published to my-channel. So let's have a button declared in our gadget.xml file.

         <div>
              <input type="button" value="Publish a random number" onclick="publish()"/>
         </div>

The function call that will be triggered by this button click is publish() and we define it in the js file of our publisher - gadget. (in publisher-gadget.js)

          function publish() {
               var message = Math.random();
               gadgets.Hub.publish("my-channel", message);
               document.getElementById("output").innerHTML = "Number that is published to the channel : " + message;
        }

Once again pay your attention to the red line which says publish the random number to my-channel which we declared in the ModulePrefs section.

Subscriber Gadget
As we did in the publisher gadget, we need to import the pubsub-2 feature and declare this gadget as a subscriber gadget in the subscriber-gadget.xml file.

          <Require feature="pubsub-2">
            <Param name="topics">
                <![CDATA[
<Topic title="randomNumber" name="my-channel"
description="Subscribes to random number channel" type="object"
subscribe="true"/>
]]>
            </Param>
        </Require>

And then let's have a simple div in the subscriber-gadget.xml file which we can use to set the fetched value from the publisher's channel.

          <div id="output"> </div>

After that we need to add the following snippet in the subscriber-gadget.js to activate the subscription to "my-channel" channel.

         gadgets.HubSettings.onConnect = function () {
                     gadgets.Hub.subscribe("my-channel", callback);
         };

The function that we want to invoke in the subscriber end, upon a message publishing by the publisher is written in the javascript callback function as follows which is also in the subscriber-gadget.js file.

         function callback(topic, obj, subscriberData) {
               document.getElementById("output").innerHTML = "Number that is fetched from the channel : " + obj;
         }

OK. We are done with the pub-sub implementation.

Finally what we need to do is add these two gadgets to a WSO2 UES dashboard and check out the functionality.

For that you can follow WSO2 UES documentation on how to create a gadget and how to add gadgets to dashboards.

Or else there is a bit hacky way also ;) (Not recommended. But if you want to check whether your two gadgets working fine, you can try this out.)

1. Copy your two gadgets in UES_HOME/repository/deployment/server/jaggeryapps/portal/gadgets/
2. Then create a dashboard (let's say our dashboard is pub-sub) using any two of the existing gadgets (NOT our two gadgets) in UES dashboard.
3. Open up UES_HOME/repository/deployment/server/jaggeryapps/pub-sub and open up the index.jag
4. Search for word .xml and you will find two of them.
5. Replace those two urls with the following and save the index.jag file.
             http://localhost:9763/portal/gadgets/publisher/publisher-gadget.xml
             http://localhost:9763/portal/gadgets/subscriber/subscriber-gadget.xml

So your index.jag will have two snippets as follows.

     <li class="layout_block " data-sizey="2" data-sizex="2" data-col="1" data-row="2" 
                data-url="http://localhost:9763/portal/gadgets/publisher/publisher-gadget.xml" 
                data-wid="5" data-prefs="{}" data-title="">

     <li class="layout_block " data-sizey="2" data-sizex="2" data-col="3" data-row="2"
                data-url="http://localhost:9763/portal/gadgets/subscriber/subscriber-gadget.xml" 
                data-wid="6" data-prefs="{}" data-title="">

6. And then access the dashboard as https://localhost:9443/pub-sub/
7. You'll see a dashboard as given in the below image.

8. Click on "Publish a random number" button in the publisher gadget and observe that the same number getting printed in the subscriber gadget as well.

9. Try clicking on the same button several times and observe the subscriber gadget updating its content accordingly.

You can download the complete code of the above two gadget from here.

Real World Scenario
Let's say we have a time slider as the publsiher gadget. Upon a time period selection on the slider, we need to display the number of builds per apps within that period in a seperate gadget. So the later gadget acts as the subscriber by listening to the time slider gadget's channel.

You can do whole lot of things with WSO2 UES pub-sub model :)
Enjoy !!!

Acknowledgement
- Thanks to the WSO2 Gadget Server ( currently deprecated )  documentation on pub-sub model.