improve ref block docu, add prefill with value solution

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
+--------------------reference
+
+- **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
 --------
 
@@ -27,3 +45,90 @@ 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 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: 
+
+
+
+```
+// 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
+  }
+}
+```