System StatusSamples on GitHub

Expressions

Expressions allow you to structure and manipulate data before binding it to the UI components. Expressions are JSONata-based. JSONata is a lightweight query and transformation language for JSON data. It also provides a rich complement of built-in operators and functions for manipulating and combining data.

Expressions are JSONata language-based. Learn more about JSONata and try out your expressions in their JSONata Exerciser. The root element of Expressions in .jigx files always starts with "@ctx" vs. "$$." in JSONata Exerciser (e.g. @ctx.data vs .$$.data). Jigx supports shorthand $ expressions for JSONata.

Syntax Rules

Essential Rules:

  • All expressions start with =

  • Use @ctx.* for context access

  • Use & for string concatenation (not +)

  • Use = for equality (not == or ===)

  • Use and/or/$not() for logical operations (not &&/||/!)

  • Avoid $$ and $ root references - use @ctx instead

Operators:

  • Equality: = (never ==)

  • Inequality: != (never !==, <>)

  • Logical: and, or, $not() (never &&, ||, !)

  • Concat: & (never + except for math)

  • Elvis: ?: (falsy fallback)

  • Null coalesce: ?? (null/undefined fallback)

  • Conditional: condition ? value_if_true : value_if_false

  • Type check: value ~> $type = 'string'

  • Regex: value ~> /pattern/

Expression structure

Avoid using state keywords, such as component, as instanceId values in expressions. Doing so will cause an "Expression is not valid" error in the app.

Using IntelliSense in Jigx Builder shows where and when you can add an expression by displaying the =$ or =@ctx. In Jigx expressions always start with =. Jigx converts @ctx. to $$. when executing expressions in JSONata.

Adding an empty array index [] in the path forces jsonata to return an array of one item versuses the normal behavior where it returns the item directly.

[email protected]
[{}] => {}
[{},{}] => [{},{}]

[email protected][]
[{}] => [{}] ← notice array of one
[{},{}] => [{},{}]

Advanced expressions

Advanced expressions are helpful when you need to filter an array of records to display specific data and perform expression transformations over the data. So, instead of writing complicated procedures and statements, you can run JSONata expressions to get the result. You can format the expression strings and have them inline or multi line.

Inline

When you are writing advanced expressions, make sure you have the expression starting with '=' inside the quotes, as shown below:

advanced-expression.jigx
text: "=(@ctx.datasources.table.field1 = '1' ? 'Jane' :'Rob')
  & ' ' &
  (@ctx.datasources.table.field2 = '2' ? 'Derek' :'Doe')"

Multiline

You can write advanced expressions as multiline, for better readability and cleaner code formatting. When writing a multiline expression, make sure you have the expression in quotes and the next line must be indented on the same level as shown below.

advanced-expression.jigx
title: "=(@ctx.datasources.table.field1 = '1' ? 'Jane' :'Rob')
  & ' ' &
  (@ctx.datasources.table.field2 = '2' ? 'Derek' :'Doe')"

Shared expressions

The shared expressions can be set either in the index.jigx file or in the jig itself. The expressions property is used for this and allows you to choose a custom name for the expression and save a value.

Global expressions set in the index.jigx

Expressions that are set in the index.jigx are reusable throughout your whole solution by referencing the global expression in the jig. Create the reference to the global expression by using [email protected].``name in the jig.

title: jigx-samples
name: jigx-samples

expressions:
  lat: [email protected]
  lng: [email protected]
  formatPrice: |
    =function($price, $currency) {
      $currency & $formatNumber($price, '#,##0.00')
    }
  userInitials: |
    =$uppercase($substring(@ctx.user.displayName, 0, 1) & 
    $substring($substringAfter(@ctx.user.displayName, ' '), 0, 1))

Expressions set inside the jig

These expressions are only available in the jig itself.

title: Shared expressions example
type: jig.default

expressions:
  numberOfEmployees: =$count(@ctx.datasources.employee-list.id)
  address: [email protected] & ', ' &   @ctx.datasources.employee-detail.county & ', ' & @ctx.datasources.employee-detail.city
  employee: [email protected] & ' ' & @ctx.datasources.employee-detail.surname & ', ' & @ctx.datasources.employee-detail.position

children:
  - type: component.entity
    options:
      isCompact: true
      children:
        - type: component.section
          options:
            title: All Employees
            children:
              - type: component.entity-field
                options:
                  label: Number of Employees
                  value: [email protected]
        - type: component.section
          options:
            title: Employee detail
            children:
              - type: component.entity-field
                options:
                  label: Employee
                  value: [email protected]
              - type: component.entity-field
                options:
                  label: Employee address
                  value: [email protected]

Reusable functions

Define reusable functions in Shared Expressions (@ctx.expressions).

# Define once, call many times
$add := function($a, $b){ $a + $b }
$add(2, 3)  # 5

# Optional/default handling via ?: / $exists
$greet := function($name){ ($name ?: 'World') & '!' }
$greet('Jigx') # "Jigx!"

# Pipe into functions (left value is first arg)
10 ~> $add(5)  # 15
$inc := function($x){ $x+1 }
41 ~> $inc()  # 42

# Closures (capture lexical variables)
$rate := 1.2
$mul := function($x){ $x * $rate }
$map([10, 20, 30], $mul)  # [12,24,36]

# Recursion
$fact := function($n){ $n <= 1 ? 1 : $n * $fact($n-1) }
$fact(5)  # 120

# Callbacks: ($v, $i, $a) = value, 1-based index, source array
$map(['a','b'], function($v, $i){ $i & ':' & $v })  # ["1:a","2:b"]

JavaScript expressions

