9.1 Grouping Form Controls

The group element is used as a container for defining a hierarchy of form controls. Groups can be nested to create complex hierarchies.

<group
  (single node binding attributes)
  (common attributes)
>
  <!--  ((any form control) | group | repeat | component | switch )* -->
</group>

In CSS-based layout systems, groups lay out their children using a constraint-based system that supports both relative flexible sizing and intrinsic sizing. Through CSS, an inline box can be specified using the display property with a value of inline. A block-level group can be specified with a value of block, which is the default.

The hierarchy defined by nested group elements is used to determine the traversal order specified by attribute navIndex on form controls. Setting the input focus on a group results in the focus being set to the lowest form control in the tabbing order within that group.

9.2 Conditional Constructs For Dynamic User Interfaces

The XForms User Interface allows the authoring of dynamic user interfaces, i.e., user interfaces that vary based on the current state of the instance data being populated. As an example, portions of a questionnaire pertaining to the user's automobile may become relevant only if the user has answered in the affirmative to the question 'Do you own a car?'. Another use case for such dynamic user interfaces is when the underlying XForms Model contains conditional structures.

This element contains one or more case elements. Each case has an id attribute that is used within event handlers appearing within form controls to activate or deactivate that portion of the user interface created by the markup contained within that case element.

<switch id="sw">
 <case id="in">
  <input ref="yourname">
   <caption>Please tell me your name</caption>
  </input>
 </case>
 <case id="out">
  <html:p>Hello <output ref="yourname" />.</html:p>
 </case>
</switch>

<switch
  (single node binding attributes)
  (common attributes)
  default = xsd:IDREF
>
  <!-- case+ -->
</switch>

<case
  id = xsd:ID
>
  <!--  ##any -->
</case>

9.3 Repeating Structures

The XForms Model allows the definition of repeating structures such as multiple items being purchased within a purchase order. When defining the XForms Model, such higher-level aggregations are constructed out of basic building blocks; similarly, here are defined higher-level user interface constructs that build on the form controls defined previously that can bind to data structures such as lists and collections.

Element repeat represents a UI mappings over homogenous collection, in other words, a collection consisting entirely of like form controls.

<repeat nodeset="/cart/items/item">
  <input ref="." .../><html:br/>
</repeat>

Note that controls for adding or removing repeating entries may appear within the repeat, (causing the add/remove controls themselves to repeat), or may appear outside the repeat.

Another way to view the repeat processing (modulo special user interface interactions) is to consider "unrolling" the repeat. The above example is similar to the following (assuming four item elements in the returned node-set):

<!-- unrolled repeat -->
<input ref="/cart/items/item[1]" .../><html:br/>
<input ref="/cart/items/item[2]" .../><html:br/>
<input ref="/cart/items/item[3]" .../><html:br/>
<input ref="/cart/items/item[4]" .../><html:br/>

Notice that the model item for the collection being populated would typically have defined attributes minOccurs and maxOccurs; these values will in turn determine if the user agent displays appropriate UI controls for the user to add or delete entries in the collection. Event listeners separately control UI aspects such as scrolling and insertion. This specification does not specify normative means for displaying such add and delete controls; as with the rest of the XForms User Interface design, these are left to be flexible while showing a default presentation.

<repeat
  (nodeset binding attributes)
  (common attributes)
  startIndex = xsd:positiveInteger : 1
  number = xsd:nonNegativeInteger
>
  <!-- ##any -->
</repeat>

9.4 Dynamic Selection Choices

XForms defines list controls selectOne and selectMany. By default, these follow the standard form control behavior of representing their state as a Schema simpleType that is associated with an instance data node--often a derived-by-list datatype. Often, a more convenient representation for lists is using markup instead of whitespace to separate list items. This section explains additional XForms processing to handle this common case.

