Context Variables

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.

Context Version A

Context Version B

Defining Context Variables

Before a context variable can be referenced in a block, it must be defined in your dashboard settings.

  • If you do not have any variables defined, you’ll see a “Create Variables” link in the dashboard toolbar, which will take you directly to the “Context” tab of your dashboard settings.
  • If you have already have one or more variables defined, open the “Settings” (three dots) dropdown menu, click “Edit Dashboard Settings” and navigate to the “Context” tab.

Create Variables

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.

Note: The order of your variables on this page will decide the order in which they appear in the dashboard toolbar. You can drag and drop variables to change this order.

Add Context Variable

To add a new variable, click the “Add Variable” button and select your variable type from the dropdown menu. There are six variable types …

Device IDs

A “Device ID” is a device query that takes a single device at a time. Device IDs take four additional parameters:

Device ID Context

  • 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 a single device ID, or by clicking “Select multiple devices or tags” multiple 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.
  • Include full device info in context is unchecked by default. When checked, the name and tags of the device matching the ID set in the context variable will be available when using this variable within your dashboard, and whether the variable is checked affects how it is used.

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.

Device Tags

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 building queries with device tags, the key or value of a device tag context variable can resolve to a wildcard (’*’) or a static value.

Device Tag Context

Device Tags take three additional parameters:

  • Application ID is the Losant application to which any selected device tag must belong.
  • Default Key and 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 can contain wildcard values by leaving one of the key or value fields blank. 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”.

Device Attributes

An “Attribute” is a single device attribute. Attributes take three additional parameters:

Attribute Context

  • 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 (Number, 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.)

Experience Users

An “Experience User” resolves to one of your application’s Experience Users. This variable should only be used in dashboards that have been built specifically to display within an Experience Page.

Experience User Context

Experience Users take three additional parameters:

  • Application ID is the Losant application to which the Experience User must belong.
  • Default Value is the Experience User to use when no value is provided.
  • Validation is optional; it is one or more Experience Groups to which any Experience User set as the value of the context variable must belong. If the user is a member of one of the chosen groups’ ancestors, the context value is considered valid.

Strings

“String” variables are simply an arbitrary string of characters. Strings take two additional parameters:

String Context

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

Numbers

A “Number” variable is simply a number: positive or negative, whole or decimal. Number variables take three additional parameters:

Number Context

  • 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 is exempt from these 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.

Setting Context Variables

Once your context variables have been defined, there are many different ways in which the values of those can be set in your dashboard:

Dashboard Toolbar

The easiest way to change a context variable’s current value is via the dashboard toolbar. Every variable you have defined will appear in the toolbar, so long as there is space. Hovering over a variable will tell you its name, and clicking it will open a dropdown where you can change its current value.

Set Context Toolbar

Device ID, Device Attribute, and Experience User variables will take the form of dropdown menus with all valid entries available for selection. Device Tag, String, and Number variables are simple text inputs.

The input will default to the value currently being used by the dashboard, and if validation rules are applied you will be able to see them in the form. You may change the value and click “Set Value” to apply the changes, or you may click “Reset to default” to revert the variable to its default value. Either option will then update the dashboard to reflect the new context.

View All Context Modal

If your variables don’t all fit in the dashboard toolbar, a “View All Context” button will appear. Clicking this will present a modal where you can set current values for each variable. All inputs will validate against any rules you have defined.

Set Context Modal

The inputs will default to the values currently being used by the dashboard. Change any values you would like and click the “Update” button at the bottom of the form, and your dashboard will update to reflect the new context.

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 ?ctx[deviceTag][key]=hello.

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.

There are a number of places within dashboards where, using Markdown and Handlebars templates, you may create a custom link tag:

The URLs can be manually constructed; or, there is a Handlebars helper to make it easier to build these links.

Linking to Dashboard Context

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.

Experience Page Parameters

When building Dashboard Pages for your application experience, the values of context variables can be set to specific values or they can reference context from the request that is returning the page.

Context in Experience Dashboard Page

In the most common case, the value of an Experience User variable will be set to the ID of the user who made the request. The easiest way to do this is with the value {{experience.user.id}}.

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 {{ctx.myString}}.

Context in a Dashboard Description

Context variables can also be referenced in block helpers and format helpers like any other variable (e.g. {{upper ctx.myString}}).

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

Device ID Context Use

A Device ID value can, for example, be used to …

Note that if the ”Include full device info in context” checkbox is checked for a device ID variable, rendering the value of the context variable requires referencing the properties of the object returned in the context.

  • {{ctx.VARIABLE_NAME.id}} renders the device ID (though {{ctx.VARIABLE_NAME}} without a sub-property will also render the ID).
  • {{ctx.VARIABLE_NAME.name}} renders the device name.
  • {{ctx.VARIABLE_NAME.tags}} is a reference to the tags associated with the device; you may wish to iterate over all tags or get the value of a specific tag with a string template such as {{ctx.VARIABLE_NAME.tags.TAG_KEY.[INDEX]}}, where INDEX is usually 0 since tag values are returned as an array.

If you are not returning full device info, you may only render the currently selected device’s ID with {{ctx.VARIABLE_NAME}}.

Using Device Tags

Device Tag Context Use

Device Tag values can be used to …

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 {{ctx.deviceTag.key}}={{ctx.deviceTag.value}}.

Using Attributes

Attribute Context Use

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.

Using Experience Users

Experience User Use

Experience User values can be used to …

  • Display a Device List scoped to devices associated with the user via their membership in certain Experience Groups.
  • Display aggregate graphs, gauges and maps based on state data across all devices associated with a user, much like how device tags are used.
  • Add a personalized message within the dashboard’s description based on which user is viewing the dashboard.

Using Numbers

Number Context Use

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:

Using Strings

String Context Use

There are a number of possible uses for string attributes:

Deleting Context Variables

Delete Context Variable

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.

Other Variables

In addition to the context variables explicitly defined on a dashboard, there are several properties exposed in the dashboard render context that can be referenced to build queries, display values, or output conditional content:

  • {{dashboard.id}}: The unique ID of this dashboard.
  • {{dashboard.name}}: The dashboard’s name.
  • {{dashboard.duration}}: The global duration currently applied to the dashboard (in milliseconds). This is the dashboard’s default value if no explicit duration is set.
  • {{dashboard.resolution}}: The global resolution currently applied to the dashboard (in milliseconds). This is the dashboard’s default value if no explicit resolution is set.
  • {{dashboard.refreshRate}}: The rate (in seconds) at which the dashboard re-fetches data for each block.
  • {{dashboard.time}}: The Unix timestamp (in milliseconds) that data was last fetched for the dashboard - or, if viewing a past dashboard state, the timestamp of the selected past state.
  • {{dashboard.themeName}}: The name of the current presentation theme. Value is “light” or “dark”.
  • {{dashboard.isFullScreen}}: A boolean indicating whether the dashboard is currently being viewed in the browser’s fullscreen mode. Value is true or false.
  • {{dashboard.viewContext}}: The method by which the dashboard is currently being consumed by the end user. Possible values are:

    • “embeddedBlock”: If this a single block embedded in an another website.
    • “embeddedDashboard”: If this is an entire dashboard embedded in another website.
    • “experience”: If the dashboard is being displayed through an Experience Page.
    • “platform”: If the dashboard is being viewed in the Losant platform interface.
    • “report”: If the dashboard is being displayed as a PDF generated by a report.

Was this page helpful?


Still looking for help? You can also search the Losant Forums or submit your question there.