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...}

If the control element does not have a binding:

the embedded XForm must either contain no shared element, or one without a binding. {otherwise...}

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"/>

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 {otherwise?}; the <control/> element used to embed the current XForm must also have a binding that similarly evaluates to a single element.
If the <shared/> element has an initial attribute that evaluates to external, the contents of the element in the embedding XForm replaces the content of the element in the embedded XForm {only children or attributes too?}
otherwise, the contents of the referenced element in the embedded XForm replaces the content 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

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.

{Do we want to add @delay}

{Should we allow <property/> sub elements as with <dispatch/> ?}

{Should we restrict to only user-defined events?}

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 {Error?}
otherwise, the specified event is dispatched to the shared element of the embedded XForm.

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. {Do we require a <shared/> element to be present in this case?}

Examples

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

Fuller Examples

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

In today.xhtml:

<output value="now()"/>

===============================

<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="">
      <a>1</a>
      <b>2</b>
      <sum/>
   </data>
</instance>
 ...
<control ref="instance('values')" resource="add.xhtml"/>

<output ref="sum"/>

In add.xhtml:

<instance>
   <values xmlns=""/>
</instance>
<bind ref="sum" calculate="../a + ../b"/>

<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>

===============================

<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}"/>

===============================