Below is a list of Atomic functions you can use in JavaScript script expressions, which are small blocks of code that can be triggered from actions in your prototype. If you’re new to JavaScript there are many learning resources online including this excellent introductory guide to JavaScript by Mozilla.

If you'd like an easy way to edit Atomic Script expressions within your favourite code editor, check out Assistant, our free companion for Mac users.

Tip: If the parameter you are passing into a function is text (a string) wrap it in double quotation marks. E.g. goto("Page 2") . Numbers, variables and other data types do not need to be wrapped in quotation marks.

Please see the MathJS cheat sheet if you are using MathJS script expressions.
 

Navigating between pages

goto(pageName);
Sets the current page of the prototype to pageName, with no transition.

goto("Page 2");

 
goto(pageName, delay);

Sets the current page of the prototype to pageName after delay milliseconds.

goto("Page 2", 200);

 
goto(pageName, motion);
Sets the current page of the prototype to pageName using motion with ease-in-out and 300ms duration. See the motion options at the bottom of this page.

goto("Page 2", "slide-right");

 
goto(pageName, motion, easing);
Sets the current page of the prototype to pageName using motion with easing and 300ms duration. See the motion and easing options at the bottom of this page.

goto("Page 2", "slide-right", "ease-out");

 
goto(pageName, motion, easing, duration, delay);
Sets the current page of the prototype to pageName using motion with easing and duration milliseconds after delay milliseconds. See the motion and easing options at the bottom of this page.

goto("Home", "slide-right", "ease-out", 200, 50);

 

Understanding path arrays

Many of the following functions use "path arrays" as a way of defining which element to reference or control via a function. Path arrays take the form of sets of names of pages and component instances, starting with the top-level page name of the prototype. To target nested components, specify further sets of page names and component instance names. For example, given a prototype having a page name “Main” and on that page two component instances: “Cancel Button” and “Submit Button”. The path arrays to target these component instances would be:

state(["Main", "Cancel Button"]);

state(["Main", "Submit Button"]);

Here the path array is the square brackets [] and the contents within them.

If the “Submit Button” had a single page named “Page 1” within it, and on that page was a component named “Icon”, the path array to target the Icon component would be:

state(["Main", "Submit Button", "Page 1", "Icon"]);


Note: Names of pages and component instances are case-sensitive.
  

Getting and setting the state of components

state(pathArray);
Gets the current state of a component instance using the given pathArray.
Returns: string

let selectedTab = state(["Page 1", "tabbarComponent"]);


state(pathArray, pageName);
Sets the state of a component instance at pathArray to the pageName.

state(["Page 1", "tabbarComponent"], "Settings tab");

 
state(pathArray, pageName, delay);
Sets the state of a component instance at pathArray to the pageName after delay milliseconds.

state(["Page 1", "tabbarComponent"], "Settings tab", 200);


state(pathArray, pageName, motion, easing, duration, delay);
Sets the state of a component instance at pathArray to the pageName using motion and easing and duration milliseconds after delay milliseconds. Delay can be set to zero if no delay is needed. See the motion and easing options at the bottom of this page.

state(["Page 1", "panelComponent"], "Expanded", "custom", "ease-out", 250, 0);

 

Getting and setting a container’s scroll position

The following functions work for Container elements with scrolling enabled only.

scrollTo(pathArray, positionX, positionY);
Sets the scroll position of a container element at pathArray to positionX and positionY in pixels. Note: negative values have no effect; the scroll position starts at 0 and increases as content is scrolled.

scrollTo(["Page 1", "Container"], 0, 300);

 
scrollTo(pathArray, positionX, positionY, duration);
Sets the scroll position of a container element at pathArray to positionX and positionY in pixels, set over duration in milliseconds. The animation uses an ease-in-out quadratic tween.

scrollTo(["Page 1", "Container"], 0, 300, 500);

 
resetScroll(pathArray);

Sets the scroll position of a container element at pathArray to 0,0.

