diff --git a/content/elements/fore/_index.md b/content/elements/fore/_index.md index 8a6456f9..73b79448 100644 --- a/content/elements/fore/_index.md +++ b/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 `` element will create the 'email' node in the right place of the document hierarchy. + + +``` + + ... + + + + ... + +``` + +If there would be no other controls the result would be: +``` + + + + + +``` + +`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 `` will apply as expected. + +> XML namespaces are fully supported. To resolve namespaces these must be declared on the `` element. ``. ## Examples