# Keychain Expressions

### Key Calculations

Watch the videoIt'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 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 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.

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)@ |