Listening events

Access dashboard settings via event handlers

Overview

A event is an action that takes place in a dashboard at load time or triggered by other specific actions.

Registering for an event

You can register an event handler for any of the events above in the following way:

// Event handler registration
ubidots.on('<event>', eventHandler);

// Event handler definition
function eventHandler(args){
    // event handler's logic
};

or

// Event handler definition and registration
ubidots.on('<event>', function(data){
    // event handler's logic
});

The event handler function's arguments must match the event signature.

Available events

You can register event handlers for the following events:

Event	Triggered
receivedToken	At dashboard load time, when the token information is being retrieved.
selectedDashboardDateRange	Whenever the dashboard's date range is changed via GUI or a calling to the corresponding method.
isRealTimeActive	Whenever the dashboard's real time setting is changed via GUI or a calling to the corresponding method
dashboardRefreshed	When a user clicks the refresh button in the dashboard.
selectedDevices selectedDeviceObjects selectedDevice [DEPRECATED] selectedDeviceObject [DEPRECATED]	When the selected device in a dynamic dashboard is changed via GUI or a calling to the corresponding method.
selectedDashboardObject	At dashboard load time, when the dashboard information is being retrieved.
selectedFilters	After changing the dashboard's filters configuration
ready	At dashboard load time, after all other events have been triggered.

receivedToken

Handler argument: token: string ⇒ The user's default token.

Signature

function eventHandler(token) { }

Important note: The retrieved token inherits the users pemissions, either if it's an account admin, in which case it will have all permissions over the account resources accesible through the API, or an End-user, where access will be limited to its configured permissions.

selectedDashboardDateRange

Handler argument: timeframe: Object ⇒ The dashboard's timeframe.

{
    start: <start-timestamp>,
    end: <end-timestamp>
}

Signature

function eventHandler(timeframe) { }

isRealTimeActive

Handler argument: rt: Bool ⇒ The dashboard's real time update setting.

Signature

function eventHandler(rt) { }

dashboardRefreshed

Handler argument: None

Signature

function eventHandler() { }

selectedDevices

Handler argument: deviceIds: [string] ⇒ String array of the id's of the currently selected devices in a dynamic dashboard

Signature

function eventHandler(deviceIds) { }

selectedDeviceObjects

Handler argument: deviceObjects: [Objects] ⇒ Object array of the device objects of the currently selected devices in a dynamic dashboard

Signature

function eventHandler(deviceObjects) { }

selectedDashboardObject

Handler argument: dashboardObject: Object ⇒ dashboard object

Signature

function eventHandler(dashboardObject) { }

selectedFilters

Handler argument: dashboardFilters: [[Object]] ⇒ Array of arrays containing the filter objects. Each nested array corresponds to a filter configured on the dashboard.

[
   [
      {
         "type":"value",
         "value":"60",
         "variables":"~temperature",
         "lookup":"lte",
         "negate":false
      },
      {
         "type":"value",
         "value":"30",
         "variables":"~temperature",
         "lookup":"gte",
         "negate":false
      }
   ],
   [
      {
         "type":"value",
         "value":"60",
         "variables":"~humidity",
         "lookup":"lte",
         "negate":false
      },
      {
         "type":"value",
         "value":"30",
         "variables":"~humidity",
         "lookup":"gte",
         "negate":false
      }
   ]
]

Signature

function eventHandler(dashboardFilters) { }

ready

Handler argument: None

Signature

function eventHandler() { }

Events relation with the class' properties

Each of the events mentioned above 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	selectedDeviceObject
selectedDevice	selectedDevice
selectedDeviceObjects	selectedDeviceObjects
selectedDevices	selectedDevices
token	receivedToken
realTime	isRealTimeActive

For example, you can configure an event to retrieve data from the selected device each time the dashboard's device picker is used, as shown below:

ubidots.on('selectedDeviceObject', function(device) {
    // Do something with the currently selected device data.
    // const deviceId = device.id;
    // const deviceLabel = device.label;
});

This way, everytime that the device picker is used, the logic within the event will be executed. As an alternative to this, if you don't require to perform an action upon the event triggering but only require the data of the currently selected device, you can just access the property related to the event as:

const deviceId = ubidots.selectedDevice;