resetScroll(["Page 1", "Container"]);

 
scrollPos(pathArray);
Gets the current scroll position of a container element at pathArray . Use this to find out if a scroll container has been scrolled and how far is has been scrolled. Note: if the element is not found, a -1  is returned.
Returns: {x: x-position, y: y-position}

let scrollPosition = scrollPos(["Page 1", "Container"]);

 

Getting and setting text values

The following functions work for Text, Text Input, Dropdown Menu and Text Area elements only.

text(pathArray);
Gets the current text value of an element at pathArray. Note: This function is not compatible with elements linked to a variable.
Returns: string

let firstName = text(["Page 1", "firstNameField"]);

 
text(pathArray, value)
Sets the current text value  of an element at pathArray. Use this to “push” a string value into a text-based element. Note: This function is not compatible with elements linked to a variable.

text(["Page 1", "firstNameField"], "Jane");

 

Controlling the focus of text fields

The following functions work for Text Input and Text Area elements only.

focus(pathArray)

Gives focus to the input element at pathArray. Use this to focus a text input element when a page loads. Note: you may need to re-focus your input element after a page transition; use a page load timer and a script expression action to invoke this function to achieve this.

focus(["Page 1", "userNameField"]);

 
blur(pathArray)
Blurs the input element at pathArray, so that it loses focus.

blur(["Page 1", "userNameField"]); 

 

Linking to a URL

openUrl(url, newWindow)
Opens a url in the current or default browser. If newWindow is true it will open a new browser tab/window. If newWindow is false  it will use the current tab/window.
Returns: true

openUrl("https://www.example.com/", false);

You can also use this function to open a new email in the user's default email client, with an email address defined in the To: field. 

openUrl("mailto:name@example.com", false);

 

Accessing dataset data

data(dataSetName);
Gets the data from dataSetName, which is the name of a dataset you have imported into your project. The returned array contains an entry for each row in the data set; each array entry contains an object having properties named after the data set columns. Arrays begin with an index of 0.
Returns: an array of objects

Example:

// store a dataset in an array
let contactsArray = data("Contacts list spreadsheet");

// access a row within the array
let firstContact = contactsArray[0];

// access a cell within a row
let contactName = firstContact.name;

Find out more about using data in your prototypes
 

Accessing event information

An event context variable is available in script expressions for the following events: blur, focus, and keypress; which are available on text-based input elements. The variable is automatically available as event. This represents the event context, or in other words, a set of values specific to the element and event which triggered the script expression.

event.value

This is the current value of the text-based input element. Available on blur, focus, and keypress.

event.key

This is the string key code of the key that was pressed in a keypress event.

Tip: Use console.log(event)  in your script expression, then open the JavaScript console to see the output when triggering events.
 

Getting the path to the current element using 'SELF'

A global self-referencing path array variable is available in all script expressions for all elements that trigger events. The variable is called SELF and is an array of strings. The array is dynamically calculated based on where the element is positioned in the hierarchy of prototypes and components. It always reflects the current “absolute” path to the element which is triggered the executing script expression. This variable can be used to target relative elements within a page or component when using functions such as state() , blur() , focus()  and text() . It can also be used, for example, to discover the nesting path for a given component. Please read the section above on "Understanding path arrays” for more information.

Examples:

var pathToComponent = SELF;

var currentComponentName = SELF.pop();

 

Logging information to the JavaScript console

console.log(message)
Prints a message to the JavaScript console in your browser, useful for tracking the value of variables over time and debugging complex scripts.

Examples:

console.log("Hello world");

console.log(var1, var2, var3);

Tip: Even if you don't log messages you can still use the JavaScript console to spot errors in your code, as any error encountered while previewing your prototype will be logged there.

 

Animation values

motion

  • "custom"
  • "slide-left"
  • "slide-right"
  • "slide-down"
  • "slide-up"
  • "push-left"
  • "push-right"
  • "float-left"
  • "float-right"
  • "fade"
  • "flip"

easing

  • "linear"
  • "ease-in"
  • "ease-out"
  • "ease-in-out"
  • "back"
  • "bounce"

duration

specified in milliseconds; a value of 0 prevents animation

delay

specified in milliseconds; default is 0

 

Related articles:

Did this answer your question?