Variables

What's in this article?

Overview

Variables can be used anywhere specific data selections are used. Because a variable is dynamically assigned a value (either by a User Input Control, User Property, Company Property, or a MAP or SET function), it can be used instead of a specific data selection. Read this article on User Input Controls to learn more.

Creating and setting variables

The use of a variable determines where the variable is created. There are three main types of variables:

Note: All variables, regardless of where they are created, can be accessed in the Klip Editor by any user with editing permissions.

Scope

Scope refers to the extent of a variable's effect:

  • Company Property: setting applies to all dashboards viewed by all users in the account (parent or client).
  • User Property: setting applies to all dashboards viewed by a user.
  • User Input Control variable: 
    • Only this Klip: setting applies to all Klips in the same multicomponent Klip as the User Input Control.
    • Only this dashboard: setting applies to all Klips on the same dashboard as the User Input Control.
    • All dashboards: setting applies to all Klips on all dashboards.

It can be useful to set the same variable at multiple levels to control the data visible to different users/clients. See Variable Precedence for details.

Variables set by functions

Variables can also be set by the MAP and SET functions.

  • MAP is used to repeat a formula over a set of values and uses variables to specify the values and use the formula. Learn more about MAP.
  •  SET uses variables, sets them to values, and uses a formula to manipulate the variables. Learn more about SET.

Using Variables

There are three ways to access a variable:

  • Select a variable from the Properties Panel.

 

  • Type in $ and select a variable from the drop-down list.

Hover over the image below to watch a short video.

 

  • Click Insert>Variables and select a variable from the drop-down list.

How variables work in a dashboard

Klips that set the same variables will show values as specified by the selection. If you have a User Input Control that sets the fruits variable, and you select Oranges, all Klips that set the fruits variable will update to reflect values based on Oranges. 

If you apply a static selection (just the variable name), then selecting a value from the drop-down list will produce the following results:

Using variables to filter data

The Filter action allows you to set conditions with variables. You can choose a variable from the dropdown list or type in a value to set a condition or multiple conditions. If you set multiple conditions, you have the option to Match All conditions or Match Any one of them. The Match Case checkbox allows you to match a value according to it's letter case. 

For this example, create a User Input Control component and a Table component. We will use the fruit sales data source. 

 

  1. Use the Filter action to set a condition that filters out the column header from both the Values subcomponent of the User Input Control and the column of data you want to display in a Table component.

  1. Select a variable from the list or create a new variable. This variable will be used to change the data displayed on the Table component according to what is selected in the User Input Control. 

  1. Select the Table component. Use the Filter action to set another condition that matches the variable you selected in the User Input Control component. 

The fruit selected in the User Input Control will display the corresponding data in the table. 

Adding the All Data option

You can add an All data option to a User Input Control that will display all the data when selected. To do this check the box next to Include "All" data option. You can rename how the All option is displayed in the drop-down list using the textbox shown below.

Note: Just like $ references a variable in a formula, "_all_" references the All option in a formula. See SELECT to see how to use conditions with All in a formula. 

Variable Precedence

The same variable name can be set by all three variable types. For example, you can have a variable named Region set by all of the following:

  • One or more User Input Control components
  • User Property
  • Company Property

When the same variable is set at multiple levels, formulas follow a standard order of precedence to determine which setting to refer to in their calculations. The order is from narrowest to broadest scope.

    1. Klip
    2. Dashboard
    3. All dashboards
    4. User Property
    5. Company Property

Note: Dashboard hyperlink parameters have a higher precedence than User Input Controls with an "all dashboards" scope.

Example

An organization may want to control the data visible to different users. For example, on a Regional Sales dashboard, the manager can see the data for all regions within the organization while the employees see only the data for their region. This approach requires two versions of the same dashboard, one for the manager and another for the employees.

  1. Create the manager dashboard and add a drop-down User Input Control that sets a variable named Region. This drop-down lists all the regions.
  2. Add the required Klips to this dashboard; these Klips will select data based on region.
  3. Go to Users and create a custom User Property named Region:
  • For the manager, do not assign a value to this custom User Property.
  • For each employee, assign this custom User Property the value corresponding to their region.
  1. Create the employees dashboard and add the same Klips from the manager dashboard except for the User Input Control that sets the Region variable. Share this dashboard and its Klips with the Employees user group. When an employee signs in, the dashboard will display data according to the Region custom User Property.

Testing with variables

You can also set a value for the variable by clicking the Advanced Tools menu (beside the Klip Editor title). The Klip Editor Value (optional) applies only while working in the Klip editor and is typically used for test purposes. The Variable Name is what you select when working with Klips and acts as a placeholder or storage location.

Using variables in Klip or dashboard titles

You can use variables in the Klip and dashboard titles so that when you select a value, the title will also change. To use variables in a title, use curly brackets around the variable name. For example, to use the fruits variable in a title, type {fruits} in the title field.

The example below shows the title of the User Input Control component changing according to the selected fruit. 

Related links: