You're currently browsing the Ignition 7.9 docs. Click here to view the latest docs.

 

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 that is largely similar in syntax to Java.  To separate this language from others in Ignition, we refer to it as a Keychain Expression. 

Keychain Expressions are configured by simply utilizing any operators or functions within the "@" characters. Assuming a key named "myKey" with a value of 100, we can multiply 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.


On this page ...


IULocgo

Key Calculations



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 between 1 and 4, and Green if greater or equal to 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.

OperatorFunctionExample
Parenthesis(expr) Nested expressionsAny portion of a Key Chain 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 @quantity*price@ in an invoice line-item or calculate a percent like this @profit/revenue*100@.

Additive+, - Add, subtractSee multiplicative above
Relational>, <, >=, <= Greater-than, less-than, greater/less-than-equalThese are most useful for conditionals: @amount>=0? "Credit" : "Debit"@ or @name=="this"? "that" : name@
Equality==, != Equal, not-equalSee Relational above
Logical AND &&These operators make it possible to test multiple conditions: @revenue>100 && budget<50? "Winner!"@ or @name=="Jack" || name=="Sam"? "Good Name!"@.
LogicalOR ||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 ItemFunction
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 ItemFunction
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)@


  • No labels