Dashboard Developer Documentation

Inter-Widget Communication

Widgets on a card may need to communicate, passing information to each other, and achieving synchronized behaviors. Only widgets on the same card can communicate. A widget can both send and receive messages. Both types of mechanisms shown below can be implemented for each widget. When a widget sends a message, all widgets on the card that are configured for receipt can use the message.

When creating widgets:

Include 'APM.WidgetBehavior' as part of the behaviors in the Polymer components.
For example, include inheritance of APM.WidgetBehavior as part of APM.WidgetErrorBehavior or APM.RefreshBehavior.
For widgets that send a message to other widgets, call the following function and pass the message through it: this._sendWidgetMessage(message);
This function is provided by the framework. The parameter to this function is a regular javascript object. This object can contain only data and not functions. The framework performs a stringify on this object and therefore any function declarations would be ignored and not sent to the widgets.
Note: The details of the message object should be well documented by the widgets that intend to send the message. This helps other widgets to know the right contracts to use when the message is received.
For widgets that receive a message from other widgets, use the following attribute in the Polymer component available through the framework: this.incomingWidgetMessage
This attribute has the following structure:
```
{
senderId:string//'The id of the sender widget component',
timestamp:string//'Timestamp of the message',
payload:object//An object which is the message sent by the sender widget
}
```
This attribute is available to the receiving widget to use anywhere and gets updated every time the sender sends a new message.
For widgets that receive a message from other widgets, you can implement the following function: '_incomingWidgetMessageReceived()'
This is a function declaration that the framework executes every time the message is updated by the sender widget.
```
_incomingWidgetMessageReceived: function() {
var msg = this.incomingWidgetMessage.payload;
console.log("New widget payload is: ", msg);
}
```
This function can be used by the receiving widget to implement custom functionality driven by the message, every time the message is updated by the sender.

Following are examples of two Polymer components representing two widgets that send and receive messages.

Widget 1:

<dom-module id="widget1-widget">
  <template>
    <div id="widget1-container">
      <div>Incoming payload: [[incomingWidgetMessage.payload.fullName]]</div>
      <i class="fa fa-paper-plane" on-click="sendMessage" title="Send Message">Send Message to other widgets</i>
    </div>
  </template>
</dom-module>
<script>
  Polymer({
    is: 'widget1-widget',
    //Just get the message and print it
  _incomingWidgetMessageReceived : function(){
      var msg = this.incomingWidgetMessage.payload;
      console.log("New widget message in widget1 is: ", msg);
    },

    //Create a person object with a unique full name on every invocation and send it to other widgets
  sendMessage : function(){
      var letter = String.fromCharCode(97 + Math.floor(Math.random() * 26));
      var person = {
        "fullName" : "John Smith " + letter
      };
      console.log("Sending message from widget1: ", person);
      this._sendWidgetMessage(person);
    },

    behaviors: [APM.WidgetBehavior]
  });
</script>

Widget 2:

<dom-module id="widget2-widget">
  <template>
    <div id="widget-container">
      <div>Incoming payload: {{anotherProperty}}</div>
      <i class="fa fa-paper-plane" on-click="sendMessage" title="Send Message">Send Message to other widgets</i><br>
      <i class="fa fa-bolt" on-click="changeProperty" title="Change Message">Change Message 1</i><br>
    </div>
  </template>
</dom-module>
<script>

Polymer({

  is: 'widget2-widget',

  properties: {
    anotherProperty : {
      type: String,
      notify:true
  }
    },
//From the incoming message get the fullName and set it to a local property.
//This is to show how other properties can be updated based on an incoming message
 _incomingWidgetMessageReceived : function(){
      var msg = this.incomingWidgetMessage.payload;
      console.log("New widget payload in widget2 is: ", msg);
      this.anotherProperty = msg.fullName;
    },
 
 //It sets the payload and the value of the property to a new unique name upon every invocation
  changeProperty : function(){
      if(this.incomingWidgetMessage.payload.fullName){
        var letter = String.fromCharCode(97 + Math.floor(Math.random() * 26));
        this.incomingWidgetMessage.payload.fullName = 'Jane Wong ' + letter;
        this.anotherProperty = this.incomingWidgetMessage.payload.fullName;
      }
    },

  //This takes the latest value in the payload and sends it to other widgets
  sendMessage : function(){
      console.log("Sending message from Monitoring widget: ", this.incomingWidgetMessage.payload);
      this._sendWidgetMessage(this.incomingWidgetMessage.payload);
    },
    behaviors: [APM.WidgetBehavior]
  });
</script>

Dashboard Developer Documentation

About Widget Development

Inter-Widget Communication