Dashboards can take a series of "context variables" for changing not only what data to display within your blocks, but also how to display that data on a per-block basis. This makes it possible to set up a common dashboard that can display data specific to any device or attribute.
Defining Context Variables
Before a context variable can be referenced in a block, the variable must first be defined within your dashboard settings. From the settings menu, click "Manage" next to "Dashboard Context". Or, if you do not have any variables defined, click the "Add Context" button.
Alternatively, "Context Variables" can be reached from the left column of your dashboard's "Edit Settings" page.
Each context variable must be given a unique name, which is how the variable is referenced in your dashboard configuration. Each variable type also has its own additional configuration options.
To add a new variable, click the "Add Variable" button on the "Context Variables" screen and then select your variable type from the dropdown menu. There are four variable types ...
A "Device ID" is a device query that takes a single device at a time. Device IDs take three additional parameters:
- Application ID is the Losant application to which any selected device must belong.
- Default Value is the device ID to use when no value is provided by the user.
- Validation is optional; it is a device query that accepts device IDs and/or tags that the variable must match. If both IDs and tags are provided, the variable may match a specific ID, or the tag must be applied to the device. If multiple tags are defined in validation, the device must match all tags (or a provided ID). If no validation rules are provided, then any device from the selected application is valid. Note that the default value does not have to match your defined validation rules.
If a device ID is used in a query with an attribute that is not defined on the device, the block that is referencing the variable will fail to load.
A "Device Tag" is a device query that resolves to a single device tag. This tag can be used to build data queries for groups of devices that have common characteristics. Just like when build queries with device tags, the key or value of a device tage context variable can resolve to a wildcard ('*') or a static value.
Device Tags take three additional parameters:
- Application ID is the Losant application to which any selected device tag must belong.
- Default Value is the device tag to use when no value is provided by the user.
- Validation is optional; it is a device query that accepts multiple device tags that the variable must match. The values must be tags that exist on at least one device within your application – or they can contain wildcard values. Any device tag entered by your dashboard users must match one of these validation tags, if they are provided. For example, if two validation tags of "foo=bar" and "*=world" are provided, a user could provide a context variable value of "foo=bar", or "hello=world", or "goodbye=world".
An "Attribute" is a single device attribute. Attributes take three additional parameters:
- Application ID is the Losant application from which the attribute must originate.
- Default Value is the attribute to use when no value is provided by the user.
- Validation is optional; it is an array of attributes that the user is allowed to select. Every unique attribute from every device within the chosen application will be in the menu. Select one or more of these attributes to limit the user's options; alternatively, by providing no validation, the user may select any attribute from the application. Note that the default value does not have to match your defined validation rules.
The attribute can be of any type (
GPS, etc.) but certain attribute types will fail to display in a number of block configurations. (For example, data for a
String attribute cannot be displayed on a time series graph for most aggregation types.)
A "Number" variable is simply a number: positive or negative, whole or decimal. Number variables take three additional parameters:
- Default Value is the number to use when no value is provided by the user. If min and/or max are defined, the default value must match the validation rules.
- Min is an optional minimum value (inclusive) that the user can set in the variable.
- Max is an optional maximum value (inclusive) that the user can set in the variable.
"String" variables are simply an arbitrary string of characters. Strings take two additional parameters:
- Default Value is the string to use when no value is provided by the user.
- Validation is an optional regular expression that, when set, the user's input for the variable must match. Note that the default value does not have to match the validation.
Setting Context Variables
Once your context variables have been defined, there are three different ways in which the values of those can be set in your dashboard:
The easiest way to change context is to set it within the "Dashboard Context" section of the settings dropdown menu. Every variable you have defined will appear in this form, and all inputs will validate against any rules you have defined.
Device IDs and attributes will take the form of dropdown menus with all valid entries available for selection. Numbers and strings are simple text inputs.
Any input that is left blank is currently set to its default value. Enter any values you would like to change and click the "Update" button at the bottom of the form, and your dashboard will update to reflect the new context.
To clear all values and return the dashboard to its default state, click "Reset to Defaults".
Direct URL Manipulation
Dashboard context settings are stored on the page's URL and changes are logged in your browser's history – meaning that you can use your browser's back and forward arrows to navigate through context changes. This also means that context values can be set by directly editing the page's URL.
Context variables are stored on the query string, and each takes the format of
ctx[VARIABLE_NAME]=NEW_VALUE. (Values must be encoded.) For example, to set a context variable called "myString" to the value of "hello world", you would append
?ctx[myString]=hello%20world to your dashboard's URL.
In the case of device tags, the key and the value must be set separately as a device tag context variable is treated as an object. To set a value of "hello=world" for the variable "deviceTag", you would append
?ctx[deviceTag][key]=hello&ctx[deviceTag][value]=world to the URL. To set a value that uses a wildcard, do not set any value for the wildcard property. A value of "such as "hello=*" would thus be appended to the URL as
These URLs are valid so long as the context variable's name remains the same, and the given values pass its respective validation rules. Therefore, context settings can be bookmarked or linked to from elsewhere on the Internet.
Links Within the Dashboard
- The dashboard's description, which is defined under your dashboard's settings menu.
- Popup templates in GPS history blocks.
- Help blocks within input controls blocks.
- Condition labels in indicator blocks.
- Header and cell templates in device state tables.
The URLs can be manually constructed; or, there is a Handlebars helper to make it easier to build these links.
Note: Context variables defined in the URL are subject to the same validation rules as variables defined through the context menu. Setting a value for a nonexistent context variable – or setting a value that does not pass validation – will cause the dashboard to fail to load.
Using Context Variables
All context variables are scoped under a
ctx object, and that object can be referenced in a number of places within your dashboard's configuration. For example, to display the value for the variable "myString", or to use it in a block's query configuration, wrap a reference to object and key in a Handlebars template like
Any variable whose value is not set by the user will return its default value when referenced.
Context variables of all types can be used in the dashboard's description and in each block's title. Additionally, each variable type can be used a number of different ways throughout a dashboard's configuration ...
Using Device IDs
A Device ID value can, for example, be used to ...
- Display data from a specific device within your dashboard blocks
- Highlight one device against an array of devices in time series graphs
- View data from a single device at a time within a device state table
- Color-coding map pins, gauges and indicator blocks when viewing a specific device
Using Device Tags
Device Tag values can be used to ...
- Display averages of state values across multiple devices in a gauge block
- Render position data for a subset of devices in a GPS history block or a position chart
- Send a command to multiple devices at once in an input controls block
Note that since device tags render as objects, they must be treated differently when using them to render string output (such as in a block's title or in your dashboard's description). Given a value of "hello=world" for the tag "deviceTag", rendering the tag in that format would be done as
Changing attributes in context can allow users to ...
- Change the attribute to compare other values against in a pie chart
- Graph one changing attribute at a time from multiple devices
- Bold or otherwise highlight a column in a device state table
Currently there are no blocks whose returned data depends on a number attribute, but there are many ways in which a block's appearance can be altered using a number variable, such as:
- Minimum and maximum values can be defined on the axes of time series graphs and bar charts, as well as the bounds of a gauge block.
- Ranges on input control blocks can also have minimums, maximums and default values defined by number context variables.
There are a number of possible uses for string attributes:
- Pass a value to the filter in the event list – or other resource lists.
- Change the axis labels in time series graphs or bar charts.
- Set a URL for the site to display in an external website block.
- Send a different device command from the input controls block.
- Define a custom map center in the GPS history or heatmap blocks
Deleting Context Variables
To delete a context variable, simply click the "delete" icon in the top right corner of the variable's configuration panel. Note: Deleting a variable will potentially break any dashboard block that is referencing that variable, and any URLs referencing that variable will fail to load.