View source for XForms:Refreshing Controls

==Keeping Controls Up-To-Date in XForms==

===Controls and their bound node===

The control is itself responsible for attaching to the model and telling the
model two things that it depends on:

# A ''context node'', which is the node that they are bound to
# A list of ''dependencies'', which are data nodes that will incluence which node that the control is bound to.

The model uses that to inform the control to either refresh the value, or
evaluate its binding expression again.


===How do controls find their bound node and their context?===

To find the node that a control is bound to, it evaluates its ''node binding
expression'' found in one of its attributes. Depending on the control this
might be <code>bind</code>, <code>ref</code>, <code>nodeset</code>,
<code>value</code> or <code>src</code>.

In order to evaluate an XPath expression though, there needs to be a ''context
node''. To find it there are two cases:

# The control does not have any XForms controls as ancestors (in the DOM).<br/>The context node is then the document node of the default instance document of the default model, or the model specificed by the <code>model</code> attribute on the node.
# The control has an XForms ancestor (in the DOM)<br/> The context node is then the bound node of the closest ancestor. Unless the control has a <code>model</code> attribute. Then it is the closest ancestor that uses the same model. If no ancestor does, it is equivalent to not having any ancestors (ie, the above case).


===How are controls attached to the model?===

When a control wants to attach itself to a model it calls
<code>nsIModelElementPrivate::AddFormControl(bound node, parent node)</code>.
The model then stores a link to the element in an internal tree structure,
mirroring the DOM structure, but only for XForms Element for that model.


===What happens when instance data changes?===

When instance data changes, the model usually run through an
<code>xforms-recalculate</code>, <code>xforms-revalidate</code>, and
<code>xforms-refresh</code>.

In the ''refresh'' the model will run through each control that is bound to
it, and check if 

# any of its dependencies have changed, and if so make the control re-evaluate its node binding (i.e., ''rebind'') and then refresh itself afterwards.
# its bound node has changed, and if so make the control refresh the value.

If the bound node of the control changes during this (through the rebinding),
then its immediate XForms children (in the DOM) are also forced to rebind.

[[User:Beaufour|Beaufour]] 08:27, 14 Mar 2006 (PST)