The Control Element

This control embeds an XForm in the current one, optionally sharing data between the two, and optionally allowing communication via events.

Common Attributes: Control Common

Special attributes:

resource: Required URI of a resource containing an XForm to be embedded within the invoking XForm.

The resource attribute is evaluated:

If the resulting resource is not found, or it is not an XForm, an xforms-link-error is dispatched to the control element, and the element has no further effect;
otherwise the resource is embedded in the current form at the current textual position, and is initialised and processed.

If the control element has a binding:

it must evaluate to a single element, and the embedded XForm must have a shared element with a binding that evaluates to a single element, otherwise an xforms-binding-error is dispatched to the control element.

If the control element does not have a binding:

the embedded XForm must either contain no shared element, or one without a binding, otherwise an xforms-binding-error is dispatched to the control element.

Communication with the Embedded XForm

If the embedded XForm contains a shared element, the embedded XForm is initialised with additional effect from that element, and data is shared between the two forms, as described in that section.

The shared element also permits communication with events using the signal action.

If the embedded XForm contains no shared element, there is no communication between the two; the embedded XForm is freestanding and is processed in the normal way.

Examples

<control resource="game.xhtml"/>
<control resource="process.xf" ref="data"/>
<control resource="{choice}" bind="values">
    <toggle ev:event="finished" case="closed"/>
</control>

The Shared Element

Specifies the data to be shared by this XForm when embedded with a control element in another XForm, and allows communication with events between the two.

Common Attributes: Common?

Special attributes:

initial local|external [not AVT] Optional attribute specifying how the shared data is to be initialized. The default is local.

If this XForm is not embedded in another, this element has no effect.

If it is embedded, this element specifies which data element if any is to be shared and synchronised with the embedding XForm, and provides a communication point for use with the signal action.

If the shared element has a binding:

it is evaluated, and must evaluate to a single element, and the control element that caused the current XForm to be embedded must also have a binding that similarly evaluates to a single element, otherwise an xforms-binding-error is dispatched to the shared element..
If the shared element has an initial attribute that evaluates to external, the attributes and content of the referenced element in the embedding XForm replaces those of the referenced element in the embedded XForm,
otherwise, the attributes and content of the referenced element in the embedded XForm replaces those of the referenced element in the embedding XForm.
After initialisation, the referenced elements are kept synchronised: a change in one is reflected in a change in the other.

If the shared element does not have a binding, the control element used to embed the current XForm must not have a binding and no data is shared.

Examples

<shared/>

No data is shared; communication is possible via events.

<shared ref="data"/>
<shared bind="sharing"/>
<shared ref="collection/a" initial="external"/>
<shared>
   <action ev:event="restart">
      <setvalue ref="score">0</setvalue>
   </action>
</shared>

The Signal Action

Common Attributes: Control Common

Special attributes:

name: Required string giving the name of an event to be dispatched.

control: Optional IDREF identifying a control element

delay: Optional number giving the minimum number of milliseconds to delay dispatching the event. The default is no delay.

bubbles: Optional boolean indicating if this event bubbles — as defined in [DOM2 Events]. The default value is true for a custom event. For predefined events, this attribute has no effect.

cancelable: Optional boolean indicating if this event is cancelable — as defined in [DOM2 Events]. The default value is true for a custom event. For predefined events, this attribute has no effect.

Content: property*

Processing imitates that of the dispatch action.

If the element has a control attribute:

if the attribute's IDREF does not indentify a control element, an xforms-action-error event with an error-type of signal-control is dispatched to the signal element
otherwise, if the XForm embedded by the identified control has no shared element, this action has no further effect
otherwise, the specified event is dispatched to the shared element of the XForm embedded by the identified control element.

If the element has no control attribute:

If this XForm is not embedded, this element has no further effect
otherwise, the specified event is dispatched to the control element that caused this XForm to be embedded.

Examples

<signal name="ready"/>
<signal if="count = 0" name="finished"/>
<signal control="game" name="restart"/>

Fuller Examples

<control resource="today.xhtml" label="Today's date:"/>

In today.xhtml:

<output value="now()"/>

<select1 ref="game" label="select a game to play">
   <item label="minesweeper">minesweeper.xml</item>
   <item label="slider">slider.xml</item>
   <item label="noughts and crosses">xox.xml</item>
</select1>
<control resource="{game}"/>

<instance>
   <data xmlns="">
      <before>
         <y>9</y><y>15</y><y>11</y><y>6</y><y>5</y><y>10</y><y>8</y>
      </before>
      <after>
         <y>8</y><y>3</y><y>12</y><y>14</y><y>9</y><y>16</y><y>14</y>
      </after>
   </data>
</instance>
 ...
<control resource="histogram.xhtml" ref="before" label="Before"/>
<control resource="histogram.xhtml" ref="after" label="After"/>

In histogram.html:

<instance>
   <histogram xmlns="">
      <data/>
      <height/>
      <width/>
   </histogram>
</instance>
<shared ref="data" initial="external"/>

<repeat ref="data/*">...

<instance>
   <data xmlns="">
      <testfile>test.xml</testfile>
   </data>
</instance>
<instance id="results">
   <results xmlns=""/>
</instance>
 ...
<control ref="instance('results')" resource="{testfile}">
   <action ev:event="started">...</action>
   <action ev:event="finished">...</action>
</control>

In test.xml:

<instance>
   <data xmlns="">
      <values>...</values>
      <results>
         <percent/>
         <success/>
         <failure/>
      </results>
   </data>
</instance>

<shared ref="results"/>
<signal ev:event="xforms-ready" name="started"/>
 ...
<trigger label="Done">
   <signal ev:event="DOMActivate" name="finished"/>
</trigger>

<instance id="values">
   <data xmlns="">
      <v>1</v>
      <v>2</v>
      <v>3</v>
      <sum/>
   </data>
</instance>
 ...
<control ref="instance('values')" resource="add.xhtml"/>

<output ref="sum"/>

In add.xhtml:

<instance>
   <values xmlns=""/>
</instance>
<bind ref="sum" calculate="sum(../v)"/>

<shared ref="/values" initial="external"/>

<instance>
   <locations xmlns="">
      <home><x/><y/></home>
      <dest><x/><y/></dest>
   </locations>
</instance>
<control ref="home" resource="map.xf" label="Please locate your home
location"/>
<control ref="dest" resource="map.xf" label="Please locate your
destination"/>

<instance>
   <data xmlns="">
      <location/>
   </data>
</instance>

<shared ref="location"/>
 ...
{code that uses location/x and location/y}

<instance>
   <testsuite xmlns="">
      <testcase>
         <filename>boolean-from-string.xml</filename>
         <tests>
            <test res="" req="true">1</test>
            <test res="" req="false">0</test>
            <result/>
         </tests>
      </testcase>
      <testcase>
         ...
      </testcase>
   </testsuite>
</instance>

<repeat ref="testcase">
   <control resource="{filename}" ref="tests"/>
</repeat>

In the embedded XForm:

<model>
   <instance>
      <tests xmlns=""/>
   </instance>
   <bind ref="test" calculate="..." />
   <bind ref="result" calculate="..."/>
   <shared ref="tests" initial="external"/>
</model>