Dashboard Variables

Internally, a dashboard is able to store arbitrary variables. They enable the dashboard to dynamically adjust it's behaviour according to changes in the data - meaning the dashboard can change according to changes in it's variables.

Defining Variables

Variables can be defined in multiple ways. The first way one can define a dashboard variable is by ticking the Vars option in the DashboardCustomize field. This will show a new duplicate group Variables where you can name a var to be initialized and, optionally, it's initial value.

Components that have a OutputVar field (where you specify the name of a variable where you want to output a certain value depending on the component) will inherently create a variable with the given name (if specified). Suppose you have a Filter component, and you specified a var named myvarname in it's OutputVarFilter field. The dashboard will create this variable internally. When a user enters text into this filter, the myvarname variable is internally updated with the text value.

Using Variables in Queries

Variables can be utilized anywhere in a dashboard. For example, variables can be used in queries to filter or modify the displayed data. The syntax for using variables in a query involves referencing with handlebars notation:

{{vars.myvarname}}

Example Let's say you have the following list query to retrieve documents in the context of the dashboard.

"myQueryResult":distinct("Definition Name","*"),

To make this query dynamic and filter the list based on a dashboard variable, you can modify as follows:

"myQueryResult":distinct("Definition Name","*  {{vars.myvarname}}"),

Here, the value of myvarname is appended to the query dynamically, allowing the displayed list to updated based on the filter input.

Scope and Context

Variables - both declared explicitly in the Dashboard Variables field and via a component's OutputVar field - are globally accessible throughout the dashboard. However, you may write templates using Handlebar'seach or with blocks, which introduce a nested scope. Inside these nested contexts, global variables are not directly accessible. To reference global variables from within a nested scope, you can use the @root keyword.

If you want to reference a variable within a nested context, you would write:

{{@root.vars.myvarname}}

This ensures you are accessing the global variable (managed by the dashboard) rather than a potentially undefined local one.

More complex use cases: Dynamically Created Variables

In some cases, you may need to dynamically create variables based on user input or a predefined list of items. This approach is particularly useful when building components like a multi-select menu where each selection dynamically generates a variable that can be referenced elsewhere in the dashboard.

Example: Suppose you have a list in your dashboard context, that represents the filters you want to use.

"myFilters": [
    {
        "label": "Filter Label 1",
        "query": "(field:fieldValue1)",
        "icon": "fa-solid fa-magnifying-glass",
        "varName": "myvar1"
    },
    {
        "label": "Filter Label 2",
        "query": "(field:fieldValue2)",
        "icon": "fa-solid fa-user-md",
        "varName": "myvar2"
    }
]

You can add a property varName to each object in the list to define the name of the variable to be created. For example, when iterating over the myFilters list inside aMenu's Text field using handlebars, you can pass the varName property to the FilterVarName field - or another field which corresponds to the name of the variable depending on the component you're using. This will dynamically create variables such as myvar1 and myvar2 for the corresponding iterated filters. These variables can then be accessed and used like any other variable:

{{vars.myvar1}} {{vars.myvar2}}