@ea-lab/reactive-json-docs 2.8.0 → 2.11.0

package/public/rjbuild/docs/core/reaction/submitData.md

@@ -7,7 +7,7 @@
 - The response can refresh the app (default) or be ignored.
 
 ## Properties
-- `url` (string, required): The destination URL for the request
+- `url` (string or array, required): The destination URL for the request: a string or a template reference, or an array of segments built like the `src` of `additionalDataSource` (references evaluated in the current template context). No request is sent when the URL is empty, or when a required segment is empty. See [Dynamic URLs with `src` as Array](../../getting-started/rjbuild-structure.md#dynamic-urls-with-src-as-array).
 - `httpMethod` (string, optional): The HTTP method to use (default: "post")
 - `data` (object, optional): The data to send. If not specified, data is sent in an object with the structure `{ data: globalDataContext.templateData }`. If `__state` exists in the context, it is automatically added.
 - `refreshAppOnResponse` (boolean, optional): If true (default), reloads the application with the server response. If false, the response is ignored and **no change is made to the application's state or display** (just like `fetchData`).

package/public/rjbuild/docs/core/reaction/submitData.yaml

@@ -15,8 +15,10 @@ renderView:
     content:
       - term:
           code: url
-          after: "(string, required)"
-        details: "The destination URL for the request"
+          after: "(string or array, required)"
+        details:
+          type: Markdown
+          content: "The destination URL for the request: a string or a template reference, or an array of segments built like the `src` of `additionalDataSource` (references evaluated in the current template context). No request is sent when the URL is empty, or when a required segment is empty."
       - term:
           code: httpMethod
           after: "(string, optional)"

package/public/rjbuild/docs/core/reaction/toggleData.md

@@ -0,0 +1,72 @@
+# Reaction: toggleData
+
+The `toggleData` reaction adds a value to an array when it is absent, and removes it when it is present. The other values of the array are kept. It is the building block of on/off filters and of data-driven selections (tags, recipients, checked rows).
+
+## Properties
+
+- `path` (string, required): The location of the array (template syntax).
+- `value` (any, required): The value to add or remove. It is evaluated, so it can be a literal or a template reference.
+
+## Behavior
+
+- The value is appended when it is absent from the array, and removed when it is present. The order of the other values is kept.
+- A missing location, or a location that does not hold an array, counts as an empty array: the result is always an array.
+- The values are compared as strings: a numeric identifier (`12`) matches its text form (`"12"`).
+- Nothing happens when the value is `null`, `undefined` or an empty string, such as a value coming from a data source that is not loaded yet. The array never receives an empty value.
+- The current array is read from the complete data, even inside a `DataFilter`.
+
+## Examples
+
+### Filter toggle
+
+```yaml
+renderView:
+  - type: button
+    content: "My tasks"
+    actions:
+      - what: toggleData
+        on: click
+        path: ~~.filters.assignee
+        value: ~~.currentUser.id
+
+data:
+  currentUser:
+    id: 12
+  filters:
+    assignee: []
+```
+
+### One toggle per list item
+
+```yaml
+renderView:
+  - type: Switch
+    content: ~~.rows
+    singleOption:
+      load: row
+
+templates:
+  row:
+    type: button
+    content: ~.title
+    actions:
+      - what: toggleData
+        on: click
+        path: ~~.selection
+        value: ~.id
+
+data:
+  rows:
+    - id: 1
+      title: "First"
+    - id: 2
+      title: "Second"
+  selection: []
+```
+
+To show the state of each item, use `attributeTransforms` with a `contains` condition on the array (see [CheckBoxField](../element/form/CheckBoxField.md#data-driven-checkbox-lists)).
+
+## Limitations
+
+- Only arrays of scalar values are supported: objects are compared by their string form.
+- `addData` appends without checking duplicates, and `removeData` removes by path: use `toggleData` to add or remove a known value.

package/public/rjbuild/docs/core/reaction/toggleData.yaml

@@ -0,0 +1,77 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Reaction: toggleData
+
+      The `toggleData` reaction adds a value to an array when it is absent, and removes it when it is present. The other values of the array are kept. It is the building block of on/off filters and of data-driven selections (tags, recipients, checked rows).
+
+      ## Properties
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: path
+          after: "(string, required)"
+        details: "The location of the array (template syntax)."
+      - term:
+          code: value
+          after: "(any, required)"
+        details: "The value to add or remove. It is evaluated, so it can be a literal or a template reference."
+
+  - type: Markdown
+    content: |
+      ## Behavior
+
+      - The value is appended when it is absent from the array, and removed when it is present. The order of the other values is kept.
+      - A missing location, or a location that does not hold an array, counts as an empty array: the result is always an array.
+      - The values are compared as strings: a numeric identifier (`12`) matches its text form (`"12"`).
+      - Nothing happens when the value is `null`, `undefined` or an empty string, such as a value coming from a data source that is not loaded yet. The array never receives an empty value.
+      - The current array is read from the complete data, even inside a `DataFilter`.
+
+  - type: RjBuildDescriber
+    title: "One toggle per list item"
+    description: "Each button adds or removes the id of its item in the selection."
+    toDescribe:
+      renderView:
+        - type: Switch
+          content: ~~.rows
+          singleOption:
+            load: row
+        - type: div
+          content:
+            - type: strong
+              content: "Selection: "
+            - type: Join
+              content: ~~.selection
+              separator: ", "
+      templates:
+        row:
+          type: button
+          attributes:
+            type: button
+            style:
+              marginRight: "0.5rem"
+          content: ~.title
+          actions:
+            - what: toggleData
+              on: click
+              path: ~~.selection
+              value: ~.id
+      data:
+        rows:
+          - id: 1
+            title: "First"
+          - id: 2
+            title: "Second"
+          - id: 3
+            title: "Third"
+        selection: []
+
+  - type: Markdown
+    content: |
+      To show the state of each item, use `attributeTransforms` with a `contains` condition on the array (see [CheckBoxField](../element/form/CheckBoxField)).
+
+      ## Limitations
+
+      - Only arrays of scalar values are supported: objects are compared by their string form.
+      - `addData` appends without checking duplicates, and `removeData` removes by path: use `toggleData` to add or remove a known value.

package/public/rjbuild/docs/getting-started/reactions.md

@@ -71,6 +71,10 @@ Reactive-JSON provides several built-in reactions:
 - **addData**: Adds new data to the specified path.
 - **removeData**: Removes data from the specified path.
 - **moveData**: Moves data from one path to another.
+- **toggleData**: Adds a value to an array when absent, removes it when present.
+- **collectField**: Writes the values of a field of every item of a collection as an array.
+- **joinData**: Writes a string built from several parts.
+- **stringifyData**: Writes the JSON representation of a value.
 
 ### Network Operations
 - **fetchData**: Fetches data from a URL using GET requests.
@@ -81,6 +85,7 @@ Reactive-JSON provides several built-in reactions:
 - **redirectNow**: Performs an immediate redirect.
 - **triggerEvent**: Triggers a custom event.
 - **postMessage**: Sends a message to another window/frame.
+- **printPage**: Opens the print dialog of the browser.
 
 For detailed documentation of each reaction, including properties and examples, see their respective documentation pages.
 

package/public/rjbuild/docs/getting-started/reactions.yaml

@@ -96,6 +96,10 @@ renderView:
       - **[addData](../core/reaction/addData)**: Adds new data to the specified path.
       - **[removeData](../core/reaction/removeData)**: Removes data from the specified path.
       - **[moveData](../core/reaction/moveData)**: Moves data from one path to another.
+      - **[toggleData](../core/reaction/toggleData)**: Adds a value to an array when absent, removes it when present.
+      - **[collectField](../core/reaction/collectField)**: Writes the values of a field of every item of a collection as an array.
+      - **[joinData](../core/reaction/joinData)**: Writes a string built from several parts.
+      - **[stringifyData](../core/reaction/stringifyData)**: Writes the JSON representation of a value.
 
       ### Network Operations
       - **[fetchData](../core/reaction/fetchData)**: Fetches data from a URL using GET requests.
@@ -106,6 +110,7 @@ renderView:
       - **[redirectNow](../core/reaction/redirectNow)**: Performs an immediate redirect.
       - **[triggerEvent](../core/reaction/triggerEvent)**: Triggers a custom event.
       - **[postMessage](../core/reaction/postMessage)**: Sends a message to another window/frame.
+      - **[printPage](../core/reaction/printPage)**: Opens the print dialog of the browser.
 
       For detailed documentation of each reaction, including properties and examples, see their respective documentation pages.
 

package/public/rjbuild/docs/getting-started/rjbuild-structure.md

@@ -336,10 +336,14 @@ additionalDataSource:
     blocking: true
 ```
 
+**Array values:** when the value resolves to an array, the param is repeated for each item: `{ param: "domains", value: ~~.domains }` with `domains: ["a.fr", "b.fr"]` gives `?domains=a.fr&domains=b.fr`. The empty items are skipped, and an empty array counts as an empty value. For a PHP backend, name the param with brackets (`domains[]`) to receive an array.
+
 **Null handling for params:**
 - If either the key or the value resolves to `null`/empty and `required` is absent or `false`, the param is **silently omitted** from the URL.
 - If either resolves to `null`/empty and `required: true` is set, the entire URL is **aborted**, triggering `fallbackDataSource` if defined.
 
+An aborted URL logs a warning naming the caller (`additionalDataSource`, `redirectNow`, `href attribute`...), the empty part and its position in the array.
+
 ```yaml
 additionalDataSource:
   - src:
@@ -355,7 +359,7 @@ additionalDataSource:
 
 #### Mixing all three types
 
-Path parts (plain strings, `~~.`/`~.` strings, and `segment` objects) are concatenated in order. All `param` objects are collected and appended as a query string after the path.
+Path parts (plain strings, `~~.`/`~.` strings, and `segment` objects) are concatenated in order. All `param` objects are collected and appended as a query string after the path. When the path already holds a query string (`/api/items?sort=asc`), the parameters continue it with `&`.
 
 ```yaml
 additionalDataSource:
@@ -400,6 +404,24 @@ data:
   timeLogs: []
 ```
 
+#### The same format elsewhere
+
+The segments format is also accepted by:
+
+- `url` of the [fetchData](../core/reaction/fetchData.md) and [submitData](../core/reaction/submitData.md) reactions: no request is sent when a required segment is empty;
+- `to` of the [redirectNow](../core/reaction/redirectNow.md) reaction: no navigation when a required segment is empty;
+- the URL attributes (`href`, `src`, `action`, `formAction`, `poster`) of any element: the attribute is omitted when a required segment is empty;
+- `parts` of the [joinData](../core/reaction/joinData.md) reaction, which writes the composed string in the data.
+
+There, the references are evaluated in the current template context: `~.slug` reads the current template data (e.g. the current `Switch` item), `~~.` the global data, `~>key` an ancestor. In `additionalDataSource.src`, both `~.` and `~~.` read the root data. In a reaction, the event placeholders also work in the parts, `required` included: `{ segment: "<reactive-json:event-new-value>.id", required: true }`.
+
+```yaml
+- type: a
+  attributes:
+    href: ["/article/", ~.year, "/", { segment: ~.slug, required: true }]
+  content: ~.title
+```
+
 ### Fallback Sources
 
 The `fallbackDataSource` property defines an alternate source that is tried automatically when the primary source cannot be used. It accepts the same structure as a regular `additionalDataSource` item, including its own `fallbackDataSource` for chaining.

package/public/rjbuild/docs/getting-started/rjbuild-structure.yaml

@@ -355,10 +355,14 @@ renderView:
 
       A param object adds a key-value pair to the URL query string. Both the key and the value accept store references.
 
+      **Array values:** when the value resolves to an array, the param is repeated for each item: `{ param: "domains", value: ~~.domains }` with `domains: ["a.fr", "b.fr"]` gives `?domains=a.fr&domains=b.fr`. The empty items are skipped, and an empty array counts as an empty value. For a PHP backend, name the param with brackets (`domains[]`) to receive an array.
+
       **Null handling:**
       - If either the key or the value resolves to `null`/empty and `required` is absent or `false`, the param is **silently omitted** from the URL.
       - If either resolves to `null`/empty and `required: true` is set, the entire URL is **aborted**, triggering `fallbackDataSource` if defined.
 
+      An aborted URL logs a warning naming the caller (`additionalDataSource`, `redirectNow`, `href attribute`...), the empty part and its position in the array.
+
   - type: TabbedSerializer
     yamlSerializedContent: |
       additionalDataSource:
@@ -379,7 +383,7 @@ renderView:
 
       #### Mixing all three types
 
-      Path parts (plain strings, `~~.`/`~.` strings, and `segment` objects) are concatenated in order. All `param` objects are collected and appended as a query string after the path.
+      Path parts (plain strings, `~~.`/`~.` strings, and `segment` objects) are concatenated in order. All `param` objects are collected and appended as a query string after the path. When the path already holds a query string (`/api/items?sort=asc`), the parameters continue it with `&`.
 
   - type: TabbedSerializer
     yamlSerializedContent: |
@@ -428,6 +432,26 @@ renderView:
         taskId: ""    # Will be overridden by dataOverride
         timeLogs: []
 
+  - type: Markdown
+    content: |
+      #### The same format elsewhere
+
+      The segments format is also accepted by:
+
+      - `url` of the [fetchData](../core/reaction/fetchData) and [submitData](../core/reaction/submitData) reactions: no request is sent when a required segment is empty;
+      - `to` of the [redirectNow](../core/reaction/redirectNow) reaction: no navigation when a required segment is empty;
+      - the URL attributes (`href`, `src`, `action`, `formAction`, `poster`) of any element: the attribute is omitted when a required segment is empty;
+      - `parts` of the [joinData](../core/reaction/joinData) reaction, which writes the composed string in the data.
+
+      There, the references are evaluated in the current template context: `~.slug` reads the current template data (e.g. the current `Switch` item), `~~.` the global data, `~>key` an ancestor. In `additionalDataSource.src`, both `~.` and `~~.` read the root data. In a reaction, the event placeholders also work in the parts, `required` included: `{ segment: "<reactive-json:event-new-value>.id", required: true }`.
+
+      ```yaml
+      - type: a
+        attributes:
+          href: ["/article/", ~.year, "/", { segment: ~.slug, required: true }]
+        content: ~.title
+      ```
+
   - type: Markdown
     content: |