Variables are dynamically assigned values (either by a User Input Control, User Property, Company Property, or a MAP, MAPFLAT or SET function), that can be used instead of a specific data selection.
This article includes:
Creating and setting variables
How a variable is being used changes where the variable is created. There are three main types of variables:
- User Input Control variable: Create the variable while building the User Input Control component.
- Company Property: Create the custom Company Property in Account settings (there are two built-in company properties). Watch this video to learn more or go to this article.
- User Property: Create the custom User Property in Account settings (there are four built-in user properties). Watch this video to learn more or go to this article.
Notes:
- All variables, regardless of where they are created, can be accessed in the Klip Editor by any user with editing permissions.
- If you create new user or company properties for a Klip and then add the Klip to a dashboard that was previously shared via a published link, the new properties won’t be recognized and the Klips in the shared dashboard will be blank. In this case, you need to delete the old link to the dashboard and send a new link to people you want to share it with. Learn more here.
Visibility
The value of a variable is set by a (visible) User Input Control on the dashboard. If you choose the Hide always option when building your User Input Control, the value of the variable as set in the Klip Editor will not be shown on the dashboard.
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 multi-component 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, MAPFLAT, and SET functions.
- MAP and MAPFLAT are 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 and MAPFLAT
- SET uses variables, sets them to values, and uses a formula to manipulate the variables. Learn more about SET.
Accessing and using variables
There are three ways to access a variable in the Klip Editor:
- 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.
Using variables to filter data
The Filter action allows you to set conditions with variables. You can choose a variable from the drop-down list or type in a value to set a condition or multiple conditions. Learn more about filtering data here.
For this example, create a User Input Control component and a Table component. We will use the fruit sales data source.
- 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 the Table component.
Note: Modelled data sources have their headers already distinguished and won’t need to have a filter applied. Learn more about modelled data sources here.
- Select a variable from the list or create a new variable by clicking 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.
- Select the column of data in the Table component you want to use. 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, click the Include "All" data option check box in the Properties panel. 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.
Watch the following video to learn more about how to use variables to filter data:
Using variables in a dashboard
Klips that set the same variables will show values as specified by the selection.
For example, 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:
Note: Klips update in your dashboard from variables changes based on the set scope.
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.
Testing variables
You can see what your Klip will look like with a variable by testing a value in the Klip Editor. You can set a value for the variable by clicking the Advanced Tools menu (beside the Klip Editor title) and click Create New Variable or to edit a value of an existing variable, click Manage Variables.
The Variable Name is what you select when working with Klips and acts as a placeholder or storage location.The Klip Editor Value (optional) applies only while working in the Klip editor and is typically used for test purposes.
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.
- Klip
- Dashboard
- All dashboards
- User Property
- Company Property
Note: Dashboard hyperlink parameters have a higher precedence than User Input Controls with an "all dashboards" scope.
Example of variable precedence
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.
- 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.
- Add the required Klips to this dashboard; these Klips will select data based on region.
- 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.
- 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.
- 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.
Watch the following video to learn more: