HTML Canvas Widget: Interacting with account data

Requirements

Ubidots account: Professional plan or above.

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.

1.1. 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 an HTML Canvas

Step 1:Click on the "+" button located at the upper right corner. A drawer menu with widget's options should open.
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. Ubidots HTML Canvas library

The Ubidots HTML Canvas Library serves as the link between the HTML Canvas Widget and the dashboard, allowing their interaction. Accessed through the Ubidots class, this library offers methods, events, and properties that enable data retrieval and dashboard configuration.

Events usage

Use each event as the code snippet below shows, replacing 'UbidotsEvent' with any of the events listed in the next section. Also, you'd have to accommodate the function's argument according to the event.

const ubidots = new Ubidots();

ubidots.on('UbidotsEvent', function(data){
    //Some logic
});

Pro tip: If the Preload dashboard data features is enabled, it is not required to instantiate the Ubidots class since it already has.

4. Available events and properties

Listening events

Event	Description	Result
`receivedToken`	Default account token	`BBFF-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`
`selectedDevices`	Returns a list containing the ids of the selected devices in a dynamic dashboard	`['device-1-id', 'device-2-id', ... ]`
`selectedDeviceObjects`	Returns a list containing the device objects of the selected devices in a dynamic dashboard	`[{"name": "device-name", "id": "device-id", "label": "device-label"}, ... ]`
`selectedDevice`	[DEPRECATED] Use `selectedDevices` instead. Returns the id of the currently selected device in a dynamic dashboard.	`'device-1-id'`
`selectedDeviceObject`	[DEPRECATED] Use `electedDeviceObjects` instead. Returns the device object of the currently selected device in a dynamic 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`

Each of those events is related to a property within the Ubidots class that can be used to retrieve exactly the same data as an alternative to setting an event handler and waiting for the event:

Ubidots class property	Associated event
`dashboardDateRange`	`selectedDashboardDateRange`
`dashboardObject`	`selectedDashboardObject`
`deviceObject`[DEPRECATED]	`selectedDeviceObject`[DEPRECATED]
`selectedDevice`[DEPRECATED]	`selectedDevice`[DEPRECATED]
`selectedDeviceObjects`	`selectedDeviceObjects`
`selectedDevices`	`selectedDevices`
`token`	`receivedToken`
`realTime`	`isRealTimeActive`

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.	`{"endTime": "now", "startTime": "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.	`-`
`setFullScreen`	Enable, Disable, or Toggle the Dashboard into Fullscreen	`toggle` : toggles the Fullscreen state of the Dashboard `enable` : sets the Dashboard to Fullscreen `disable`: takes the Dashboard out of Fullscreen.

5. Examples

5.1. Interacting with dashboard data

The following example uses Ubidots' "listener events" on an HTML Canvas in order to extract information from Ubidots and display it on the 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('selectedDeviceObjects', 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."
});

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.

5.2. Set a device in a Dynamic Dashboard

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;
}

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();
});

3rd party library

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

5.3. 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>

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;
}

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

5.4. Activate Dashboard Refresh button from your 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;
}

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

HTML Canvas Widget: Examples

Create an HTML Canvas Widget: Introductory Demo

HTML Canvas Widget: Adding real time using Socket.IO

Connect your Watersens devices over LoRaWAN to Ubidots

HTML Canvas Widget: Using React.js

HTML Canvas Widget: Interacting with account data

Requirements

1. Introduction

1.1. How does the HTML Canvas widget work?

2. Creating an HTML Canvas

3. Ubidots HTML Canvas library

4. Available events and properties

5. Examples

5.1. Interacting with dashboard data​

5.2. Set a device in a Dynamic Dashboard

5.3. Turn on/off Dashboard Real Time

5.4. Activate Dashboard Refresh button from your HTML Canvas

5.1. Interacting with dashboard data