6.6 Node-set Functions

The XForms core function library provides function instance for use when the XForms model contains more than one instance element. Multiple instances in a model are useful in forms that wish to store temporary values that are not submitted. Function instance can be used within binding expressions to address instance nodes from an instance different from the one that contains the current context node but belonging to the same model as the instance containing the current context node.

Function instance takes a string that identifies the instance to address. If it succeeds in locating an instance with attribute id equal to the specified string argument, it returns a node-set containing the root node of that instance . In all other cases, it returns an empty node-set. The effect of returning the root node has a subtle but significant effect on the use of this function within binding expressions, and we illustrate this using the example shown in Figure 6.5 after first detailing the process by which binding expressions are evaluated. In addition, refer to the examples shown in Figure 4.12 where we used function instance to address nodes in the catalog while iterating items in the shopping cart instance.

Figure 6.5 Using instance to address multiple instances in an XForms model.

 <  html   xmlns  ="http://www.w3.org/1999/xhtml">   <  head  >     <  model   xmlns  ="http://www.w3.org/2002/xforms">       <  instance   id  ="i1">         <  root   xmlns  ="">           <  child  >As easy as   3.14159265359</  child  >       </  root  ></  instance  >   </  model  ></  head  >   <  body  >     <  group   xmlns  ="http://www.w3.org/2002/xforms">       <  label  >The three controls shown below all         address node /root/child of instance i1         and display the same message, As easy as       3.14159265359.</  label  >  <!--absolute locator:  first instance-->  <  output   ref  ="/root/child"/>  <!--relative locator default context is root-->  <  output   ref  ="child"/>  <!-- Use instance function -->  <  output   ref  ="instance('i1')/child"/></  group  > </  body  ></  html  > 

6.6.1 Binding Expressions: The Full Story

Throughout this book, we have used relative and absolute XPath locators in binding expressions. To keep the explanation simple, we have glossed over some minor details, but now it's time to reveal the full story.

As explained in Section 2.2, the current context node is key to determining the result of evaluating an XPath expression. When working with an XForms document that contains one or more models, binding expressions use attribute model in determining the model to address; if attribute model is absent, we default to the first model in document order.

Next, the binding expression needs to determine the instance to address. Again, we default to the first instance in the model, as seen in this section. This can be overridden by explicitly naming the instance via a call to function instance .

Finally, we need to determine the context node for XPath locators addressing nodes in this instance; XForms sets the root node of the selected instance as the default context.

Applying these rules to the model shown in Figure 6.5, we see that the three binding expressions shown in that example all address the same node.

/root/child	This uses the first model in document order and the first instance in that model . Since we have an absolute locator, we do not need to locate the context node any further in determining the result of evaluating this expression.
child	The model and instance are determined as before. This is a relative XPath locator, so to evaluate it we need first to establish the current context node. XForms uses the root node of the instance in use, in this case root . Expression child is evaluated with /root as the current context and returns the same node as the absolute XPath locator detailed earlier.
instance('i1')/child	The model is chosen as before. This time the locator uses function instance ; it is called to locate the instance to use. This function call locates element instance having attribute id with value i1 . It returns a node-set containing the root node of this instance, /root . This root node is now used as the context node for evaluating the remainder of the expression. The result is element child .