Notice that this usage matches the case of selection controls selectOne and selectMany where the user is allowed to select from a set of dynamic choices, i.e., where the list of choices is determined at run-time as opposed to authoring time. As a consequence, this working draft proposes the construct repeat as the means to represent dynamic choices for controls selectOne and selectMany.

In this case, binding attribute nodeset on element repeat specifies the location in the instance that contains the dynamically determined set of choices. The contained form controls within element repeat specify the user interface for one element from the dynamic list as before. Semantics of the repeat cursor are as defined earlier.

<selectOne ref="/trip/reservation/flight">
  <caption>Available Flights</caption>
  <help>Displaying list of available flights matching your
        requirements, please pick one.</help>
  <!-- /trip/available/flights is populated by a sequence of -->
  <!-- <flight> elements  at run time-->
  <repeat nodeset="/trip/availableFlights/flight">
     <!--itemrefs that point to <flight> nodes -->
  </repeat>
</selectOne>

In the above, the user is able to select a flight from a dynamically created list of available flights. The user interface template encapsulated within the body of element repeat is used in creating a choice item for each flight element found in /trip/availableFlights.

9.5 Reusable Form Controls

User Interface templates allow the creation of reusable user interface components. Just as authors can define data types and structures that can be reused within the XForms Model, reusable user interface components allow us to design complex user interfaces using the basic building blocks described in the previous section, and then reuse these components in multiple situations. As with any component framework, this has two basic requirements:

• Components need to declare what aspects of the component are parameterizable by the caller.

• The caller needs to be able to override the default values of the parameters declared in the component.

This section describes such a component framework along with sample markup. This component mechanism has some similarities with the user interface used within the body of element repeat to provide the user interface for a generic element of the nodeset operated on by element repeat. Those templates can be thought of as anonymous components. This consists of:

1. XForms user interface construct defComponent defined next corresponds to creating re-usable data types.

2. Using XForms user interface construct component to instantiate reusable components declared using defComponent corresponds to creating data instances corresponding to a reusable user defined data type.

this example, assume that USShippingAddress is a reusable data type that is used in multiple places in the XForms Model, e.g. the user will be asked for a billingAddress and shippingAddress--both of type USShippingAddress.

The following shows a simple example that is designed to bind an XForms form control to a model item of type address with no attention to making the component reusable.

<group ref="address">
  <input ref="street">
    <caption>Please enter your street address</caption>
  </input>
  <input ref="zip">
    <caption>Zip Code</caption>
  </input>
</group>

Next, consider the above fragment modified to become a reusable component that could be used for obtaining both the shipping and billing address. To do this, those portions of the component that the caller will wish to modify need to be parameterized.

<defComponent id="AddressWidget">
  <param name="streetPrompt"/>
  <param name="zipPrompt"/>
  <group ref="address">
    <input ref="street">
      <caption><valueOf select="$streetPrompt"/></caption>
    </input>
    <input ref="zip">
      <caption><valueOf select="$zipPrompt"/></caption>
    </input>
  </group>
</defComponent>

Note that the markup shown above does not create a user interface; user interface is created by explicitly instantiating the component via element component described next.

With this, the component can be instantiate in the user interface for obtaining the shipping and billing address:

<component ref="myAddress" component="AddressWidget">
  <param name="streetPrompt" value="Shipping Street Address"/>
  <param name="zipPrompt" value="Zip Code for shipping state"/>
</component>

The reusable component is instantiated by element component; parameter values are specified by the contained param elements.

<defComponent
  id = xsd:ID
>
  <!--  param*, ((any form control) | group | repeat | component | switch )* -->
</defComponent>

<param
  id = xsd:ID
  name = xsd:NMTOKEN
  value = xsd:string
>
  <!--  ##empty -->
</param>

<valueOf
  id = xsd:ID
  select = xsd:string
>
  <!--  ##empty -->
</valueOf>

<component
  (single node binding attributes)
  (common attributes)
  component = xsd:IDREF
>
  <!-- param* -->
</component>