Merge branch 'main' into badge-does-not-refresh-automatically

docs/extensibility/100-jsonata.md

@@ -0,0 +1,63 @@
+# Use JSONata Expressions with Resource-Based Extensions
+
+## Scoping
+
+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.
+
+Additionally, the scope in arrays changes to the array item.
+
+For example, for this resource:
+
+```yaml
+spec:
+  name: foo
+  description: bar
+  items:
+    - name: item-name
+      details:
+        status: ok
+```
+
+The following definition has their scope changed as follows:
+
+```yaml
+- source: spec.name # top level, scope is the same as a resource
+
+- source: spec # top level, scope is the same as a resource
+  children:
+    - source: name # parent has source=spec, therefore this refers to spec.name
+
+- children:
+    - source: spec.name # As there's no parent source here, the scope is still the resource
+
+- source: spec.items
+  children:
+    - source: name # parent data is an array, therefore scope changes to its item - this refers to spec.items[0].name
+    - source: details.status # refers to spec.items[0].details.status (same as above)
+    - source: details # this changes scope for its children again
+      children:
+        source: status # this refers to spec.items[0].details.status
+```
+
+## Common Variables
+
+Common variables are the primary means to bypass the default scoping.
+
+- **\$root** - always contains the reference to the resource, so any JSONata in the example above can always be `$root.spec.name`.
+- **\$item** - refers to the most recent array item. When not in an array, it's equal to **\$root**.
+- **\$items** - contains an array of references to all parent array items (with the last item being equal to **\$item**).
+- **\$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.
+- **\$index** - exists in array components, refers to the index of the current item of an array.
+
+### Example
+
+```yaml
+- widget: Table
+  source: spec.rules
+  visibility: $exists($value)
+  collapsibleTitle: "'Rule #' & $string($index + 1)"
+```
+
+## Data Sources
+
+Whenever data sources are provided, they are available as corresponding variable names. For more information, see [Configure the dataSources Section](90-datasources.md).

docs/extensibility/101-preset-functions.md

@@ -0,0 +1,87 @@
+# JSONata Preset Functions for Resource-Based Extensions
+
+## canI (resourceGroupAndVersion, resourceKind)
+
+You can use the **canI** function to determine if a user has access rights to list a specified resource. The function comes with the following parameters:
+
+- **resourceGroupAndVersion**: Determines the first part of a resource URL following the pattern: `${resource group}/${resource version}`.
+- **resourceKind**: Describes a resource kind.
+
+### Example
+
+```yaml
+- path: spec.gateway
+  name: gateway
+  visibility: $not($canI('networking.istio.io/v1beta1', 'Gateway'))
+```
+
+## compareStrings (first, second)
+
+You can use this function to sort two strings alphabetically. The function comes with the following parameters:
+
+- **first**: Determines the first string to compare.
+- **second**: Determines the second string to compare.
+
+### Example
+
+Here is an example from the [ResourceList widget](./50-list-and-details-widgets.md#resourcelist):
+
+```yaml
+- widget: ResourceList
+  source: '$myDeployments()'
+  name: Example ResourceList Deployments
+  sort:
+    - source: '$item.spec.strategy.type'
+      compareFunction: '$compareStrings($second, $first)'
+      default: true
+```
+
+## matchByLabelSelector (item, selectorPath)
+
+You can use this function to match Pods using a resource selector. The function comes with the following parameters:
+
+- **item**: Describes a Pod to be used.
+- **selectorPath**: Defines a path to selector labels from `$root`.
+
+### Example
+
+Example from [dataSources](90-datasources.md).
+
+```yaml
+- podSelector:
+    resource:
+      kind: Pod
+      version: v1
+    filter: '$matchByLabelSelector($item, $root.spec.selector)'
+```
+
+## matchEvents (item, kind, name)
+
+You can use this function to match Events using a resource selector. The function comes with the following parameters:
+
+- **item**: Describes an Event to be checked.
+- **kind**: Describes the kind of the Event emitting resource.
+- **name**: Describes the name of the Event emitting resource.
+
+### Example
+
+```yaml
+- widget: EventList
+  filter: '$matchEvents($item, $root.kind, $root.metadata.name)'
+  name: events
+  defaultType: NORMAL
+  hideInvolvedObjects: true
+```
+
+## readableTimestamp (timestamp)
+
+You can use this function to convert time to readable time. The function comes with the following parameters:
+
+- **timestamp**: Defines a timestamp to convert.
+
+### Example
+
+```yaml
+- source: '$readableTimestamp($item.lastTransitionTime)'
+  name: status.conditions.lastTransitionTime
+```

docs/extensibility/110-presets.md

@@ -0,0 +1,37 @@
+# Configure the presets Section
+
+The **presets** section contains a list of objects that define which preset and template are used in the form view. If you specify a preset, it is displayed in the dropdown list along with the **Clear** option. When you select a preset, the form is filled with the values defined in the **value** property.
+
+## Available Parameters
+
+| Parameter   | Required | Type    | Description                                                                                      |
+| ----------- | -------- | ------- | ------------------------------------------------------------------------------------------------ |
+| **name**    | **Yes**  | string  | A name to display on the preset's dropdown.                                                      |
+| **value**   | **Yes**  |         | It contains the fields that are set when you choose the given preset from the list.              |
+| **default** | No       | boolean | If set to `true`, it prefills the form with values defined in **value**. It defaults to `false`. |
+
+## Example
+
+```yaml
+- name: template
+  default: true
+  value:
+    metadata:
+      name: my-name
+    spec:
+      description: A set description
+- name: preset
+  value:
+    metadata:
+      name: second-one
+    spec:
+      data: regex
+      description: A different description
+      items:
+        - name: item-1
+          value: 10
+        - name: item-2
+          value: 11
+        - name: item-3
+          value: 5
+```