Skip to content

Custom Expressions

Expressions Overview

Expressions allow complex tag-based logic to set a property. Expressions are evaluated on the main GUI thread.

Expression

Expressions are broken down into two phases: the math phase and the formatting phase. In the math phase, one can use tags to compute various mathematical operations to get a single value. The formatting phase is intended for displaying purposes. Formatting options would include things like specifying the number of decimals for a number, date time string format, etc.

Math

The math phase will always return a single numeric value. A good way of thinking about this phase is to think it as a calculator where the only allowed inputs are tag values, constants, and operations on those values. All constants are treated as doubles, including boolean values (e.g., 1.0/0.0).

Operators

  • Tag ([<Tag name>])
  • Constants (pi, epsilon, inf)
  • Basic math operators (+, -, *, /, %)
  • Functions (min, max, avg, sum, abs, ceil, floor, round, exp, log, log10, logn, pow, root, sqrt, clamp)
  • Trigonometry (sin, cos, tan, acos, asin, atan, atan2, cosh, cot, csc, sec, sinh, tanh)
  • Equalities (==, !=, <, <=, >, >=)
  • Control (if, then, else)

Format

The format phase will always return a single string value. A good way of thinking about this phase is to think of the value from the math value being converted into some reasonable string. Because of this, using formatting options will convert the math value into a string.

Operators

round(decimalPlaces)
  • Returns a number rounded to the nearest decimalPlaces decimal places.
base(base)
  • Returns a string equivalent of the input number according to the specified base.
numericFormat(format)
  • Returns a string formatted by the pattern described in format. Invalid formats will return an empty string.

  • Format:

    CharacterDescription
    #Denotes a basic decimal character. If used past a decimal point, it will specify the minimum number of decimal values to show. This is not compatible with hexadecimal formats.
    HDenotes a hexadecimal character. This is not compatible with decimal formats.
    0Denotes a zero fill character. The index of this character will be used as the minimum number of digits to display before a decimal point. There should be at most one of these.
    .Denotes a decimal point. There should be at most one of these in a decimal format, and it is not compatible with hexadecimal formats.
    ,Denotes a group separator. The index of this character will be used as the number of digits to group. There should be at most one of these, and they cannot be used past a decimal point.
  • Examples:

    InputFormatResult
    123#"123"
    123#,###"123"
    1230###"0123"
    123##.##"123.00"
    123456#,###"123,456"
    123456##,##"12,34,56"
    1#0##"001"
    1234#,0##"1,234"
    123HH"7B"
dateTimeFormat(format)
  • Returns the Unix timestamp as a string in the form described in format.

  • Format:

    OptionOutput
    hThe hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display)
    hhThe hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display)
    HThe hour without a leading zero (0 to 23, even with AM/PM display)
    HHThe hour with a leading zero (00 to 23, even with AM/PM display)
    mThe minute without a leading zero (0 to 59)
    mmThe minute with a leading zero (00 to 59)
    sThe whole second, without any leading zero (0 to 59)
    ssThe whole second, with a leading zero where applicable (00 to 59)
    zThe fractional part of the second, to go after a decimal point, without trailing zeroes (0 to 999). Thus, "s.z" reports the seconds to full available (millisecond) precision without trailing zeroes
    zzzThe fractional part of the second, to millisecond precision, including trailing zeroes where applicable (000 to 999).
    AP or AUse AM/PM display. A/AP will be replaced by an upper-case version of either QLocale::amText() or QLocale::pmText()
    ap or aUse am/pm display. a/ap will be replaced by a lower-case version of either QLocale::amText() or QLocale::pmText()
    tThe timezone (for example "CEST")
    dThe day as a number without a leading zero (1 to 31)
    ddThe day as a number with a leading zero (01 to 31)
    dddThe abbreviated localized day name (e.g. 'Mon' to 'Sun'). Uses the system locale to localize the name, i.e. QLocale::system()
    ddddThe long localized day name (e.g. 'Monday' to 'Sunday'). Uses the system locale to localize the name, i.e. QLocale::system()
    MThe month as a number without a leading zero (1 to 12)
    MMThe month as a number with a leading zero (01 to 12)
    MMMThe abbreviated localized month name (e.g. 'Jan' to 'Dec'). Uses the system locale to localize the name, i.e. QLocale::system()
    MMMMThe long localized month name (e.g. 'January' to 'December'). Uses the system locale to localize the name, i.e. QLocale::system()
    yyThe year as a two digit number (00 to 99)
    yyyyThe year as a four digit number. If the year is negative, a minus sign is prepended, making five characters.
  • Example format strings (assumed that the Unix timestamp is 990447189120):

    FormatResult
    dd.MM.yyyy21.05.2001
    ddd MMMM d yyTue May 21 01
    hh:mm:ss .zzz14:13:09.120
    hh:mm:ss .z14:13:09.12
    h:m:s ap2:13:9 pm
map(format)
  • Returns the value that falls in the range provided in format based on the input value. The following is the expected syntax of the format:
    • A list of range values separated by a comma
    • A range value is defined as:
      • Starts with {
      • A pair of a range and a value
      • A range is defined as:
        • Starts with [ or (
          • A [ implies inclusive
          • A ( implies exclusive
        • A pair of numeric values separated by a comma
          • An empty numeric value implies either positive infinity or negative infinity, depending on which side of the pair it is on
          • "inf", "+inf" resolve to infinity
          • "-inf" resolves to negative infinity
        • Ends with ] or )
          • A ] implies inclusive
          • A ) implies exclusive
        • Ends with }
    • A default value may be specified with a | character
hasPermission(permission)
  • Returns whether or not the currently signed-in user has permission: permission. This is the expression equivalent to the script with the same name: system.hasPermission()

Examples

Get Tag

  • Expression: {[TAG1]}
  • Possible output: 10

Round Value

  • Expression: {round[TAG1]}
  • Possible output: 6

Add Tags

  • Expression: {[TAG1] + [TAG2]}
  • Possible output: 30

Format Sum

  • Expression: {([TAG1] + [TAG2])|numericFormat("#,###")}
  • Possible output: 1,456

Return Value as Binary

  • Expression: {[TAG1] + [TAG2]|base(2)}
  • Possible output: 11110

Conditional Value

  • Expression: {if ([TAG1] % 2) [TAG2]; else [TAG3];}
  • Possible output: 1 or 3

Convert °C to °F

  • Expression: {([CelsiusTag] * 9 / 5) + 32}
  • Possible output: If CelsiusTag = 20, 68

Embed Values into String

  • Expression: Temp: {[TAG1]} | Pressure: {[TAG2]}
  • Possible output: Temp: 1 | Pressure: 2

Map Values from Range

  • Expression: {[TAG1]|map("{,0),-1},{[0,10),0},{[10,20),1},{[20,30),2},|nan")}

  • Possible outputs:

    TAG1Output
    -10"-1"
    0"0"
    1"0"
    15"1"
    30"nan"

Check User Permission

  • Expression: {[TAG1]|hasPermission("Open Page")}
  • Possible outputs: False: 0, True: 1