Requirements

  • Ubidots account: trial or licensed

Table of Contents

  1. Introduction

  2. Creating and HTML Canvas

  3. Methods and available properties

  4. Examples

1. Introduction

The HTML canvas is a powerful widget that allows Ubidots developers to create specialized visualizations using Ubidots API REST. Users can interact with their account data and listen to the events made on the dashboard to make the widget respond as a default Ubidots widget would.

How does the HTML Canvas widget work?

The HTML Canvas widget works with the same HTML/CSS/JS you would code when creating a simple website. It also considers the case when you may need to use a 3rd library (e.g. jQuery), so you can add these by inserting an URL containing the library.

Using this guide and the HTML Canvas Widget you will be able to:

  • Securely retrieve your account's Token, Dashboard and Device information.

  • Listen to navigation bar buttons on the Dashboard side.

IMPORTANT NOTE: This article is intended for developers with foundational knowledge of HTML, JS and CSS.

2. Creating and HTML Canvas

Step 1:Click on the top-right "+" button. Drawer menu with widgets options opens.
Step 2:Click on HTML canvas. Drawer menu displays setup options.
Step 3: Name your widget.
Step 4: Click on "Open editor" button.
Step 5: Enter your HTML, CSS and JS code in the respective tab.
Step 6: Add libraries by entering its URL in the "3rd party libraries section".
Step 7: Save the changes.

3. Methods and available properties

Ubidots support the below methods to be used by developers inside the widget:

Listening events:

Event

Description

Result

receivedToken

Default account token

BFF-XXXXXXXXXX


selectedDashboardDateRange

Actual selected date range in the dynamic dashboard (timestamp in milliseconds).

{"start":1637006467592,"end":1637095008866}


isRealTimeActive

This event is triggered every time the Real Time button in the Dashboard is clicked.


true or false


dashboardRefreshed

This event is activated when a user clicks the refresh button in the dashboard.


true

selectedDevice

Returns the Device id selected in a Dynamic Dashboard

device-id


selectedDeviceObject

Returns the whole object of a Device as received when loading the dashboard.


{"name": "device-name", "id": "device-id", "label": "device-label"}


selectedDashboardObject


Return the whole object of a Dashboard as received when loading the dashboard


{"id": "dashboard-id", "name": "dashboard-name", "organization_data": {"id": 25, "name": "My First Customer", "properties": {"color": "#00BCD4"}}, "timeframe": {"endDate": "now", "startDate": "now-24h"}}

ready

Returns an object with the information of all the other events. See example.

BBFF-XXXXX

{"start":1651761902036,"end":1651848302036}

5e8bb8644763e72e09658f76

Setter events:

Event

Description

Arguments


setDashboardDevice


Ability to set the selected device in a Dynamic Dashboard


device-id


setDashboardDateRange


Ability to set the date and time range in a dashboard, dynamic or static.

{"endDate": "now", "startDate": "now-24h"}}


setRealTime


Ability to turn on or off the dashboard real time update


true or false


refreshDashboard


Ability to refresh the dashboard data in all widget.


-

4. Examples

The HTML Canvas widget is divided into three coding slots: HTML, CSS and JS, there isn’t any CSS as this tutorial is not intended for the widget's visual design, to learn how to use it please refer to HTML Canvas Widget Examples.

Ubidots(): Constructor to create an instance.
on({{listener}}, callback()) : Each method to trigger a callback based on the listener set as input.

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>

JS

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('selectedDevice', function (data) {
document.getElementById('eventDeviceSelected').innerText = "Selected Device id: " + data;
});

ubidots.on('selectedDeviceObject', function (data) {
document.getElementById('eventDevice').innerText = "Device Object: " + JSON.stringify(data);
});

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."
});

This JavaScript code changes the actual paragraph using the available listeners and triggering a callback that will fill the HTML meta-tags with the data provided by Ubidots. This implementation is appropriate when you wish to implement any additional logic encapsulated within an anonymous function.

Another workaround, instead of triggering an anonymous function, is to fill the HTML properties using the Ubidots object instance. This way could be useful to create actions that will be triggered just once.

JS

var ubidots = new Ubidots();

ubidots.on('ready', function () { document.getElementById('token').innerText = ubidots.token; document.getElementById('device').innerText = ubidots.selectedDevice; document.getElementById('dateRange').innerText = JSON.stringify(ubidots.dashboardDateRange);});


IMPORTANT NOTE: There is no need to add any external library to use these methods and properties, Ubidots adds libraries to do this by default once you've created the HTML Canvas widget.


Set a device in a Dynamic Dashboard

HTML

<div class="notification--container" id="notification">
<p>Device set successfully</p>
</div>

<div class="set-device--container">
<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 {
left: 50%;
position: absolute;
top: 50%;
transform: translate(-50%, -50%);
}

.set-device--input {
border: none;
border-bottom: 2px solid #28AECD;
display: block;
margin: 0 auto;
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;
cursor: pointer;
color: #FFFFFF;
}

.notification--container {
display: none;
}

JS

var $setDevice = $('#send-value');
var $notification = $('#notification');

var ubidots = new Ubidots();

$setDevice.on('click', function () {
$device = $('#device');
ubidots.setDashboardDevice($device.val())
$notification.show();
});

3rd party library

https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js

Turn on/off Dashboard Real Time

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>

JS

.real-time--container {
left: 50%;
position: absolute;
top: 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;
cursor: pointer;
color: #FFFFFF;
}

.notification--container {
display: none;
}

CSS

var $realTime = $('#real-time');
var $notification = $('#notification');

var ubidots = new Ubidots();

$realTime.on('click', function () {
ubidots.setRealTime(true)
$notification.show();
});

3rd party library

https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js

Activate Dashboard Refresh button from your HTML Canvas

HTML

<div class="notification--container" id="notification">
<p>Dashboard successfully refresh</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 {
left: 50%;
position: absolute;
top: 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;
cursor: pointer;
color: #FFFFFF;
}

.notification--container {
display: none;
}

JS

var $refreshDashboard = $('#refresh-dashboard');
var $notification = $('#notification');

var ubidots = new Ubidots();

$refreshDashboard.on('click', function () {
ubidots.refreshDashboard()
$notification.show();
});

3rd party library

https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js

Other users also found helpful:

Did this answer your question?