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:

1. A context node, which is the node that they are bound to
2. 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 bind, ref, nodeset, value or src.

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

1. The control does not have any XForms controls as ancestors (in the DOM).
   The context node is then the document node of the default instance document of the default model, or the model specificed by the model attribute on the node.
2. The control has an XForms ancestor (in the DOM)
   The context node is then the bound node of the closest ancestor. Unless the control has a model 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 nsIModelElementPrivate::AddFormControl(bound node, parent node). 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 xforms-recalculate, xforms-revalidate, and xforms-refresh.

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

1. 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.
2. 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.

Beaufour 08:27, 14 Mar 2006 (PST)