|
| 1 | +# Use JSONata Expressions with Resource-Based Extensions |
| 2 | + |
| 3 | +## Scoping |
| 4 | + |
| 5 | +The primary data source of [JSONata](https://docs.jsonata.org/overview.html) expressions changes depending on where it's used. Starting with the root, it contains the whole resource, but whenever it's in a child whose parent has a **source** (in lists and details) or **path** (in forms) parameter, the scope changes to data from that source or path. |
| 6 | + |
| 7 | +Additionally, the scope in arrays changes to the array item. |
| 8 | + |
| 9 | +For example, for this resource: |
| 10 | + |
| 11 | +```yaml |
| 12 | +spec: |
| 13 | + name: foo |
| 14 | + description: bar |
| 15 | + items: |
| 16 | + - name: item-name |
| 17 | + details: |
| 18 | + status: ok |
| 19 | +``` |
| 20 | +
|
| 21 | +The following definition has their scope changed as follows: |
| 22 | +
|
| 23 | +```yaml |
| 24 | +- source: spec.name # top level, scope is the same as a resource |
| 25 | + |
| 26 | +- source: spec # top level, scope is the same as a resource |
| 27 | + children: |
| 28 | + - source: name # parent has source=spec, therefore this refers to spec.name |
| 29 | + |
| 30 | +- children: |
| 31 | + - source: spec.name # As there's no parent source here, the scope is still the resource |
| 32 | + |
| 33 | +- source: spec.items |
| 34 | + children: |
| 35 | + - source: name # parent data is an array, therefore scope changes to its item - this refers to spec.items[0].name |
| 36 | + - source: details.status # refers to spec.items[0].details.status (same as above) |
| 37 | + - source: details # this changes scope for its children again |
| 38 | + children: |
| 39 | + source: status # this refers to spec.items[0].details.status |
| 40 | +``` |
| 41 | +
|
| 42 | +## Common Variables |
| 43 | +
|
| 44 | +Common variables are the primary means to bypass the default scoping. |
| 45 | +
|
| 46 | +- **\$root** - always contains the reference to the resource, so any JSONata in the example above can always be `$root.spec.name`. |
| 47 | +- **\$item** - refers to the most recent array item. When not in an array, it's equal to **\$root**. |
| 48 | +- **\$items** - contains an array of references to all parent array items (with the last item being equal to **\$item**). |
| 49 | +- **\$value** - when used in a JSONata other than **source** (for example **visibility**, but also other widget-specific formulas), contains the value returned by the source. |
| 50 | +- **\$index** - exists in array components, refers to the index of the current item of an array. |
| 51 | + |
| 52 | +### Example |
| 53 | + |
| 54 | +```yaml |
| 55 | +- widget: Table |
| 56 | + source: spec.rules |
| 57 | + visibility: $exists($value) |
| 58 | + collapsibleTitle: "'Rule #' & $string($index + 1)" |
| 59 | +``` |
| 60 | + |
| 61 | +## Data Sources |
| 62 | + |
| 63 | +Whenever data sources are provided, they are available as corresponding variable names. For more information, see [Configure the dataSources Section](90-datasources.md). |
0 commit comments