Dashboard Engine Javascript API

Description

A JavaScript API has been created to communicate the platform panel dashboards embedded in iframes with framework applications by passing messages and authenticating with OAuth2 from the presentation layer of the web browser.

We will rely on the drag-and-drop features native to html5 to improve the user experience.

To complete the functionality, a Rest API has also been created. The panels are managed with it.

The idea is to be able to create, modify and delete boards and their gadgets through an application that works as a framework, through the use of the API.

From this API we can open a board, save it, create by using templates or those of the platform such as LINE, BAR, TABLE, ...

Downloads

We have created an example application, to show the steps to be followed to communicate and receive messages from the platform boards.

We can download it from here frameAPP.html.

To test it, it's best to upload it to the platform as a web project.

We can access: frameAPP example application in cloudlab

First, we will describe what we need.

We have to create a board and a user with permissions to it.

We can create the board with the Rest API or from the Panel control.

Then, we will copy the url from the list of boards:

where clicking on the one we need, we will copy it to the clipboard. In our case, click on the last one. We can also retrieve this URL with the apiRest / dashboard / {id} where {id} is the id of the dashboard.

We can only recover the OAuth2 token. We can do this by following this guide:

(APIs) How to invoke Platform Management APIs with OAuth2 Tokens

With these two data, we can now open our board in Edit mode, loading them into the Dashboard Url and OAuth2 Token fields of the board. We press OPEN DASHBOARD and the board will load in the square to the right of these fields.

At this point, what we are doing is calling the function:

openDashboard ()

where the board is loaded with the token as a parameter in the iframe.

If all went well, the blue background will disappear and we will see the loaded board.

The next step would be to click on NEW GADGET and select one of them, for example, BAR.

The gadget that we have indicated will appear on the board.

This is the code associated with the BAR button, where what we do when we click it is to execute the sendMessageCreateWithAxes ('bar') function, passing the ‘bar’ parameter.

<a class="dropdown-item" onclick="sendMessageCreateWithAxes('bar')">BAR</a>

Now we will explain how to create and send the message:

//We will divide this function to see how to use it:
        var iframeEl = document.getElementById('sonIframe');
//With this we have the iframe's reference in a variable.
        var token = $('#token').val();
//In this variable, we save the token to access
        var newName = type + new Date().getTime();
//We generate a random name for the gadget
        var message 
//This variable contains the message that is sent to the dashboard, it will contain all the information that the platform needs to //create the gadget.
//In this case for gadgets with Axes, this is the structure to create the gadget
    "command": "newGadget",
    "authorization": "${token}",
//We pass the token in the message
    "information": {
//Here is the information on how we want the gadget
        "dashboard": "identificationDashboard",
//Dashboard identifier
        "gadgetName": "${newName}",
//Gadget Name
        "gadgetType": "${type}",
//Gadget type, can be one of the predefined platform or the identifier of a gadget template
        "refresh": 10,
//Datasource refresh time
        "ontology": "HelsinkiPopulation",
//Ontology from which we want to retrieve the information, we could use a datasource for which we would put "datasource": "data //source identifier"
        "setupLayout": {
            },
//This is the gadget presentation settings,
            "filtersInModal": false,
//We can indicate whether we want the filters to be displayed in a modal window or with a sidenav
            "hideBadges": false,
//We can show or hide badges
            "hidebuttonclear":false
//We can show or hide the clear button that removes the filters applied from the gadget.

        "axes": {
//Here we indicate the attributes and the series that will be shown on the axes. Here we are indicating that the gadget will have //two series, one for the Helsinki.population attribute and another one for the Helsinki.population_men attribute. If the type of //gadget is mixed, we also add 	"type":"line",	"type":"bar" or	"type":"points" within each element in measuresY
            "nameX": "",
            "nameY": "",
            "measuresY": [{
                    "name": "population",
                    "path": "Helsinki.population",
	      "type":"line"
                },
                {
                    "name": "population_men",
                    "path": "Helsinki.population_men",
	    "type":"bar"
                }
            ],
            "measuresX": [{
                "name": "Helsinki.year",
                "path": "Helsinki.year"
            }]
        }
    }
}`;

Gadgets can also be created with associated filters as we will describe in this section, for which we click for example on "numeric filter"

A gadget with this icon appears: . When pressed, the filter is shown, in this case as a side. In the message, we have indicated to create two numerical filters for the Helsinki parameter, one year as a lower limit and another as an upper limit.

The method we are invoking is this one: sendMessageCreateWithAxesAndFilter ('bar')

If we go to the code of this method, we see that in the message the difference with the previous one is that an array of filters has been added:

"filters": [{
                "id": "yearstart", 
//Filter identifier must be unique for the gadget
                "type": "numberfilter",
//Type of filter, the available ones are:  'textfilter', 'numberfilter', 'livefilter', 'multiselectfilter', //'multiselectnumberfilter', 'simpleselectfilter', 'simpleselectnumberfilter', 'intervaldatefilter'
                "name": "year limit lower",
//Filter text header 
                "initialFilter": false,
//Specify whether we want the filter to be launched when the gadget is loaded or not
                "op": ">",
//Operator 
                "value": "2000",
//Filter's Initial Value
                "field": "Helsinki.year"},
//Attribute of the datasource on which we will filter the data
                {
                "id": "yearend",                
                "type": "numberfilter",
                "name": "year limit upper",
                "initialFilter": false,
                "op": "<",
                "value": "2005",
                "field": "Helsinki.year"}],

To modify an existing gadget, you have to send a message with the command, as we see in the dropOnElement (x, y) function:

var message = ' {"command":"dropOnElement", "authorization":"' + token +
            '", "information":{"x":' + x + ',"y":' + y + '}}';

This is so that from the x and y coordinates of the screen we retrieve the data from the gadget to form the modification message.

The answer will be collected with the eventer code.

In our example, we drag

on the gadget.

The fields will be loaded with the gadget's information.

We click on

And this sends the following message, which modifies the gadget by adding one more series.

//This is the message we send, the difference with the previous one is that we are passing the new series for Helsinki.population_women,
    var message = `{
	"command": "updateGadget",
//Now the command is "updateGadget" 
	"authorization": "${token}",
	"information": {
		"dashboard": "identificationDashboard",
		"gadgetId": "${idGadget}",
		"gadgetName": "${idGadget}",
		"gadgetType": "${typeGadget}",
		"refresh": 10,
		"ontology": "HelsinkiPopulation",
		"axes": {
			"nameX": "",
			"nameY": "",
			"measuresY": [{
				"name": "Helsinki.population_women",
				"path": "Helsinki.population_women"
			}],
			"measuresX": [{
				"name": "Helsinki.year",
				"path": "Helsinki.year"
			}]
		}
	}
}`;