XFDL references to elementsAdded by IBM on October 10, 2012 | Version 1 (Original)
The simple character content of options and suboptions are obtained as the operands of XFDL compute expressions using XFDL references. XFDL references support forward and backward referencing. An XFDL reference can refer to any option or array element with simple character content.
The element containing the desired character content is identified using scope identifiers to negotiate a path through the parse tree. To traverse through the page and item levels and identify an option, the well-known 'dot' membership operator is used. The well-known square-bracket array notation can then be used to access suboptions to arbitrary element depth. For example, Page2.Field2.value would access the option with tag name <value> in the <field> element having a sid of Field2 in the <page> having a sid of Page2.
Because each XFDL element's scope identifier (sid) is used to uniquely identify an element only within the surrounding parent element, XFDL can support relative referencing. For example, in an element identified as Field1, if a computation includes the reference Field2.value, this means that the character data of the value option in the item Field2 on the same page will be obtained. If Field2 is on a separate page, say Page2, then a compute in Field1 can still access its value using the fully-qualified reference Page2.Field2.value.
The context for interpreting a reference is also decided based on the form of the reference itself in combination with its location in the form. For example, in the XFDL below, the reference Bill.value appears in a compute that is attached to a grand-child suboption of the format option. However, the name after the rightmost 'dot' operator always refers to an option, and the name before the rightmost dot always refers to an item. Since the page is not specified, it is determined to be the page containing the reference.
XFDL references can also grow arbitrarily below the option level using the array notation, allowing access to unbounded array element depth within any option. If an array element is not named, then the zero-based numeric position of the array element is used in the square brackets. If the array element is named, then the scope identifier can be used in the square brackets. For example, given the format option of the XFDL above, the reference format yields dollar and the reference format[range] yields 700. If a suboption is named, the numeric position can still be used, e.g. format also yields 700.
The above description covers static references. The XFDL referencing model also supports dynamic references. The left associative 'arrow' operator (->), also known as the indirect membership operator, expects to receive a static or dynamic reference as a left operand. The run-time value of the static or dynamic reference must conform to the syntax of the ItemRef non-terminal. The right operand of the indirect membership operator is an option reference. At run-time, the left operand is evaluated, yielding a static item reference to an XML element representing an XFDL item. This run-time item reference is combined with the right operand of the indirect membership operator to yield an option or array element whose simple data is the result of the evaluation.
The simplest example of a dynamic reference is retrieving the text of the selected cell in an XFDL list box or popup, as is discussed in Items, because the value option of a list or popup is equal to the item reference of the selected cell item. Thus, given an example popup that offers a selection of days of the week, the text for the day of week selected by the user is obtained by Popup_DayOfWeek.value->value.
An option reference can simply refer to element tag names in the XFDL namespace without any namespace qualification. A namespace qualified scope identifier (the non-terminal NSsid below) must be used if the element being referenced is not in the XFDL namespace. In order to reference element in the empty namespace, XFDL supports the predeclared prefix null. For example, to reference an element E which has an empty namespace URI, use the reference null:E.
Below are the syntax rules for an XFDL reference. Note that unlike most other syntax rules for XFDL expressions, intervening white space is not allowed in an XFDL reference. An XFDL reference is treated as a single lexical token.
<page sid= "CreditCardApp">
<label>Your monthly bill is:</label>
<label>Enter payment amount:</label>
<min compute="Bill.value * '0.05'">35</min>
XFDLReference ::= StaticRef | StaticRef '->' DynamicRef
StaticRef ::= ItemRef '.' OptionRef | OptionRef
ItemRef ::= ((sid '.')? sid '.')? sid
DynamicRef ::= DynamicRef '->' OptionRef | OptionRef
OptionRef ::= NSsid (' [' (Digit+ | NSsid) ']')*
NSsid ::= sid | (Letter (Letter | Digit | '_')*) ':' sid