Update _index.md

create-nodes docs

content/elements/fore/_index.md

@@ -17,6 +17,7 @@ and provides the following facilities:
 
 | Name | Description                                                              | default |
 |------|--------------------------------------------------------------------------|---------|
+| create-nodes | If attribute is present, non-existing XML data nodes will be created from UI Binding expressions | - |
 | ignore-expressions | if given is expected to contain a CSS selector that matches element to excluded from Template Expression handling | - |
 | [foreign attributes] | Foreign attributes are all other attributes being present. These will be copied to the resulting `fx-fore` element if `src` is used for loading an external page. These can be accessed with the `fore-attr()` function | - | 
 | show-confirmation | either just marker attribute or boolean XPath |  -      |
@@ -37,6 +38,46 @@ Likewise when an XPath expression is given as the attribute value it is evaluate
 | ready             | dispatched after Fore has fully been initialized |
 | error             | dispatches error when template expression fails to evaluate |
 
+## create-nodes
+
+The usual behavior for controls is to become 'nonrelevant' and not be shown in the UI if there's no data node matching
+the binding expression (`ref`). This allows to show/hide parts of the UI depending on users' choices and is a powerful way to build dynamic UIs.
+
+However this creates problems with other use cases where there's a schema to support and the goal is build an editor for it.
+
+The `create-nodes` attribute solves this common problem with editing XML documents. Quite often a given document does not use all elements and attributes that would be possible from its schema. But to edit the document the UI must show these additional nodes and provide a control to edit them. As there's no node the control can bind to, it has no place to put a value the user inputs. - the node needs to be created first.
+
+Traditional solution to this is to merge the data to be edited with a full template structure containing all possible nodes. However XML merging is not a trivial process when considering all the possible cases. Further it requires extra effort and an additional toolchain to handle this merging and a page author needs to explicitly handle it in a page.
+
+To overcome this issue the `create-nodes` attribute was introduced which will create missing nodes in the data from the UI bindings automatically at startup time. 
+
+Example: assume you have an 'email' field that is not yet present in the edited data. Putting a control into the UI that binds to that field and adding the `create-nodes` attribute to `<fx-fore>` element will create the 'email' node in the right place of the document hierarchy.
+
+
+```
+<fx-fore create-nodes>
+  ...
+  <fx-control ref="contact/email">
+    <label>Email (optional)</label>
+  </fx-control>
+  ...
+</fx-fore>
+```
+
+If there would be no other controls the result would be:
+```
+<data>
+  <contact>
+    <email>
+  </contact>
+</data>
+```
+
+`create-nodes` will looks for all `ref` expressions in the UI, check if a node already exists and if not, create the necessary nodes from the binding expression. In this case it will first create `contact` and afterwards `email` and attach those to the default instance. 
+
+This happens even before the UI is created and afterwards processsing will continue as usual. Additional `relevant` conditions defined by `<fx-bind ref='something' relevant='some-boolean-expression'>` will apply as expected. 
+
+> XML namespaces are fully supported. To resolve namespaces these must be declared on the `<fx-fore>` element. `<fx-fore xmlns:foo="bar">`.
 
 
 ## Examples