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.