You can use JavaScript functions in expressions to build logic into your solution. This makes repetitive and complex tasks less taxing and makes the code easier to read, understand, and debug. JavaScript functions surface as an expression in the YAML in Jigx Builder.

Wherever you can add an expression, you can use JSONata, Regex, JavaScript functions, or a combination of these to create logic in your app.

What is Supported?

  • Only .js files containing JavaScript functions are supported. Creating any file in the scripts folder, automatically adds the .js extension.

  • Currently, only date-fns libraries are supported. If you require other JavaScript libraries, contact [email protected].

  • Functions that call web services are not supported.

How does it work?

avaScript functions
avaScript functions

Create the JavaScript function

  • Open a solution in Jigx Builder.

  • Create a new file under the scripts/expressions folder and save it with a .js extension, for example, functions.js.

  • Within this file, you can define your functions.

    • For a single functions, you simply write the function definition.

    • For multiple functions, you can define each function in a single file or separate then into their own files.

  • Each function must be prefixed with export, for example, export function helloWorld() { return 'Hello World' }

  • Import is used to define the format for a specific function, for example, import { addDays, isWeekend, format } from 'date-fns'; export function getNextBusinessDay(date) { let nextDay = addDays(date, 1); while (isWeekend(nextDay)) { nextDay = addDays(nextDay, 1); } return format(nextDay, 'MMMM d, yyyy'); }

Call the JavaScript function in an expression

  • In a jig, where you configure an expression, use IntelliSense to surface the defined functions from the script/expression js files.

  • IntelliSense provides the javascript language options for selection starting with the =$ shortcut followed by the JavaScript file name and then the function name, such as =$functionFileName.functionName, for example, =$jsfunctions.helloWorld().

Considerations

  • One or more functions can be defined in a single JavaScript file. This caters for the exporting of files.

  • Multiple JavaScript files can be added under the script > expression folder.

  • In an expression, you can have functions inside functions, see tax calculation for an example.

  • JavaScript files are recognized throughout the solution and can by reused in multiple jigs.

  • JavaScript functions are not a replacement for JSONata expressions. Each has its purpose; combining the two will empower you while creating apps. In certain instances, JSONata is inline and can be quicker and easier than using a JavaScript function, such as concatenating first and last names.

  • JavaScript functions can be used instead of regex expressions used for validation. For example, JavaScript functions can be used to format a phone number rather than regex to validate if it is in the correct format.

  • Use F12 to navigate from an expression to the JavaScript function script file. See Go to Definition.

  • From the script file use shift + F12 or right-click and select Go to References to see where all the script file is used in expressions.

JSONata and Regular expressions

In Jigx you can combine a JSONata expression with a Regex expression to create a validation pattern and provide a message if the pattern does not match. See validation and regex expression examples for more information.

Best Practice

  • Use the following in expressions:

    • @ctx.*

    • & for concat

    • = for equality

    • and/or/$not() for logic

    • ?: for defaults

    • leading =

  • Avoid using the following in expressions:

    • $$/$ roots

    • + for strings

    • ==/===/!==/<>

    • &&/||/!

    • undefined access

  • Optimize data access in expressions with a single datasource access that uses multiple variables.

# Efficient - single access with variable
[email protected][0].('name' & ' - ' & 'email')

  • Use the following recommended expressions common and navigational functionality.

# Common
[email protected] ?: @ctx.user.email ?: 'Anonymous'
[email protected] ?: '-'
=$sum($map(@ctx.datasources.items, function($v){ $v.price }))
=$count(@ctx.jig.state.selected) > 0
[email protected][@ctx.user.id & '_preferences']
=$in(@ctx.solution.state.userRole, ['admin', 'manager'])

  • Advanced Semantics

    • Path projection flattens: applying .field to an array projects and flattens one level.

    • Predicate truthiness: empty sequence → false; non-empty sequence → true.

    • Function pipe ~>: left value becomes first argument; use parentheses to pass extras (e.g., value ~> $type).

    • Function callbacks receive ($v, $i, $a) = value, 1-based index, source array.

    • Variables: assign with := inside expressions; lexical scope.

Expression examples

Expressions are a powerful and flexible way to transform and extract data for use in a Jigx App. Below are links to examples showing how JSONata expressions can be used when creating apps.

JSONata expressions
Example of use

Arrays

Create filtered lists from arrays and handling arrays with SQL and Dynamic Data

Aggregation

To return minimum, maximum or an average value in an array.

Boolean

Evaluate data to find a true or false result.

Comparison Operators

Compare values in data and use the value in a conditional logical expression, e.g., is an amount greater than 100.

Date & Time

Return a date and time in various formats, e.g., ISO 8601.

Path Operators

Navigate and access specific elements or properties within a data set, e.g., for filtering or searching.

Functional Programming

Compare values or display data based on certain conditions and using logical statements, e.g., adding HTML variable in content, or a multi-select as a functionParameter.

Jigx Variables

Jigx variable set used in expressions to manipulate data specific to a Jigx App, e.g., determining the logged-in user, or the organization and solution.

Predicate Queries

Used for query refinement.

String

There are many uses for using string expressions, these can be to concatenate two strings to display multiple data records in one row or write numbers as strings, or select only a few characters from the whole string.

Advanced expressions

Advanced expressions are helpful when you need to filter an array of records to display specific data and perform expression transformations over the data.

Regex + JSONata

Create validation for text fields by combining JSONata and Regex expressions.

JavaScript expressions

JavaScript functions allow you to write modular and reusable code, by encapsulating specific functionality within JavaScript functions and calling the function in an expression.

See Also

PreviousLogicNextExpressions - Common Patterns

Last updated

Was this helpful?