---
title: "Keychain Expressions"
---
# Keychain Expressions
>
>
It's possible to perform calculations on data keys. This section documents the various operators and functions that are available.
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 @quantity*price@ in an invoice line-item or calculate a percent like this @profit/revenue*100@. |
| 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" || name=="Sam"? "Good Name!"@. |
| 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](data-keys.md#built-in-keys)), 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)@ |