Documents the Link Action block

docs/workflow/blocks/link_action_block.rst

@@ -0,0 +1,92 @@
+Link Action block
+===========
+The Link Action block provides a user-friendly button that links to other Flows. Like a normal link, the user can choose how Flows are opened, according to their browser configuration.
+Existing Flows that use a combination of an Action block and a Launch block to open a Flow, can be replaced by the Link Action block to provide the user with more control.
+Often when browsers present buttons to navigate to new screens, (such as when a Flow uses an Action block with a Launch block), the user is not given control over where the browser will open the new screen. Instead of allowing users to open the new screen in a new tab or window, the user may be forced to navigate away from their current screen, which unfortunately could cause context from the current tab to be lost! To provide the user with more control, the Link Action block can be used instead to produce buttons that allow opening a specified Flow in a new tab or window, or even the same browser context.
+
+For example, when a laptop user right-clicks a button generated by the Link Action block, their browser will typically present a context menu, then the user may choose to open the specified Flow in a new tab, allowing them to keep the existing Flow they have been using, as it is - without needing to navigate away from it.
+To perform the same behavior without using a right mouse button users typically hold the Cmd or Ctrl button and then click (Ctrl+click for Windows/Linux, and Cmd+click for macOS).
+
+Without relying on browser pop-ups, the Link Action block links to Flows in the browser's chosen context by using a browser anchor tag, as normally used for web page links, with the link styled as a button for a consistent user experience.
+
+By default, links to Flow's made with the Link Action block will open in the same window/tab context, but users with a mouse input device may right-click to open the link in a new tab or window, or on mobile devices with touchscreens, typically users would press and hold to open a Flow link produced by the Link Action block in a new tab.
+
+On supported browsers, users may notice the destination Flow is shown when hovering over the link, this allows the user to directly see where the button would navigate to.
+
+Default configuration
+--------------
+
+.. code-block:: json
+
+    {
+      "type": "link-action",
+      "label": "Open Workflow",
+      "adapterName": "adapterName",
+      "workflowId": "workflowId"
+    }
+
+Supported Properties
+--------------------
+
+- **label** (string): The text displayed on the button-like link. Defaults to "Link".
+- **adapterNameGetter** (string): A JMESPath expression that resolves to the adapter name of the target workflow. This allows for dynamic resolution of the adapter name from the data and context. If not set, will use the `adapterName` property instead.
+- **adapterName** (string): The adapter name of the target workflow. This property is used if `adapterNameGetter` is not specified.
+- **workflowIdGetter** (string): A JMESPath expression that resolves to the workflow ID of the target workflow. This allows for dynamic resolution of the workflow ID from the data and context. If not set, will use the `workflowId` property instead.
+- **workflowId** (string): The workflow ID of the target workflow. This property is used if `workflowIdGetter` is not specified.
+
+Usage
+-----
+
+The block can be configured for use in a static or dynamic way.
+
+1. **Standalone Link:**
+    - Use hardcoded values for `adapterName` and `workflowId` to create a static link to a specific Flow.
+
+2. **Within a Grid Cell:**
+    - Embed the block within the `cellRendererParams` of a grid column definition to provide a clickable link for each row.
+    - Use JMESPath expressions in `adapterNameGetter` and `workflowIdGetter` to dynamically generate the link URL based on the row data.
+    - Alternatively, use the `adapterName` and `workflowId` properties for static links within the grid.
+
+Example 1: Static Flow links (not dynamic)
+------------------------------------------
+
+To create a standalone button with a hardcoded link to a Flow, in the configuration for the block, provide the `adapterName` and `workflowId` properties:
+
+.. code-block:: json
+
+    {
+        "type": "link-action",
+        "label": "View Details",
+        "adapterName": "myAdapter",
+        "workflowId": "myWorkflow"
+    }
+
+In this example, it will create a link with the label "View Details" that points to the `/myAdapter/myWorkflow` route.
+
+Example 2: Dynamic Flow links within a grid
+-------------------------------------------
+
+This example demonstrates using the `LinkActionComponent` within a grid cell to link to individual Flows:
+
+**Grid column example:**
+
+.. code-block:: json
+
+    {
+        "headerName": "Operations",
+        "cellRenderer": "workflowRenderer",
+        "cellRendererParams": {
+            "blocks": [
+                {
+                    "type": "link-action",
+                    "label": "Launch",
+                    "adapterNameGetter": "data.adapterName",
+                    "workflowIdGetter": "data.id"
+                }
+            ]
+        }
+    }
+
+In this configuration:
+- `data.adapterName` and `data.id` are JMESPath expressions that retrieve the adapter name and workflow ID from the current row's data.
+- The generated link for each row will point to the corresponding Flow.