Play’s Expression Editor is an input method that allows you to create more advanced, custom interactions. It can be accessed by clicking the + sign button on any property of any interaction node.

When you press the + icon, the Expression Editor will appear as a new window. In the top left, you’ll see the name of the interaction node (i.e. Set State, Animate, Timer, etc.) and the property name (i.e. Value, Start, etc.).

In the top right, you’ll see the mode where you can select if the expression should output as a number, string, or boolean. The mode will update based on the property that opened it. For example, if the property was a Set Opacity action’s value, the mode would default to a number. If it was instead a Set Text action’s value, the mode would default to a string.

The majority of the Expression Editor will resemble a code editor. This is where you’ll write your expression.

Keeping an Expression Editor Open

Usually, an Expression Editor window will be dismissed when you press Enter or click on another node/object. You can keep an Expression Editor open AND pin it to a specific location by dragging it into the desired position. Any number of Expression Editors can be open at once. You can close a pinned Expression Editor by clicking the pin/close button in its top left corner.

Expression Output

When you write something in the Expression Editor, you’ll receive an output. Depending on the value, that output can be a number, string, or bool.

Number Output

A number is a numerical value. If you wrote...

1 + 1

The Expression Editor’s output would be a number with the value 2.

String Output

A string is a sequence of characters, like a word or a phrase. If you wrote...

“I love Play" 

or

"I" + " love" + " Play"

The Expression Editor’s output would be a string with the value "I love Play".

Boolean Output

A boolean is a data type that has a value of either true or false.

If you wrote...

"Hello" == "Hello"

The Expression Editor’s output would be a bool with the value True because these strings are the same.

If you instead wrote...

"Hello" == "Goodbye"

The Expression Editor’s output would be a bool with a value False because these strings are not equivalent.

If we used numbers instead of strings, we would see 0 or 1 instead of false or true, respectively.

For example, if you wrote…

1 == 1

The Expression Editor’s output would be a bool with the value 1 because it’s true that one equals one.

Expression Syntax

Here are the properties and functions you can use in the Expression Editor, along with how to use them:

Object Properties

To use the current value of an object’s property, use this structure:

objectName.property

For example, let's say you're building an onboarding flow with a progress bar. You want to fill the progress bar stack when the user taps a button, so you need to know the width of the progress bar stack. You would use...

ProgressContainer.width

You can find a list of all object properties at the bottom of this article.

Device Properties

You can also use properties from the user's device to make your app responsive.

For example, let's say you're creating a scrolling progress bar. To set the progress bar's width, you'll need the device's width, which varies across iPhone models. That value comes from this expression:

device.screenWidth

Multiply that value by the page's scroll percent...

self.percentScrolledY

You'll see the expression outputs a number which will be the progress bar's width, changing throughout the scroll.

You can find a list of all device properties at the bottom of this article.

Selection Helpers

In the scrolling progress bar example above, we used "self" in the expression to find a property value. Self is a selection helper that refers to the object on which the interaction is placed.

Parent and Trigger are other selection helpers. Parent refers to the parent of the object the interaction is on. Trigger refers to the interaction's trigger.

Selection helpers work the same way object and device properties do with the same syntax. For example:

self.scaleX 

parent.childCount

Tap.locationX

Some triggers have specific properties. You can find a list at the bottom of this article.

Variables

You can use any variable that is within the scope of the interaction (i.e. component variables can only be used in interactions on the component and its instances). You can either:

Type the variable’s name directly into the editor
Type the page or component name plus “.” and select the applicable variable
Type “#” and select from a full list of variables

The Expression Editor will show...

#variablename

Connectors

Operators

Connect values from device properties, object properties, and variables with operators. Operators can be basic math functions like +, -, *, /, and % (remainder) that make an expression's value a number or string. They can also be logic operators that make the expression’s value a boolean. You'll use logic operators in conditions. These include:

&&  and

||  or

==  equals

!=  does not equal

>   greater than

>=  greater than or equal to

<   less than

