The control Element

The Control Element

This element embeds one XForm in another.

Common Attributes: Control Common

Special attributes:

resource: Required URL of a resource containing an XForm. This form will be embedded within the invoking form.
ref (also bind): Optional single node binding that indicates a target node to receive values from the embedded form. It may be the same node as that used in the initial attribute below. If absent, no values are accepted from the embedded form; if the embedded form nevertheless tries to return values, the attempt will fail.
initial: Optional single node expression. The value of this node is used to initialise the textually first instance in the embedded form, in the same way as a submission with replace="instance" would work. If absent, no values are passed to the embedded form. [Should this be a nodeset?]

Content: EMPTY

The resource attribute is evaluated. If the resource is not found, or it is not an XForm, an xforms-link-error is dispatched to the control element, and the control element has no effect.

The resource is embedded in the current form at the current textual position.

The initial attribute is evaluated and the node and all its descendants are selected. [Do we select for relevance?]

The textually first instance in the embedded form is replaced by the selected node and descendants, as if by a submission with replace="instance". [if there is no such instance...].

The embedded form is further initialised in the normal way.

If at any time the embedded form processes a return action, its values are used to replace the content of the binding identified by the ref or bind attribute of the control element. The node is replaced in the same way as a submission with replace="instance" targetref="...".

Examples

An embedded control with no initial values, and no result:

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

---today.xhtml:

<output value="now()"/>

An embedded control with initial values and no result:

<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" initial="before" label="Before"/>
<control resource="histogram.xhtml" initial="after"  label="After"/>

An embedded control with a result but no initial values:

<instance>
   <data xmlns="">
      <testfile>test.xml</testfile>
   </data>
</instance>
<instance id="results"/>
 ...
<control ref="instance('results')" resource="{testfile}"/>

---In test.xml

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

An embedded control with both initial values and result:

<instance id="values">
   <data xmlns="">
      <a>1</a>
      <b>2</b>
      <sum/>
   </data>
</instance>
 ...
<control ref="instance('values')" resource="add.xhtml" initial="instance('values')"/>
<output ref="sum"/>

---In add.xhtml:

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

An embedded control with both initial values and result:

<instance>
   <locations xmlns="">
      <here x="3498234" y="8734503"/>
      <home x="" y=""/>
      <dest x="" y=""/>
   </locations>
</instance> ...

<control ref="home" resource="map.xf" initial="here" label="Please locate your home location"/>
<control ref="dest" resource="map.xf" initial="here" label="Please locate your destination"/>

A series of embedded controls with both initial values and results:

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

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

---in the subform

<model>
   <instance>
      <tests xmlns=""/>
   </instance>
   <instance id="result">
      <result xmlns="">
         <percent/>
      </result>
   </instance>
   ...
   <return ref="instance('result')"/>
</model>

Selecting a control to embed:

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

The renew Element

This action causes the initial values of an embedded form to be re-initialised, possibly with new values.

Attributes: Common

Special attributes:

control: Required ID of a control element.

Examples

<instance id="start">
   <data xmlns="">
      <attempt>1</attempt>
      <score>0</score>
   </data>
</instance>
 ...
<control id="game" resource="game.xml" initial="instance('start')"/>
<trigger label="restart">
   <action ev:event="DOMActivate">
      <setvalue ref="attempt" value=". + 1"/>
      <setvalue ref="score" value="0"/>
      <renew control="game"/>
   </action>
</trigger>

The signal element

This action dispatches an event to or from an embedded control.

Attributes: Common

Special attributes:

name: Required string, the name of an event to be dispatched.
control: Optional ID of a control element.

[Note: No delay, targetid, bubbles or cancelable attributes.]

Content: property*

An event is created with its name set to the value of the name attribute.

If the signal element has any property child elements, the event context is updated with their values.

If the control attribute is present, that control element is identified, and the event is dispatched to the textually first model element of the form embedded by the control element, if any.

If the control attribute is absent, the event is dispatched to the control element that caused this form to be embedded. If the current form is not embedded in another, then the action has no effect.

Examples

Sending an event to an embedded control:

<control id="game" resource="game.xml" initial="instance('start')"/>
<trigger label="restart">
   <action ev:event="DOMActivate">
      <signal control="game" name="restart"/> 
   </action>
</trigger>

Sending an event to an embedding form:

<control resource="calculate.xml" initial="instance('values')">
   <action ev:event="finished">
      <setvalue ref="done">true</setvalue>
   </action>
</control>
---calculate.xml
<signal name="finished"/>

The return Element

This action returns values from an embedded form.

Common Attributes: Common, Events, Action Common

Special attributes

nonrelevant: Optional string indicating whether non-relevant values are included in the returned data. Values are "keep": all values are returned, "remove": non-relevant values are not returned, "empty": non-relevant nodes are returned as empty values. The default is "remove".

If the current form has not been embedded in another, or the control command invoking this form has not supplied a receiving binding, then an xforms-action-error event with an error-type of return-error is dispatched to the return element.

Otherwise, an update is done if necessary, and the binding attributes evaluated to give a nodeset, which is filtered for relevance according to the nonrelevant attribute as for a submission, and returned to the embedding XForm, where it is used to replace the node specified in the binding attribute of the control element in that form, as if by a submission with replace="instance" targetref="...".

Examples

<return ref="instance('result')"/>
<return ref="value[@selected=true()]"/>
<return ref="address" nonrelevant="keep"/>