Introduction to WSO2 Dashboard Server (WSO2 DS) – Part 2

  This is the second blog about the introduction of the WSO2 Dashboard Server. Here you can read part 1. In this second part of the introduction we are going to study how to create a Gadget using a Gadget Author role (user). This gadget is accessed by DashBoard editor and viewers rol.

• Creating a Gadget
• Configuring Customized User Preference Settings
• Configuring Gadget for Inter-gadget Communication

Creating a Gadget

This gadget is going to be created by a gadget author. After that, it can be added to WSO2 DS. This object can be used to create a dashboard.

• Step 1 – Gadget folder

We are going to create a folder to store our gadget.

• Goto: <DS_HOME>/repository/deployment/server/jaggeryapps/portal/store
• Make another folder inside. Use a Tenant name.

(A Tenant is a user of a single server/cluster that is going to be used or shared by other tenants at the same time. With this strategy the same resources are shared between users.)

For example:

<DS_HOME>/repository/deployment/server/jaggeryapps/portal/store/yenlo

• Go inside the new folder and create a new one with the name of the gadget you are going to create.

For example:

<DS_HOME>/repository/deployment/server/jaggeryapps/portal/store/yenlo/team_project 

• Step 2 – XML of the Gadget

The skeleton of a Gadget is a xml file. This file is going to be used to display information in a HTML document. Example of this file that it is going to be created in:

<DS_HOME>/repository/deployment/server/jaggeryapps/portal/store/yenlo/team_project/gadget1.xml

On the same folder can appear another set of files used by the gadget file like: javascript files, images, style files.

The xml file has this basic tree structure:

<Module>
        <ModulePrefs></ModulePrefs> 
        <Content></Content>
</Module>

Module: This part defines the configuration of a Gadget.

ModulePrefs: Contains the configuration details.

Example:

<ModulePrefs title="Yenlo Projects " height="400" description="List of projects in Yenlo (Subscribe) " tags="drilldown">

<Require feature="dynamic-height" /> (Gives a gadget the ability to resize itself.)<Require feature="pubsub-2" />  (This is to pass messages from one gadget to another.)</ModulePrefs> 

Content: It has a data set to be displayed to user. It can be html or url type.

Example:

<Content type=”html”>
         <![CDATA[html code]]>
</Content>

A set of this type of files can be found at: /WSO2/wso2ds-2.0.0/samples

A good resource to learn how to create gadgets can be found at: https://developers.google.com/gadgets/docs/gs#Hello_World

• Step 3 – The gadget.json file.

This file configures gadget’s behaviour. This file is stored in:

<DS_HOME>/repository/deployment/server/jaggeryapps/portal/store/<TENANT_NAME>/<GADGET_NAME>

on our example:

<DS_HOME>/repository/deployment/server/jaggeryapps/portal/store/yenlo/team_project

  { 
"id":"linechart",
      "title":"Yenlo Projects",
      "type":"gadget",     <-- Type of document.
"thumbnail":"store://gadget/DrillDown_LineChart/images/index.png",
"options":{   },
"data":{  <-- Data file config. It is going to be a htmt content type.
"url":"store://gadget/DrillDown_LineChart/index.xml"
   },
"notify":{  <-- This gadget is a publisher.
"history":{  <-- Name of the channel used to publish messages.
"type":"year", <-- Type of the publisher.
"description":"This notifies the selected year"
}
},
"listen":{  <-- This gadget is subcribed to a channel.
"state":{ 
"type":"state", <-- Publisher channel this gadget is listen to.
"description":"Used to filter based on state"
}
}

Configuring Customized User Preference Settings

The user preferences can be rendered in a different way, in other words, can be customized. User specific info, related with a Gadget, can be added on Dashboard View mode. This can be done by viewers and editors roles.

Dashboard viewer changes are saved in user’s space in the registry. On this way a viewer can display a customized version of the dashboard.

Dashboard editor changes are saved in the original registry space of the dashboard.

The user preferences can appear in the standard view. To do so, the user preferences must to be added in the <UserPref> tag. 

With a customized user preference view, WSO2 DS renders the customized user preferences settings view into the gadget.

To update the gadget view, use settings toggle button and enter the user preference details, click on that button again. The changes are going to be saved into UserPrefs.

How define the user preferences of a gadget:

1. Go to the gadget folder.

<DS_HOME>/repository/deployment/server/jaggeryapps/portal/store/yenlo/team_project

2. Include user preferences view in the <Content> tag.

<Module>
<Content type="html" view="settings">
   <![CDATA[
   Define the settings here
]]>
</Content>
</Module>

An example of a gadget xml:

<Module>
  <ModulePrefs title="USA Map" description="USA clickable map"><Require feature="dynamic-height" />
   <Require feature="setprefs" />
   <Require feature="pubsub-2" />
 </ModulePrefs>
 <UserPref name="username"default_value="trm@yenlo.com" />
 <Content type="html" view="home"><![CDATA[<html>
<head>
<style>
  #map {
   height: 100%;
   width: 100%;
  }
  …
</style>
</head>
<body>
<div>
<label id="defaultViewLabel">USA MAP (This is default view)</label><svg id="map" viewBox="0 0 1000 800" preserveAspectRatio="xMidYMid"></svg>
<script src="../../../js/jquery-1.10.2.js"></script>
<script src="js/uStates.js"></script>
<script src="js/d3.v3.min.js"></script>
<script>
  var click = function(state) {
  var address = { country: 'US', state: state.id };
  …
</script>
</div>
</body>
</html>]]></Content>
  <Content type="html" view="full"><![CDATA[<html>
<head>
<style>
…
</style>
</head>
<body>
<div>
<label id="fullViewLabel">USA MAP(this is full screen view)</label>
<svg id="map" viewBox="0 0 1000 800" preserveAspectRatio="xMidYMid"></svg>
<script src="../../../js/jquery-1.10.2.js"></script>
<script src="js/uStates.js"></script>
<script src="js/d3.v3.min.js"></script>
<script>
…
</script>
</div>
</body>
</html>]]></Content>
 <Content type="html" view="settings"><![CDATA[This is settings]]></Content>
</Module>

Configuring Gadget for Inter-gadget Communication

We are going to configure a gadget to use Public subscribe pattern.

• Step 1 – Publish the data in the publisher.

Configure the gadget as a publishers. To do so, define a gadget publishing channel in the gadget.json file.

Code format: gadgets.Hub.publish(publisher_channel_name, message)
publisher_channel_name – Name of the channel.
message                                – Data to publish through the channel.

Example:
var message = "Publisher channel";
gadgets.Hub.publish('publisher', message);

• Step 2 – Configure a pub-sub link between the publisher and subscriber.

Now we connect to the channel to receive data.

Code format: gadgets.Hub.subscribe(listener_name, function (topic, message, subscriber_data)    {
                                   //put your code here
               })

listener _name    – Name of the listener channel.
topic                      – Publisher channel.
message               – Data published by a publisher.
Subscriber_data – Subscriber channel or listener channel.

Example:

gadgets.HubSettings.onConnect = function() {

    gadgets.Hub.subscribe(‘subscriber’, function(topic, data, subscriberData) {

        // Rest of the call back code goes here
       });
       };

This blog is based on documentation of WSO2. See also: http://wso2.com/products/dashboard-server/

If you would like to read information about other WSO2 products like the WSO2 API Manager, WSO2 Identity Server or WSO2 Enterprise Service Bus, feel free to have a look here or contact the WSO2 Gurus.

{{cta(‘d8004418-ade6-4e7c-b9b6-e58d0ed55010’)}}