Expression Element

The expression element is used to execute complex evaluations and comparisons of inputs and outputs using Javascript, executed within a Node.js virtual machine environment. The expression solely evaluates the input data it’s given, enabling you to evaluate specific data within a Studio project.

The expression element uses the internal variable values for input data. Values is an object that can be referenced within the expression, and the element’s abilities are used to modify what values may be: either a single value or a mapping of multiple key-value pairs. When the expression element triggers, it runs its code editor’s JavaScript and executes on values. The output of the expression always returns the evaluated value, which by default is the variable value.

The expression element is located in the Element Toolbox within Studio’s Application tab and Cloud tab.

The sandbox execution context is a Node.js virtual machine, use of statements such as require and import are not allowed.

Properties

The following properties can be changed for the expression element:

Name

The name of the element.

Expression

Expression to evaluate. The code written in the expression editor can be any valid JavaScript. Your code must be wrapped inside of an IIFE and must not end in a semicolon. For example, here is a valid expression to multiply a value by 2:

(function () {
    return values.testValue * 2;
})()

Triggers

The following triggers are available to execute events from within the expression element:

Triggered

Execute an event when the source element connected to the expression triggers.

Expression True

Execute an event when the evaluated expression is true.

Expression False

Execute an event when the evaluated expression is false.

Evaluated

Execute an event when the expression is evaluated and a value is returned.

Abilities

The following abilities are available for the expression element when its source element triggers:

Trigger

Trigger the element(s) that follow the expression element.

Evaluate

Evaluate the code written in the expression for the values variable, and return it as value. The expression evaluates the input data for the values variable if nothing is specified in the Values argument. If value(s) are entered in the argument, they are added to the values variable first, and then the expression is evaluated.

Evaluate Argument      
Name Type Description Example
Values Object Key-value pairs added to values prior to evaluation. {a:11, b:22}

Set Value

Set the values variable to a single key-value pair object. When set, any existing objects in the expression are removed and replaced with what is specified in the ability’s argument fields. This object can be referenced within the code of the expression.

Set Value Arguments      
Name Type Description Example
Key String The unique identifier for the data. "A"
Value Object The data being identified. 1

Set Values

Set the values variable to an object mapping of multiple key-value pairs. When set, any existing key-value pairs in the expression are removed and replaced with what is specified in the Values argument. This object can be referenced within the code of the expression.

Set Values Argument      
Name Type Description Example
Values Object Set the values variable to an object containing any number of key-value pairs. {a:11, b:22, c:33}

For example, to set `values` to multiple key-value pairs: an `a` key with a value of `11`, `b` key with a value of `22`, and a `c` key with a value of `33`, enter the mapping within braces: `{a:11, b:22, c:33}` Note when listed in this format, the key does not require quotation marks.

Assign Values

Assign the value(s) specified in the argument to an existing object; essentially updates the value of the object if the key-value pair exists. If a value is assigned for a key that doesn’t exist, it instead adds that key-value pair to the mapping within the object.

Assign Values Argument      
Name Type Description Example
Values Object Key-value pairs being added to an object. {a:55, d:44}

For example, if the object consists of `{a:11, b:22, c:33}`, and then you assign the values `{a:55, d:44}` and evaluate the expression, it results in the object containing `{a:55, b:22, c:32, d:44}`. The existing `a` value is updated with the assigned value, and the new `d` key is added to the object.

Demo Projects

To view the Expression element used within a project, click the demo’s name to open the project in Atmosphere and see how the element is set up.

Name Hardware Description
Celsius to Fahrenheit Conversion Demo PIC-IoT WG The Expression Element is used in this demo to convert temperature data from Celsius to Fahrenheit.