Advice and answers from the Atomic Team

Variables let you define values that can dynamically change over time within your prototype. They can be set via actions, displayed in text or text input elements and used to control the state of components.

Variables are useful for creating wide variety of behaviour, including:

  • Dynamically updating text elements
  • Capturing text entered into input fields to display later
  • Simple form field validation
  • Storing user preferences/options so they can be reused throughout a prototype
  • Simplifying communication and control between components
  • Tailoring prototype content and behaviour to different scenarios for use in user testing
  • Creating calculators

How to create a variable

When you create a new variable by default it will be a simple variable. For example, using a simple variable you could store text content such as person’s name or email address, or numerical content like their age, phone number or weekly income.

There are three ways to create a variable. Either from the tools panel, a text element or a component:

  • From the tools panel: Click the Manage Project Variables button (or via the keyboard shortcut: V). 
  • From a text or text input element: Open the Content dropdown. In the Use Variables section, click Add
  • From a component: Select a component and open the State dropdown in the properties panel. Under the Set From Variable section click Add.

With the Project Variables Library now open, click Add Variable. You’ll see two columns; a Name and Default Value column.

  • Name refers to the name of your variable. Choose something descriptive but short. 
  • Default Value refers to the default value you’d like shown. This field is optional to complete. It defines the value that will be used when the prototype is first previewed.

A note about variable names

Variable need to be alphanumeric, are case sensitive and need to start with a letter. Avoid using certain scripting terms as variable names, such as: mod, to, in, and, xor, or, not, end.

How to use variables in your prototype

Variables in Atomic are scoped to your Project. That means all prototypes and components in the same project can listen to and control the variables defined within that Project. 

For example, a component embedded into your prototype has the same access to variables as the main prototype. Because of this, variables are a great way to share values between prototypes and components.

Displaying variable values in text and input elements

The value of a variable can be displayed in a text or text input element. This can be useful for dynamically setting form fields or other types of text in your prototype.

To display a variable in a text element:

  1. Select the text or text input element you’d like to display a variable value in.
  2. Open the Content dropdown and select the variable you’d like to use. If you have provided a default value it will immediately display in the element selected. If you’re using a text input element, when users type within the input the value of variable will be updated as they type.
  3. You can change the value of the variable using actions which will update what is shown in your text or text input element.

Using variables to control the state of components

Variables can be used to set the state of a component. By binding the component state to a variable, whenever the variable value changes so will the component state. For example, you can set up a navigation component to update a variable with the currently selected navigation option, and have one or more other components bound to that variable, so that their state (and the content they display) is automatically updated whenever a different navigation option is selected.

To control the state of a component using a variable:

  1. Select the component you’d like to control. Your component must have multiple states (pages within it).
  2. Open the State dropdown and from within the Set From Variable section, select the variable you’d like to use. If you don’t have a variable to use, you can create one now using the Add button in the dropdown.
  3. Now when previewing your prototype, when the value of your variable changes to one that matches the name of one of your states (a page within your component), the component will display that state. You can change the value of a variable by either setting a default value or by using actions.

Note: If no default value is set for your variable, or the value does not match one of the states, the first state in your component will be displayed.

Using actions to change variable values

The real power of variables is the ability to change their values over time in your prototype. You can do this with actions. For example, if you had a variable called “first name” you could change it from “Jane” to “Sarah” and use that value throughout your prototype.

There are many ways to define when a variable action should be triggered. You can trigger an action when a numeric variable is over or under a certain number, when it is set or unset, or create complex conditions using script expressions.

To change the value of a variable using actions:

  1. Create an action. This could be a page action or interaction on a component.
  2. In the Action dropdown, you’ll see an option called Set Variable. From this section, choose the variable you would like to change.
  3. Enter a new value for your variable. Now when this action is performed the value will update with it.

To perform a basic operation on the value of a variable using actions:

  1. Create an action. This could be a page action or interaction on a component.
  2. In the Action dropdown, you’ll see an option called Set Variable. From this section, choose the variable you would like to change.
  3. Choose the basic operation you’d like to perform. Now when this action is performed the value will be modified using the operation you’ve configured. 
  4. Note: If you choose Script Expression you can write a single line expression that results in a value which will update the variable.

To perform a complex operation on the value of a variable using actions

  1. Create an action. This could be a page action or interaction on a component.
  2. In the Action dropdown, you’ll see an option called Script Expression
  3. Write a script expression where the last line results in a value. 
  4. When this action is performed the expression will be evaluated.
  5. Note: Using a Script Expression in this way means you can perform complex math and logic operations, reference and even update many variables in a single action.

Using actions to listen for when a variable changes

You can use actions to listen to when a variable changes and then trigger another action, like going to a new page or changing the state of a component. For example, you could listen for when a “notification setting” variable changes from “off” to “on”, and then respond by going to a different page in your prototype.

To listen for when a variable changes:

  1. Create a page action or interaction on a component and select When a variable changes.
  2. Choose to listen to when a variable changes (to anything), when it is set to a specific value or when it meets a basic numeric criteria. 
  3. Now choose the action you would like to perform when the variable changes. This could be going to another page or even changing the value on another variable.

Using a script expression to create a logic test within an action

You can use a script expression to create a logic test within an action. If the test evaluates to ‘true’ then the action will proceed, if it evaluates to ‘false’ the action won’t proceed.   

To use a script expression as a test that gets evaluated when a variable changes:

  1. Create a page action or interaction on a component and select When a variable changes.
  2. Choose Script Expression
  3. Write a script expression where the last line can be evaluated ‘true’ or ‘false’. 
  4. Now choose the action you would like to perform when the variable changes and the script expression has returned true. This could be going to another page or even changing the value on another variable.

Check out this article on Script Expressions to learn more about how they work.

Advanced variables

Advanced variables are used when you want to work with more complex data types like arrays and objects – or to create functions that can be referenced in Script Expressions

An advanced variable can be created by clicking the </> button on the right of the variable value field. 

When a variable is converted to Advanced, the icon changes to blue. Now the formatting of text in the default value field looks different and you’ll receive feedback about the syntax and validity of the value as you’re editing. 

Did this answer your question?