Keychain Expressions

Key Calculations

Watch the video

It's possible to perform calculations on data keys. This section documents the various operators and functions that are available.

Keychain Expressions

Keychains have their own expression language, which is called a Keychain Expression to separate it from other languages in Ignition.

Keychain Expressions are configured by simply utilizing any operators or functions within the "@" characters. Assuming we have a key named "myKey" with a value of 10, we can multiple its value by 10 with the following expression:

//Expression
@myKey * 10@

//Output
100

Again, note that the "*" operator and multiplier are enclosed in the "@" characters. Of course, we can also use a different key as the multiplier. Assuming we have another key named "myMultiplier" that has a value of 5:

//Expression
@myKey * myMultiplier@
 
 
//Output
50

Any characters outside of the "@" characters are not part of the expression, so you can easily add prefixes and suffixes with static text.

//Expression
Total: @myKey * myMultiplier@ gal
 
 
//Output
Total: 50 gal

Additionally, you can utilize separate Keychain Expressions in the same TextShape. Note that "myUnits" (which has a string value of "gal") is enclosed in a separate set of "@" characters, since it is a separate expression:

//Expression
Total: @myKey * myMultiplier@ @myUnits@
 
 
//Output
Total: 50 gal

Dynamic Data Key Expressions

Keychain Expressions may also be used with Dynamic Data Keys. The syntax and operators work exactly the same, except there is no need to type the "@" characters. Because of this, the entire field is treated as a single keychain expression.

Conditional Keychain Example

The following example demonstrates an if-statement using a Dynamic Data Key. This allows us to highlight different values or ranges contextually, making important values stand out.

Assuming a key named "myValue" has been created, and contains a numerical value, we can use the following syntax:

#If the value of the "myValue" key is greater than 5, a blue color will be returned. 
# Otherwise, a green color will be used.

myValue>5?"blue":"green"

In the image below, the Fill property is also using a dynamic data key, so the Fill Color will be disabled if myValue is less than 1, Blue if myValue is greater than 5, and Green if myValue is between 1 and 5. Note that in the Property inspector, the @ symbols are not needed.

To add more color-value pairs, we simply add more if statements to the end of the expression with a colon:

#If the value of "myValue" will determine one of multiple colors:
#Greater than 10 will return Red
#greater than 5 (but not greater than 10) will return Blue
#anything else will return Green.
@myValue>10?"red":myValue>5?"blue":"green"@

Operators and Functions

Operators

The following operators may be used in a Keychain expression.

Operator	Function	Example
Parenthesis	(expr) Nested Expressions	Any portion of a Keychain can be enclosed with parenthesis to guarantee precedence.
Multiplicative	*, /, % Multiply, divide, modulo	These are the most common and intuitive operators. You might want to display @quantityprice@ in an invoice line-item or calculate a percent like this @profit/revenue100@.
Additive	+, - Add, subtract	See multiplicative above
Relational	>, <, >=, <= Greater-than, less-than, greater/less-than-equal	These are most useful for conditionals: @amount>=0? "Credit" : "Debit"@ or @name=="this"? "that" : name@
Equality	==, != Equal, not-equal	See Relational above
Logical	AND &&	These operators make it possible to test multiple conditions: @revenue>100 && budget<50? "Winner!"@ or @name=="Jack"
Logical	OR ||	See AND above
Conditional	? : If/then - with form "expr? true_expr : false_expr"	Provides IF/THEN/ELSE expressions. Note: a false expression is optional. 'null' will be evaluated to false and non-null as true. You can provide null substitutions like this: @name? name : "(None provided)"@. You can also nest conditionals for more conditions. For example, @age>=21?"Adult":(age>12?"Teen":"Child")@.
Assignments	=, +=	For the brave, you can create temporary variables for use in a report. Most of the functionality you might use this for is covered in more intuitive ways (such as the Running key), but it is possible to define a variable in a header row: @revTotal=0@ and update it in details rows @revTotal+=revenue@.

Math Functions

The following functions return floats.

Menu Item	Function
floor(float)	Round input down to the nearest whole number.
ceil(float)	Round input up to the nearest whole number.
round(float)	Round input to the nearest whole number.
abs(float)	Returns the absolute value of the input (if number < 0 return number * -1).
min(float, float)	Returns the input number with the least value.
max(float, float)	Returns the input number with the greatest value.
pow(float, float)	Returns first number to the second number power.

String Functions

The following functions return strings.

Menu Item	Function
startsWith(String, String)	Returns true if the first string starts with the second.
endsWith(String, String)	Returns true if the first string ends with the second.
substring(String, int start)	Returns a substring of String beginning at position start.
join(List aList, String aKeyChain, String aDelimeter)	Used to display an individual attribute of individual objects as a single String. Suppose you have a list of movies and want to show their titles in a comma separated list: @join(getMovies, "getTitle", ", ")@
substring(Object aString, int start, int end)	Obtain a subset of a given string. This could be useful if you wanted to restrict a text field to a certain number of chars:@substring(title, 0, 10)@