Expression Overview and Syntax
Overview
The expression language is used to define dynamic values for component properties and expression tags. Expressions often involve one or more other values that are used to calculate a final value. Expressions don't do anything, other than return a value.
The classic example for an expression is to change a temperature that is stored in Celsius to Fahrenheit in order to display it. Suppose you had a tag,Tank 6/Temp that was in Celsius. If you wanted to display that tag in Fahrenheit on a Label, you would use an Expression Binding on the label's text property using the following expression:
1.8 * {Tank 6/Temp} + 32The expression language is used to define dynamic values for component properties and expression tags. Expressions often involve one or more other values that are used to calculate a final value. Expressions don't do anything, other than return a value.
The classic example for an expression is to change a temperature that is stored in Celsius to Fahrenheit in order to display it. Suppose you had a tag,Tank 6/Temp that was in Celsius. If you wanted to display that tag in Fahrenheit on a Label, you would use an Expression Binding on the label's text property using the following expression:
Every time that the temperature tag changes, the expression will re-calculate the value and push it into the Label's text property. Now lets say that you wanted to append a "°F" to the end of the label so that the user knew the units of the temperature. You could simply use some string concatenation in your expression, like this:
(1.8 * {Tank 6/Temp} + 32) + " °F"The expression language is used to define dynamic values for component properties and expression tags. Expressions often involve one or more other values that are used to calculate a final value. Expressions don't do anything, other than return a value.
The classic example for an expression is to change a temperature that is stored in Celsius to Fahrenheit in order to display it. Suppose you had a tag,Tank 6/Temp that was in Celsius. If you wanted to display that tag in Fahrenheit on a Label, you would use an Expression Binding on the label's text property using the following expression:
Every time that the temperature tag changes, the expression will re-calculate the value and push it into the Label's text property. Now lets say that you wanted to append a "°F" to the end of the label so that the user knew the units of the temperature. You could simply use some string concatenation in your expression, like this:
Lets suppose that you wanted to give the user an option to display the value in Celsius or Fahrenheit, based on checking a checkbox. You could add a Check Box component to th screen called DisplayFahrenheit. Then you could use this expression to dynamically display either unit, based upon the user's selection:
if({Root Container.DisplayFahrenheit.selected}, (1.8 * {Tank 6/Temp} + 32) + " °F", {Tankf/Temp} + " °C")Syntax
As its name suggests, everything in the expression language is an " expression ". This means that everything returns a value . 5 is an expression. So is 5+1 . So are {MyTags/TankLevel} and {MyTags/TankLevel}+1 . Expressions can be combined in many powerful ways. Lets take a look at how expressions are written.
More formally, an expression is any one of the following:
-
Number
-
Boolean
-
String
-
Bound tag
-
Bound property
-
Function call
-
Dataset access
-
Equation involving any of these
Literal Values
Literal values are things like numbers, booleans, and strings that are represented directly in the language. In the expression language, numbers can by typed in directly as integers, floating point values, or using hexadecimal notation with a 0x prefix. Examples:
428.4560xFFC2Strings are represented by surrounding them with double or single quotes. You can use the backslash character to escape quotes that you want to be included in the string. Examples:
"This is a regular string"'This one uses single quotes'"This string uses \"escaping\" to include quotes inside the string"
Operators
You can use these arithmetic, logical, and bit-shifting operators to combine expressions.
|
Operator |
Name |
Description |
|
-- |
Unary Minus |
Negates a number. |
|
! |
Not |
Logical opposite of a boolean. |
|
^ |
Power |
Raises a number to the power of another number. a^b is a b. |
|
% |
Modulus |
Modulus or remainder of two numbers. a%b is the remainder of a÷b. |
|
* |
Multiply |
|
|
/ |
Divide |
|
|
+ |
Add/Concatonate |
If both operands are numbers, this will add them together. Otherwise treats arguments as strings and performs concatenation. |
|
- |
Subtraction |
|
|
& |
Bitwise AND |
|
|
| |
Bitwise OR |
|
|
xor |
Bitwise XOR |
|
|
<< |
Left Shift |
A signed bitwise left shift. |
|
>> |
Right Shift |
A signed bitwise right shift. |
|
> |
Greater Than |
Logical greater-than test between two numbers. Returns a boolean. |
|
< |
Less Than |
|
|
>= |
Greater Than or Equal To |
|
|
<= |
Less Than or Equal To |
|
|
= |
Equal |
Tests for equality between two operands. |
|
!= |
Not Equal |
Tests for equality, returning true when not equal. |
|
&& |
Logical AND |
Returns true when both operands are true. Anything non-zero is considered true. |
|
|| |
Logical OR |
Returns true when either operand is true. Anything non-zero is considered true. |
|
like |
Fuzzy String Matching |
Compares the left-hand value with the pattern on the right side. The pattern may consist of %,*, and ? wildcards. |
|
// |
Comments |
Allows for comments following this operator. |
Bound Values
Bound values are paths to other values enclosed in braces. These will appear red in the expression editor. When you are writing an expression for a
Expression Binding
, you can reference tag values and property values using the brace notation. When you are writing an expression for an
Expression Tag
, you can only reference other tag values. You can use the Insert Property (
) and Insert Tag Value (
) buttons to build these references for you.
Dataset Access
If you have an expression that returns a dataset, you can pull a value out of the datatset using the dataset access notation, which takes one of these forms:
Dataset_Expression ["Column_Name"] //returns the value from the first row at the given column nameDataset_Expression [Column_Index] //returns the value from the given column at the first rowDataset_Expression [Row_Index, "Column_Name"] //returns the value from the given row at the given column nameDataset_Expression [Row_Index, Column_Index] //returns the value from the given row at the given column indexFor example, this expression would pull a value out of a Table at row 6 for column " ProductCode ":
{Root Container.Table.data}[6, "ProductCode"]Note that you'll often have to convince the expression system that what you're doing is safe. The expression language can't tell what the datatype will be for a given column, so you may have to use a type-casting function to convince the expression language to accept your expression, like this:
toInt({Root Container.Table.data}[6, "ProductCode"])
Expression Functions
The expression language's functions are where much of the real power lies. A function may take various arguments, all of which can themselves be any arbitrary expression. This means that you can use the results of one function as the argument to another function. In general, the syntax for a function call is:
functionName(expression1, expression2, ...)Whitespace and Comments
Whitespace, such as spaces, tabs and newlines, are largely ignored in the expression language. It is often helpful to break your expression up onto multiple lines for clarity. Comments are delimited by two forward slashes. This will make the rest of that line be ignored. This example shows an if function spread over 4 lines with comments annotating the arguments.
if( {Root Container.UseTagValueOption.selected}, {MyTags/SomeValue}, // Use the tag value "Not Selected", // Use default value if the user doesn't check the box)