<=  less than or equal to

Functions

Play also offers other math functions that you can use in expressions.

.abs(): The value’s distance from 0 (always a positive number)

.min(): The smaller of 2 values

.max(): The larger of 2 values

.random(): A random number between 2 values

.randomInt(): A random integer between 2 values

.round(): Rounds a value to the nearest whole number

.roundUp(): Rounds a value up to the nearest whole number

.roundDown(): Rounds a value down to the nearest whole number

.stringCount(): Number of characters in a given string

.substring(): The selected range of characters in a given string

.childAtIndex(): Targets the object at a given index

Expression Editor Glossary

Object Properties

.borderBottomLeftRadius

.borderBottomRightRadius

.borderTopLeftRadius

.borderTopRightRadius

.childCount: Number of children in the selected object

.gaugeStartValue

.height

.index: Current order of the selected object

.insetBottom

.insetLeft

.insetRight

.insetTop

.isHidden

.isScrollEnabled

.isZoomEnabled

.layerBlur

.left: Position of the object’s left edge in relation to its parent’s alignment

.marginBottom

.marginLeft

.marginRight

.marginTop

.maxX: Value of the object’s right edge within its parent

.maxY: Value of the object’s bottom edge within its parent

.maxZoomScale

.midX: Value of the object’s horizontal mid-point within its parent

.midY: Value of the object’s vertical mid-point within its parent

.minX: Value of the object’s left edge within its parent

.minY: Value of the object’s top edge within its parent

.minZoomScale

.opacity

.originX: The initial horizontal position when Play Mode begins

.originY: The initial vertical position when Play Mode begins

.paddingBottom

.paddingLeft

.paddingRight

.paddingTop

.parent: The parent of the object

.parentX: The horizontal position of this object’s parent

.parentY: The vertical position of this object’s parent

.percentScrollX: A value between 0 - 1 based on the object’s horizontal scroll

.percentScrollY: A value between 0 - 1 based on the object’s vertical scroll

.position

.progressiveBlur

.rotationX

.rotationY

.scale

.scaleX

.scaleY

.screenX

.screenY

.scrollIndexX

.scrollIndexY

.scrollX: Object’s horizontal scroll in PTs

.scrollY: Object’s vertical scroll in PTs

.stackAxis

.stackGap

.state

.top: Position of the object’s left edge in relation to its parent’s alignment

.translateX

.translateY

.translateZ

.userInterfaceStyle

.width

.zIndex

.zoomScale

.triggerProperty

Device Properties

.isPad

.safeAreaTop

.safeAreaBottom

.isPhone

.deviceWidth

.deviceHeight

Trigger Properties

Tap

.numberOfTaps: Number of taps set on the trigger

.numberOfTouches: Number of fingers used to tap

Touch

.numberOfTouches: Number of fingers used to tap

.locationX: The horizontal location of your finger in relation to the object this trigger is on

.locationY: The vertical location of your finger in relation to the object this trigger is on

Long Press

.minimumPressDuration: Duration set on the Long Press trigger

.numberOfTouches: Number of fingers used to press

Scroll

.offsetX: Amount scrolled horizontally in PTs

.offsetY: Amount scrolled vertically in PTs

.velocityX: Horizontal velocity of your finger while scrolling

.velocityY: Vertical velocity of your finger while scrolling

Pan

.deltaX: Distance your finger moves horizontally from A to B

.deltaY: Distance your finger moves vertically from A to B

.locationX: The horizontal location of your finger in relation to the object this trigger is on

.locationY: The vertical location of your finger in relation to the object this trigger is on

.translationX: The horizontal distance of the pan: Left (-) & Right (+)

.translationY: The vertical distance of the pan: Up (-) & Down (+)

.velocityX: Horizontal velocity of your finger while panning

.velocityY: Vertical velocity of your finger while panning

Loop

.count: Total number of children in the loop

.children: Target each child in the loop

.index: The index number of each child in the loop

.(target): The target of the Loop Children Action