From 7e2e6d709a778d5654e4e0eef6474512465eea8d Mon Sep 17 00:00:00 2001
From: gio <designbygio@pm.me>
Date: Fri, 8 Nov 2024 14:30:09 +0100
Subject: [PATCH] improve documentation for gosub

---
 docs/workflow/blocks/context_block.rst        |  4 +-
 docs/workflow/blocks/gosub.rst                | 80 ++++++++++++++++++-
 .../dialogs/add-block-dialog/block-types.ts   |  2 +-
 3 files changed, 81 insertions(+), 5 deletions(-)

diff --git a/docs/workflow/blocks/context_block.rst b/docs/workflow/blocks/context_block.rst
index 7075423ff..996406bdf 100644
--- a/docs/workflow/blocks/context_block.rst
+++ b/docs/workflow/blocks/context_block.rst
@@ -114,8 +114,8 @@ Security and access control
 There is currently no access control or protection in state. Any path in the global state is accessible (read and write) to any flow. 
 In the future some form of restriction may be implemented. 
 
-Subroutines
-+++++++++++
+Subroutines (Gosub)
++++++++++++++++++++
 
 Subroutines are Flows that are configured separately and used within a parent Flow.
 All data saved in a subroutine is stored in the context or state of the parent Flow.
diff --git a/docs/workflow/blocks/gosub.rst b/docs/workflow/blocks/gosub.rst
index 2aff5a6c6..12b54d61f 100644
--- a/docs/workflow/blocks/gosub.rst
+++ b/docs/workflow/blocks/gosub.rst
@@ -6,9 +6,85 @@ A Flow embedded within a Flow.
 This allows composition of larger building blocks to create Flows that
 are easier to manage, and DRY (don't repeat yourself).
 
+Default config
+--------------
+
+.. code-block:: json
+
+    {
+        "type": "gosub",
+        "adapterName": "",
+        "workflowId": ""
+    }
+
+Supported properties
+--------------------
+
+- **adapterName**: the name of the Flow's adapter that will be embedded.
+- **workflowId**: the id of the Flow's adapter that will be embedded.
+
 Typical use-cases for this are creating custom form widgets that can
-be referenced from a form's ``uiSchema``. Or, creating dashboards
-that are made up of multiple other Flows combined with a ``multi``
+be referenced from a form's ``uiSchema``. 
+The form property's name must match the data property name. 
+In this way the data will be passed down to the embedded Flow.
+
+
+
+
+.. code-block:: json
+
+    // Parent Flow data
+    {
+        "asset_name": "Gioconda",
+        "location": "https://someimages.com",
+        "asset_manager_id": "1"
+
+    }
+
+    {
+    "type": "form",
+    "jsonSchema": {
+        "type": "object",
+        "properties": {
+            "asset_title": {
+                "title": "Asset",
+                "type": "string"
+            },
+            "location": {
+                "title": "Location",
+                "type": "string"
+            },
+            "asset_manager_id": {
+                "type": "string",
+                "title": "Asset Manager"
+            }
+        }
+    },
+    "uiSchema": {
+        "location": {
+            "ui:widget": "remote-image"
+        },
+        "asset_manager_id": {
+            "ui:widget": "blocks",
+            "blocksConfig": {
+                "blocks": [
+                    {
+                        "type": "gosub",
+                        "adapterName": "culturebanked",
+                        "workflowId": "artist2-select-asset-manager"
+                    }
+                ]
+            }
+        }
+    }
+}
+
+In the example above, there are two Flows: the primary Flow, where the above configuration is written, and a secondary Flow with the Adapter "culturebanked" and Workflow ID "artist2-select-asset-manager".
+The "artist2-select-asset-manager" Flow is rendered as part of the parent Flow and is initiated with the data { "asset_manager_id": "1" }.
+If the property is modified in the uiSchema, the property name must be the same as the original data both in 
+the jsonSchema and in the uiSchema.
+
+Or, creating dashboards that are made up of multiple other Flows combined with a ``multi``
 multiplex Flow block.
 
 All data saved in a gosub is stored in the context or state of the parent Flow.
diff --git a/src/app/dialogs/add-block-dialog/block-types.ts b/src/app/dialogs/add-block-dialog/block-types.ts
index 6044725e4..f0d2583a7 100644
--- a/src/app/dialogs/add-block-dialog/block-types.ts
+++ b/src/app/dialogs/add-block-dialog/block-types.ts
@@ -467,7 +467,7 @@ export const BLOCK_TYPES = [
   },
   {
     type: 'gosub',
-    label: 'Subroutine',
+    label: 'Subroutine (Gosub)',
     description: 'Embed another workflow or partial workflow',
     icon: 'autorenew',
     hasEditor: true,