API JavaScript del Dashboard Engine

Descripción

Se ha creado una API de JavaScript para comunicar los dashboards del panel de la plataforma incrustados en iFrames con aplicaciones de framework (marco), pasando mensajes y autenticándose con OAuth2 desde la capa de presentación del navegador web.

Nos apoyaremos en las funcionalidades de drag and drop nativas de html5 para mejorar la experiencia de usuario.

Para completar la funcionalidad se ha creado también una API Rest con la que se gestionan los dashboard.

La idea es poder crear, modificar, y borrardashboards y sus gadgets, a través de una aplicación que funcione comoframework, mediante el uso del API .

Desde esta API podremos abrir un dashboard, guardarlo, crear mediante el uso de nuestras plantillas, o las propios de la plataforma como el LINE, BAR, TABLE,…

Downloads

Hemos creado una aplicación de ejemplo, para mostrar los pasos a seguir para poder comunicarnos y recibir los mensajes de los dashboards de la plataforma.

Puedes descargarla desde aquí: frameAPP.html.

Para probarla, lo mejor es subirla a la plataforma como un proyecto web.

Puedes acceder a: aplicación ejemplo frameAPP en cloudlab

En primer lugar, describe lo que necesitas.

Tienes que crear un dashboard y un usuario con permisos en él.

Puedes crear el dashboard con el API Rest o desde el Control Panel.

Accede al listado de dashboards:

Ahora, copia la url del listado de dashboards:

donde con pulsar encima de la que necesites, se copiará al portapapeles. En nuestro caso clica la última. También puedes recuperar esta URL con el apiRest / dashboard / {id} donde {id} es el identificador del dashboard.

Ya sólo queda recuperar el token OAuth2. Puedes hacerlo siguiendo esta guía:

¿Cómo invocar la API de gestión de plataforma con tokens OAuth2?

Con estos dos datos, ahora puedes abrir tu dashboard tablero en modo Editar, cargándolo en los campos Dashboard Url y Token OAuth2 del dashboard. Pulsa ABRIR DASHBOARD y el dashboard se cargará en el recuadro a la derecha de estos campos.

Aquí lo que estás haciendo es llamar a la función:

openDashboard ()

donde el dashboard se carga con el token como parámetro en el iframe.

Si todo ha ido bien, el fondo azul desaparecerá y verás el dashboard cargado.

El siguiente paso será hacer clic en NUEVO GADGET y seleccionar uno de ellos, por ejemplo, BAR.

En el dashboard aparecerá el gadget que hayas indicado.

Este es el código asociado al botón BAR, donde lo que haces al pulsarlo es ejecutar la función sendMessageCreateWithAxes ('bar'), pasando el parámetro 'bar'.

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

Ahora vamos a explicar cómo crear y enviar el mensaje:

//Dividiremos esta función para ver como usarla:
        var iframeEl = document.getElementById('sonIframe');
//Con esto tenemos la referencia del iframe en una variable.
        var token = $('#token').val();
//En esta variable guardamos el token para acceder
        var newName = type + new Date().getTime();
//Generamos un nombre aleatorio para el gadget
        var message 
//Esta variable contiene el mensaje que se envía al dashboard, contendrá toda la información que necesita la plataforma para crear el gadget.
//En este caso para gadgets con Axes, esta es la estructura para crear el gadget
    "command": "newGadget",
    "authorization": "${token}",
//Pasamos el token en el mensaje
    "information": {
//Aquí esta la informacion de cómo queremos el gadget
        "dashboard": "identificationDashboard",
//Identificador del dashboard
        "gadgetName": "${newName}",
//Nombre del dispositivo
        "gadgetType": "${type}",
//Tipo de gadget, puede ser una plataforma predefinida o el identificador de una plantilla de gadget
        "refresh": 10,
//Tiempo de actualización de la fuente de datos (datasource)
        "ontology": "HelsinkiPopulation",
//Ontología de la que queremos recuperar la información, podríamos usar una fuente de datos para la cual pondríamos "datasource": data //source identifier"
        "setupLayout": {
            },
//Esta es la configuración de presentación del gadget,
            "filtersInModal": false,
//Podemos indicar si queremos que los filtros se muestren en una ventana modal o con un sidenav
            "hideBadges": false,
//Podemos mostrar u ocultar badges
            "hidebuttonclear":false
//Podemos mostrar u ocultar el botón borrar que elimina los filtros aplicados del gadget.
        "axes": {
//Aquí indicamos los atributos y las series que se mostrarán en los ejes. Aquí estamos indicando que el gadget tendrá dos series,
//una para el atributo Helsinki.population y otra para el atributo Helsinki.population_men.
//Si el tipo de gadget es mixto, también agregamos "tipo":"línea", "tipo":"barra" o "tipo":"puntos" dentro de cada elemento en medidasY
            "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"
            }]
        }
    }
}`;

También se pueden crear gadgets con filtros asociados, como describiremos en este apartado. Para ello, pincha por ejemplo en "filtro numérico":

Aparecerá un gadget con este icono: .Al pulsarlo se muestra el filtro, en este caso en un lado. En el mensaje, indica que quieres crear dos filtros numéricos para el parámetro Helsinki, un año como límite inferior y otro como límite superior.

El método que estás invocando es este: sendMessageCreateWithAxesAndFilter ('bar')

Si vas al código de este método, verás que, en el mensaje, la diferencia con el anterior es que se le ha añadido una matriz de filtros:

"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"}],

Para modificar un gadget existente, debes enviar un mensaje con el comando, como ves en la función dropOnElement (x, y:

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

Esto es para que, a partir de las coordenadas x y de la pantalla, se recuperen los datos del gadget para formar el mensaje de modificación.

La respuesta se recogerá con el código eventer.

En este ejemplo, arrastra:

sobre el gadget.

Se cargarán los campos con la información del gadget.

Haz clic en

Y esto envía el siguiente mensaje, que modifica el gadget añadiendo una serie más.

//Este es el mensaje que enviamos, la diferencia con el anterior es que estamos pasando la nueva serie para 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"
			}]
		}
	}
}`;