Creating a Gadget

A gadget author can create any type of gadgets and add it to WSO2 DS, so that you can make use of them when creating a dashboard.

Follow the instructions below to create a gadget:

Step 1 - Create a folder structure for the new gadget

You need to create the gadget related configurations within a tenant folder as follows:

1. Navigate to the <DS_HOME>/repository/deployment/server/jaggeryapps/portal/store directory.
2. Create a folder by the name of the tenant.
   <DS_HOME>/repository/deployment/server/jaggeryapps/portal/store/<TENANT_NAME>
   
   Example:
   <DS_HOME>/repository/deployment/server/jaggeryapps/portal/store/kim
3. Create a folder based on the name of the gadget in the newly created tenant directory.
   <DS_HOME>/repository/deployment/server/jaggeryapps/portal/store/<TENANT_NAME>/<GADGET_NAME>
   
   Example:
   <DS_HOME>/repository/deployment/server/jaggeryapps/portal/store/kim/age_group

Step 2 - Define the Gadget XML

Gadgets are defined using an XML file, which can be later rendered using Shindig to HTML document. Create this XML file within the <DS_HOME>/repository/deployment/server/jaggeryapps/portal/store/<TENANT_NAME>/<GADGET_NAME> directory, and use any name to name the gadget XML file.

The basic structure of the gadget XML file is as follows:

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

• Module - This is the root element of the XML structure.

• ModulePrefs - This is the gadget configuration element. This can contain attributes and child elements as follows:

  Example

  <ModulePrefs title="Population History" height="350" description="Subscribe to the state channel" tags="drilldown">
     <Require feature="dynamic-height" />
     <Require feature="pubsub-2" />
  </ModulePrefs>

    The Require element is used to define features that are used in the gadget. In this sample, the pubsub-2 and dynamic-height features have been added.

   

• Content - This contains the data that needs to be rendered. In the following example, it contains HTML. When defining the content element, you need to also define the type of the content.

  <Content type=”html”>
  	<![CDATA[ 
  html content goes here 
  ]]>
  </Content>

  
  For example, if you look at the index.xml file in the Line Chart gadget sample, which is in the <DS_HOME>/samples/s0/gadgets/usa-population-history directory you can see that the HTML content is normal HTML content where we load scripts, styles and define HTML elements to load visual contents. The main purpose of this file is to load the PubSub-2 feature using the Require element.

Step 3 - Define the gadget.json file

The gadget.json file is a configuration file that is specifically used by the WSO2 Dashboard Server (DS) for a gadget. Create the gadget.json file in the the <DS_HOME>/repository/deployment/server/jaggeryapps/portal/store/<TENANT_NAME>/<GADGET_NAME> directory. 

{  
   "id":"linechart",
   "title":"Population History",
   "type":"gadget",
   "thumbnail":"store://gadget/DrillDown_LineChart/images/index.png",
   "options":{  

   },
   "data":{  
      "url":"store://gadget/DrillDown_LineChart/index.xml"
   },
   "notify":{  
      "history":{  
         "type":"year",
         "description":"This notifies the selected year"
      }
   },
   "listen":{  
      "state":{  
         "type":"state",
         "description":"Used to filter based on state"
      }
   }
}

The main properties in the gadget.json file are described as follows:

• type - This defines the type of this document to be rendered by the Shindig. 
• data - This contains the URL of the location of the index.xml that corresponds to the gadget.
• notify - This is the most important. This is the property that defines whether this gadget is a publisher or not. By adding this property we can define a channel to publish messages. In this sample, a channel named history is being created. The notify property has two sub properties which are as follows: type and description. The property named type is used to define the type of the publisher.
• listen - This property defines whether this specific gadget can subscribe to a channel or not. A listener named state has been created for this sample, which has the same properties that a publisher channel has. Type will filter the publisher channels that the gadget can listen to.

Step 4 - Add any other required folders

The gadget that is being created may need supporting files such as images etc. These files too need to be added in the <DS_HOME>/repository/deployment/server/jaggeryapps/portal/store/<TENANT_NAME>/<GADGET_NAME> directory.