Requisitos
Cuenta de Ubidots: plan Professional o superior.
1. Introducción
El HTML Canvas es un poderoso widget que permite a los desarrolladores de Ubidots crear visualizaciones especializadas usando la API REST de Ubidots. Los usuarios pueden interactuar con los datos de su cuenta y escuchar los eventos realizados en el dashboard para hacer que el widget responda como lo haría un widget predeterminado de Ubidots.
1.1. ¿Cómo funciona el widget HTML Canvas?
El widget HTML Canvas funciona con el mismo HTML/CSS/JS que usarías al crear un sitio web simple. También considera el caso cuando puedas necesitar usar una tercera biblioteca (por ejemplo, jQuery), por lo que puedes agregarlas insertando una URL que contenga la biblioteca.
Usando esta guía y el widget HTML Canvas podrás:
Recuperar de manera segura el Token de tu cuenta, la información del Dashboard y del Dispositivo.
Escuchar los botones de la barra de navegación en el lado del Dashboard.
NOTA IMPORTANTE: Este artículo está destinado a desarrolladores con conocimientos fundamentales de HTML, JS y CSS.
2. Creando un HTML Canvas
Paso 1: Haz clic en el botón "+" ubicado en la esquina superior derecha. Debería abrirse un menú desplegable con las opciones del widget.
Paso 2: Haz clic en HTML canvas. El menú desplegable muestra opciones de configuración.
Paso 3: Nombra tu widget.
Paso 4: Haz clic en el botón "Abrir editor".
Paso 5: Ingresa tu código HTML, CSS y JS en la pestaña correspondiente.
Paso 6: Agrega bibliotecas ingresando su URL en la sección de "bibliotecas de terceros".
Paso 7: Guarda los cambios.
3. Biblioteca HTML Canvas de Ubidots
La Biblioteca HTML Canvas de Ubidots sirve como el enlace entre el widget HTML Canvas y el dashboard, permitiendo su interacción. Accedida a través de la clase Ubidots, esta biblioteca ofrece métodos, eventos y propiedades que permiten la recuperación de datos y la configuración del dashboard.
Uso de eventos
Usa cada evento como muestra el siguiente fragmento de código, reemplazando 'UbidotsEvent' con cualquiera de los eventos listados en la siguiente sección. Además, tendrás que ajustar el argumento de la función de acuerdo al evento.
const ubidots = new Ubidots();
ubidots.on('UbidotsEvent', function(data){
//Some logic
});
Consejo profesional: Si la característica de Preload dashboard data está habilitada, no es necesario instanciar la clase Ubidots, ya que ya está instanciada.
4. Eventos y propiedades disponibles
Escuchando eventos
Evento | Descripción | Resultado |
| Token predeterminado de la cuenta |
|
| Rango de fechas seleccionado actualmente en el dashboard dinámico (timestamp en milisegundos). |
|
| Este evento se activa cada vez que se hace clic en el botón de Tiempo Real en el Dashboard. |
|
| Este evento se activa cuando un usuario hace clic en el botón de refrescar en el dashboard. |
|
| Devuelve una lista que contiene los IDs de los dispositivos seleccionados en un dashboard dinámico |
|
| Devuelve una lista que contiene los objetos de los dispositivos seleccionados en un dashboard dinámico |
|
| [OBSOLETO] Usa
Devuelve el ID del dispositivo actualmente seleccionado en un dashboard dinámico. |
|
| [OBSOLETO] Usa
Devuelve el objeto del dispositivo actualmente seleccionado en un dashboard dinámico. |
|
| Devuelve el objeto completo de un Dashboard como se recibe al cargar el dashboard |
|
| Devuelve un objeto con la información de todos los otros eventos. Ver ejemplo. |
|
Cada uno de esos eventos está relacionado con una propiedad dentro de la clase Ubidots que se puede usar para recuperar exactamente los mismos datos como una alternativa a configurar un controlador de eventos y esperar el evento:
Propiedad de la clase Ubidots | Evento asociado |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Eventos de configuración:
Evento | Descripción | Argumentos |
|
|
|
|
|
|
|
|
|
| Habilidad para refrescar los datos del dashboard en todos los widgets. |
|
| Habilitar, deshabilitar o alternar el estado de pantalla completa del Dashboard |
|
5. Ejemplos
5.1. Interactuar con datos del dashboard
El siguiente ejemplo utiliza los "eventos de escucha" de Ubidots en un HTML Canvas para extraer información de Ubidots y mostrarla en el dashboard:
HTML
<div>
<p id="token"></p>
<p id="dashboard"></p>
<p id="dateRange"></p>
<p id="deviceSelected"></p>
<p id="device"></p>
<p id="isRealTimeActive"></p>
<p id="dashboardRefreshed"></p>
<p id="eventToken"></p>
<p id="eventDashboard"></p>
<p id="dashboardDateRange"></p>
<p id="eventDeviceSelected"></p>
<p id="eventDevice"></p>
<p id="eventRefresh"></p>
<p id="eventisRealTimeActive"></p>
</div>
JavaScript
var ubidots = new Ubidots();
ubidots.on('receivedToken', function (data) {
document.getElementById('eventToken').innerText = "TOKEN: " + data;
});
ubidots.on('selectedDashboardObject', function (data) {
document.getElementById('eventDashboard').innerText = "Dashboard Object: " + JSON.stringify(data)
});
ubidots.on('selectedDashboardDateRange', function (data) {
document.getElementById('dashboardDateRange').innerText = "Dashboard date range: " + JSON.stringify(data);
});
ubidots.on('selectedDevices', function(data) {
let listOfIds = data.join(', ');
document.getElementById('eventDeviceSelected').innerText = "Selected Device ids: " + listOfIds;
});
ubidots.on('selectedDeviceObject', function (data) {
let formattedData = JSON.stringify(data); // 2-space indentation
document.getElementById('eventDevice').innerText = "Device Object: \n" + formattedData;
});
ubidots.on('isRealTimeActive', function (data) {
document.getElementById('eventisRealTimeActive').innerText = "Real time button: " + JSON.stringify(data);
});
ubidots.on('dashboardRefreshed', function (data) {
document.getElementById('eventRefresh').innerText = "The Dashboard refresh button was pressed."
});
NOTA IMPORTANTE: No es necesario agregar ninguna biblioteca externa para usar estos métodos y propiedades, Ubidots agrega bibliotecas para hacer esto por defecto una vez que has creado el widget HTML Canvas.
5.2. Establecer un dispositivo en un Dashboard Dinámico
HTML
<div class="set-device--container">
<p>Device set successfully</p>
<input type="text" placeholder="Enter Device id" class="set-device--input" id="device" />
<button type="button" class="set-device--button" id="send-value">Set device</button>
</div>
CSS
.set-device--container {
position: absolute;
top: 50%;
left: 50%;
transform: translate(-50%, -50%);
}
.set-device--input {
display: block;
margin: 0 auto;
border: none;
border-bottom: 2px solid #28AECD;
font-size: 14px;
outline: none;
}
.set-device--button {
background: #FFFFFF;
border: 2px solid #28AECD;
border-radius: 20px;
color: #28AECD;
font-size: 14px;
margin-top: 10px;
width: 100%;
}
.set-device--button:hover {
background: #28AECD;
color: #FFFFFF;
cursor: pointer;
}
.notification--container {
display: none;
}
JS
var $setDevice = $('#send-value');
var $notification = $('#notification');
var ubidots = new Ubidots();
$setDevice.on('click', function () {
var $device = $('#device'); // Ensuring declaration of the variable
ubidots.setDashboardDevice($device.val());
$notification.show();
});
Biblioteca de terceros
https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js
5.3. Activar/desactivar el Tiempo Real del Dashboard
HTML
<div class="notification--container" id="notification">
<p>Dashboard Real Time</p>
</div>
<div class="real-time--container">
<button type="button" class="real-time--button" id="real-time">
Enable real time
</button>
</div>
CSS
.real-time--container {
position: absolute;
top: 50%;
left: 50%;
transform: translate(-50%, -50%);
}
.real-time--button {
background: #FFFFFF;
border: 2px solid #28AECD;
border-radius: 20px;
color: #28AECD;
font-size: 20px;
margin-top: 10px;
width: 100%;
}
.real-time--button:hover {
background: #28AECD;
color: #FFFFFF;
cursor: pointer;
}
.notification--container {
display: none;
}
JS
var $realTime = $('#real-time');
var $notification = $('#notification');
var ubidots = new Ubidots();
$realTime.on('click', function () {
ubidots.setRealTime(true)
$notification.show();
});
Biblioteca de terceros
https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js
5.4. Activar el botón de actualización del Dashboard desde tu HTML Canvas
HTML
<div class="notification--container" id="notification">
<p>Dashboard successfully refreshed</p>
</div>
<div class="refresh-dashboard--container">
<button type="button" class="refresh-dashboard--button" id="refresh-dashboard">
Refresh Dashboard
</button>
</div>
CSS
.refresh-dashboard--container {
position: absolute;
top: 50%;
left: 50%;
transform: translate(-50%, -50%);
}
.refresh-dashboard--button {
background: #FFFFFF;
border: 2px solid #28AECD;
border-radius: 20px;
color: #28AECD;
font-size: 14px;
margin-top: 10px;
width: 100%;
}
.refresh-dashboard--button:hover {
background: #28AECD;
color: #FFFFFF;
cursor: pointer;
}
.notification--container {
display: none;
}
JS
var $refreshDashboard = $('#refresh-dashboard');
var $notification = $('#notification');
var ubidots = new Ubidots();
$refreshDashboard.on('click', function () {
ubidots.refreshDashboard()
$notification.show();
});
Biblioteca de terceros
https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js