Merge pull request #499 from kendraio/gosub-ref-docu-update

Update documentation for Gosub and Reference

docs/testing/tips.rst

@@ -2,9 +2,9 @@ Notes for Cypress testing
 =========================
 
 "https" not "http"
----------------
+------------------
 
-When tests are run within GitHub's environments, calls to external urls must be https, otherwise they will not run. 
+When tests are run within GitHub's environments, calls to external URLs must be https, otherwise they will not run. 
 This applies even to fixtures that don't even make external requests. 
 
 

docs/workflow/blocks/actions.rst

@@ -29,14 +29,9 @@ Supported properties
 
   - **label** (string) - the text for the button label
   - **id** (string) - the unique identifier for the button
-  - **color** (string) - passed as the “color” attribute to the material button. Use one of the supported
-    Material color values, such as “primary”, “warn”, “accent”. Leave as “default” to use the default button styling for a plain button.
-  - **enabledGetter** (string) - A value from the state or context. Based on this value, it generates an "enabled" property on the button.
-  The button will be shown as disabled (greyed out) or enabled accordingly. The default value of this property is `true`. After 
-  the block is loaded, it will automatically add a property to the block json: `"enabled": true`.
-  If `enabledGetter` is set to `false` the automatic property will be then shown as `"enabled": false`.
-  - **valueGetters** (string) - A value that will be pass as context to whichever action is being executed. 
-  This is a JMESPath mapping.
+  - **color** (string) - passed as the “color” attribute to the material button. Use one of the supported Material colour values, such as “primary”, “warn”, “accent”. Leave as “default” to use the default button styling for a plain button.
+  - **enabledGetter** (string) - A value from the state or context. Based on this value, it generates an "enabled" property on the button. The button will be shown as disabled (greyed out) or enabled accordingly. The default value of this property is `true`. After the block is loaded, it will automatically add a property to the block json: `"enabled": true`. If `enabledGetter` is set to `false` the automatic property will be then shown as `"enabled": false`.
+  - **valueGetters** (string) - A value that will be passed as context to whichever action is being executed. This is a JMESPath mapping.
   - **blocks** (array) - the list of workflow items to run when this button is pressed.
 
 Example
@@ -47,6 +42,7 @@ This example shows two buttons. The first one dispatches an asynchronous command
 block in order to start the inner workflow so that it runs and signals completion to the outer workflow.
 
 .. code-block:: json
+
   {
     "type": "actions",
     "buttons": [

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 (also called Gosubs)
+++++++++++++++++++++++++++++++++
 
 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.

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 namespace the embedded Flow belongs to (a name to group multiple Flows)
+- **workflowId**: A text identifier of the Flow to 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.

docs/workflow/blocks/mapping.rst

@@ -392,7 +392,7 @@ Examples:
    replace(data.email, '.', '')        // Output: "[email protected]"
 
 8. replaceAll
------------
+-------------
 
 Returns a string replacing all instances of a substring with another substring.
 
@@ -415,7 +415,7 @@ Examples:
    trim('  John Doe  ')  // Output: "John Doe"
 
 10. now
-------
+--------
 
 Returns the current UTC timestamp in RFC 7231 format.
 
@@ -441,7 +441,7 @@ Examples:
 12. omit
 --------
 
-Creates an object composed of enumerable properties from the input objects omitting the properties named in the *names array.
+Creates an object composed of enumerable properties from the input objects omitting the properties named in the *names* array.
 
 Examples:
 
@@ -622,7 +622,7 @@ Examples:
    markdown('## Header')  // Output: "<h2 id=\"header\">Header</h2>"
 
 23. btoa
--------
+---------
 
 Encodes a string in base-64.
 

docs/workflow/blocks/reference.rst

@@ -6,6 +6,24 @@ It expects to receive an array of options, and shows a drop-down select list whe
 one of the options can be selected. The selected option is output as the data from
 this block.
 
+Default config
+--------------
+
+.. code-block:: json
+
+    {
+        "type": "reference"
+    }
+
+Supported properties
+--------------------
+
+- **fieldLabel**: The label displayed above the select widget.
+- **labelGetter**: A property used to specify the field in the data for display as labels in the select options.
+- **valueField**: Specifies the field in the data that holds the value for each option.
+- **outputGetter**: Defines how the selected option’s value is output.
+
+
 Examples
 --------
 
@@ -28,5 +46,92 @@ input data items have a field called ``label`` you can omit these options.
 You can also set the ``required`` status of the input select list. This defaults
 to ``false``.
 
-At the moment, it does not seem possible to prefill the field with a selected value.
+At the moment, it does not seem possible to prefill the field with a selected value simply using the block property.
 There is a property called `defaultValue` which currently doesn't seems to work.
+
+To prefill the select value, embed the reference block within a form block. 
+The form's incoming data must contain the selected value, while the form’s configuration takes the options list from a predefined list in the context. 
+The list must follow a specific data structure, as shown below.
+
+.. code-block:: json
+
+    {
+        "type": "debug",
+        "open": 1,
+        "showData": true,
+        "showContext": true,
+        "showState": false
+    }
+
+    // Output of the debug
+
+    {
+        "data": {
+            "managerSelected": "John Smith"
+        }
+
+        "context": {
+            "managers": {
+                "anyOf": [
+                    {
+                        "title":"Will Teather",
+                        "const":1
+                    },
+                    {
+                        "title":"John Smith",
+                        "const":2
+                    },
+                    {
+                        "title":"Ross Sullivan",
+                        "const":3
+                    }
+                ]
+            }
+        }
+    }
+
+    {
+        "type": "form",
+        "hasSubmit": false,
+        "jsonSchema": {
+            "type": "object",
+            "properties": {
+                "managerSelected": {
+                    "title": "Select an Asset Manager",
+                    "$ref": "#/definitions/context/managers"
+                }
+            }
+        },
+        "uiSchema": {}
+    }
+
+TIP: Use this formula in a mapping block to transform an array into the "anyOf" data structure needed by the reference block: 
+
+
+
+.. code-block:: json
+
+    // Example of incoming data
+
+    [
+        {
+            "name":"Will Teather",
+            "asset_manager_id":1
+        },
+        {
+            "name":"John Smith",
+            "asset_manager_id":2
+        },
+        {
+            "name":"Ross Sullivan",
+            "asset_manager_id":3
+        }
+    ]
+
+
+    {
+        "anyOf": data[*].{
+            "title": name,
+            "const": asset_manager_id
+        }
+    }

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,