Manually Creating a Custom Gadget

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

Step 1 - Create a folder structure for the new gadget

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

Navigate to the <DAS_HOME>/repository/deployment/server/jaggeryapps/portal/store directory.
Navigate to the respective tenant directory.
This folder gets automatically created when a tenant is created via the DAS Management Console.
<DAS_HOME>/repository/deployment/server/jaggeryapps/portal/store/<TENANT_DOMAIN>

Example:
<DAS_HOME>/repository/deployment/server/jaggeryapps/portal/store/test.com
Create a folder based on the name of the gadget in the newly created tenant directory.
<DAS_HOME>/repository/deployment/server/jaggeryapps/portal/store/<TENANT_DOMAIN>/fs/gadget/<GADGET_NAME>

Example:
<DAS_HOME>/repository/deployment/server/jaggeryapps/portal/store/test.com/fs/gadget/lineChart

Step 2 - Define the gadget XML

Gadgets are defined using an XML file, which can be later rendered using Shindig to HTML document. This file is mandatory when creating a gadget. Create this XML file within the <DAS_HOME>/repository/deployment/server/jaggeryapps/portal/store/<TENANT_DOMAIN>/fs/gadget/<GADGET_NAME> directory, and use any name to name the gadget XML file. Generally, for standardization purposes, the gadget XML files that are shipped with WSO2 DAS are named as index.xml.

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 a gadget configuration element. This can contain attributes and child elements.
Example
```
<ModulePrefs title="Line Chart" description="Line chart">
    <Require feature="dynamic-height"/>
</ModulePrefs>
```
The Require element is used to define features that are used in the gadget. In this sample, it adds the dynamic-height feature.

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>

Click here for an example index.xml.

For example, if you look at the following index.xml file, you can see that the HTML content is normal HTML content where we load scripts, styles and define HTML elements to load visual contents.

<Module>
    <ModulePrefs title="Line Chart" description="Line chart">
        <Require feature="dynamic-height"/>
    </ModulePrefs>
    <Content type="html">
        <![CDATA[
        <head>
            <script src="/portal/libs/analytics-wso2-2.0.0/d3.min.js"></script>
            <script src="/portal/libs/analytics-wso2-2.0.0/vega.js"></script>
            <script src="/portal/libs/analytics-wso2-2.0.0/VizGrammar.min.js"></script>
            <script>
                var data =  [
                          {
                            "metadata" : {
                                "names" : ["rpm","torque","horsepower", "EngineType"],
                                "types" : ["linear","linear", "ordinal","ordinal"]
                            },
                            "data": [
                              [0, 10, 1, "Piston"], [0, 10, 1, "Rotary"]]
                          }
                        ];
                        var config = {
                          x : "rpm",
                          charts : [
                            {type: "line",  y : "torque", color: "EngineType"}
                          ],
                          maxLength: 20,
                          width: 500,
                          height: 250
                        }
                        var lineChart = new vizg(data, config);
                        lineChart.draw("#canvas");
                        var iterations = 1000;
                          (function insertLoop(i) {
                              setTimeout(function () {
                                var x = iterations-i + 1;
                                lineChart.insert([[x, Number((Math.random() * 100).toFixed(2)), 2, "Rotary"]]);
                                lineChart.insert([[x, Number((Math.random() * 100).toFixed(2)), 1, "Piston"]]);
                                  if (--i) insertLoop(i);
                               }, 500)
                        })(iterations);
            </script>
        </head>
        <body>

            <div id="canvas"></div>
        </body>
        ]]>
    </Content>
</Module>

If you wish to learn more on creating gadget XMLs, go to https://developers.google.com/gadgets/docs/gs.
In addition, if you do not want the user preferences to be rendered using the default view, customize the way in which the user preferences should appear. For more information, see Configuring Customized User Preference Settings.

Step 3 - Define the `gadget.json` file

The gadget.json file is a configuration file that is specifically used for a gadget. This file is mandatory when creating a gadget. Create the gadget.json file in the <DAS_HOME>/repository/deployment/server/jaggeryapps/portal/store/<TENANT_DOMAIN>/fs/gadget/<GADGET_NAME> directory.

The name of the JSON file should always be gadget.json; therefore, ensure not to change the name of the JSON file.

{
    "id": "lineChart",
    "title": "Line Chart",
    "type": "gadget",
    "thumbnail": "gadget/lineChart/index.png",
    "settings": {
        "personalize": true
    },
    "data": {
        "url": "gadget/lineChart/gadget.xml"
    },
    "description": "Allows to view line chart"
}

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

id - The gadget ID should be unique and it should be identical to the gadget directory name (<GADGET_NAME>), which is specified in the <DAS_HOME>/repository/deployment/server/jaggeryapps/portal/store/<TENANT_DOMAIN>/fs/gadget directory.
title - This is the name that is displayed as the gadget name in the WSO2 DAS portal. This name should be identical to the title defined in the gadget XML.
thumbnail - This defines the path to the image that is used as the gadget thumbnail.
type - This defines the type of the document that is rendered by Shindig. In this case, specify the document type as gadget.
data - This contains the URL of the location to the gadget XML file (e.g., index.xml) that corresponds to the gadget.

Step 4 - Add any other required folders/files

The gadget that is being created may need supporting files. For example, the gadget XML file which you created in Step 2, may refer to certain javascript libraries. You may also need a thumbnail image as the gadget icon. These files too need to be added to the <DAS_HOME>/repository/deployment/server/jaggeryapps/portal/store/<TENANT_DOMAIN>/fs/gadget/<GADGET_NAME> directory.

In this example, you need the following.

An image that is used as the gadget icon. You can download the image used in this example from here. Add the image to <DAS_HOME>/repository/deployment/server/jaggeryapps/portal/store/<TENANT_DOMAIN>/fs/gadget/<GADGET_NAME> folder. Note that this image is being referred in the gadget.json file, created in Step 3.

For more information on other folders and files that you can include, see the default folder structure of a gadget that is created when generated using the wizard.

Step 5 - Add the gadget to the dashboard

This step involves selecting the gadget you created for the purpose of visualizing processed data. To add the gadget to a dashboard,follow the procedure given below.

Access the WSO2 DAS Analytics Dashboard using the following URL.
https://<HOST_NAME>:<PORT>/portal/dashboard
Enter your username and password, and click Login.
Add a dashboard named TestDashboard as described in Analytics Dashboard - Create a new dashboard.
Click the following icon for gadgets.

The custom gadget named Line Chart that you created is displayed in the gadget store with the following icon.
Drag and drop the Line Chart to your dashboard.

Step 6: View the gadget in the dashboard

To visualize processed data in the custom gadget you created, log into the WSO2 DAS Analysis Dashboard if you are not already logged in, and click View in the US Population dashboard that is displayed as shown below.

The Line Chart gadget is displayed as follows.

In this example, this gadget is populated with the data hardcoded in the index.xml file added in Step 2 - Define the gadget XML.

You can modify the index.xml file and make the gadget get populated with some other datasource of your choice. Refer the sample gadget here which uses an RDBMS source to populate the gadget.