This element embeds an XForm in another form.
Common Attributes: Control Common
Special attributes:
xforms-return' method in the embedded
form. It may be the same node as that used in the 'initial' attribute
below. If absent, no values are expected from the embedded form; if the
embedded form nevertheless tries to submit return values, the submission
will fail with 'xforms-return'. 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? Probably]
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 initialised in the normal way.
If at any time the embedded form processes a submission with
method="xforms-return", the submission 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="...".
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>
...
<submission ref="results" method="xforms-return"/>
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"/>
<submission method="xforms-return"/>
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>
...
<submission ref="instance('result')" method="xforms-return"/>
</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}"/>
This action causes the initial values of an embedded form to be re-initialised, possibly with new values.
Attributes: Common
Special attributes:
control element. <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>
This action dispatches an event to or from an embedded control.
Attributes: Common
Special attributes:
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.
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"/>
With this method, the resource attribute of the
submission element is ignored. If the submitting form has not been
embedded in another, or the embedding form has not supplied a receiving binding
for submission results, submission fails with return-error.
Otherwise, the form data is returned to the embedding XForm, and is used to
replace the node specified in the ref or bind
attribute of the control element in that form, as if by a
submission with replace="instance" targetref="...".
<submission ref="instance('result')" method="xforms-return"/>