Script expressions are short blocks of code you can write in your prototype. They can be used in actions on pages, hotspots and other elements.

Script expressions let you retrieve and manipulate variables, perform math and logic tests, and use the results to update variables or trigger state changes and transitions directly in the prototype. You can use arithmetic, algebra, trigonometry, geometry and logical functions, as well as array and object data types.

Script expressions are written within actions and are most commonly used in conjunction with variables. To read more about how script expressions can be used within actions to interact with variables check out our article on using variables in your projects.

Syntax for writing script expressions

Script expressions can be written in either of two languages: JavaScript, or MathJS. If you are new to Atomic we highly recommend you use JavaScript. Support for MathJS is deprecated and planned to be phased out later in 2018. All the examples on this page use JavaScript.

MathJS is similar to JavaScript, but better suited to mathematical calculations only. You can learn more about MathJS here. Note: if you are using MathJS you do not need to use the math.  prefix when referencing MathJS functions in script expressions. The MathJS cheat sheet lists Atomic functions available in MathJS and their syntax.

Here’s an example. Let’s say in our prototype we have two form inputs, one collects a user’s income and the second collects expenses. Both inputs are linked to variables, so text entered will be updated in those variables automatically. Now, let’s say we have a page action listening to the expenses variable, and when expenses changes we want the action to calculate the result of income minus expenses and put that result into a third variable named net.

The syntax for this is:

net = income - expenses;

The above expression reads: assign the variable named net a value of income minus expenses. Just like normal JavaScript, the values of income and expenses are treated as numbers in order to perform the numerical operation. Here’s the actions made:

Some tips on script expression syntax

Accessing project and library variables

Project variables are defined uses the “Manage Project Variables” tool in the editor toolbar. They can also be defined through scripts. Project variables are available to all documents in your project, including components. Reading and writing to project variables is done via the $p.  prefix. For example:

$p.fullName = $p.firstName + " " + $p.lastName;

Reading and writing to library variables (e.g. variables used by library components) is done via the $l.  prefix. For example:

$l.taxRate = 0.15;

Assign values to variables using =

Use the =  symbol to assign a value to a variable. For example, the following expression reads as: change var1 to have the same value as var2.

let var1 = var2;

Use == to test equal-to

Use the ==  syntax to test if value on either side are equal. For example the following expression reads as: is it true that var1 is equal to var2?

if(var1 == var2) {
  // Do something
}

Cast variable values to the right format

When using variable values in script expressions you may need to cast them into the correct format.

If you are doing multiplication, division, addition or subtraction those values will be auto-cast as numbers, however, when you are comparing strings using < and > they need to be cast. For example to compare two variables both must be cast as numbers: 

var3 = Number(var1) > Number(var2);

You can ensure numbers are cast as strings for use in building phrases of text. For example:

pageName = "Page " + String(pageNumber);

Set a variable value using a conditional logic test 

You can set the value of a variable using a conditional logic test like this:

let var2;

if(var1 > 0) {
  var2 = "Yay!";
} else {
  var2 = "On rats";
}

Or in condensed form on one line like this:

let var2 = (var1 > 0) ? "Yay!" : "Oh rats";

Both of these reads as: if var1 is greater than 0 then set var2 to “Yay!” Otherwise set var2 to “Oh rats”.

Add comments to your expressions to communicate your intent

It's always a good practice to add comments to your script expressions so when you (or someone else!) returns to them later, they'll be easy to understand and debug. Any line that begins with an // will be treated as a comment and won't interfere with your expression. For example:

// This sets the default value
const var1 = 5;

Comments are also a great way to debug your code. If you want to remove one line from your expression to see if it's causing problems, just add an // to the start of the line.

Multiple lines of comments can be added by starting them with /*  and ending with */  . For example:

/*
  Here's an example of a long comment
  that goes onto two or more lines
*/

Bringing new variables into scope using assignment

If you want to create a new variable within a script expression you can do that by assigning a value to a suitably formatted name. For example, var newVar = “New Zealand”  will create a new variable that is available for that review session, if it doesn’t already exist. If a variable named newVar already exists, then the value will simply be assigned to it.

Accessing the previous value of a variable

Every time a variable change event occurs the previous value of that variable can be accessed using the event.prevState  object. For example, to access the previous value of a variable named income you’d write event.prevState.income . Note: Accessing the event  object and prevState  property is only accessible via script expressions in the initial condition (or “When” field) of a variable change event.

 

Related articles:

Did this answer your question?