XForms Actions

8.1 Using XForms Actions

All form controls defined in this specification have a set of common behaviors that encourage consistent authoring and look and feel for XForms-based applications. This consistency comes from attaching a common set of behaviors to the various form controls. In conjunction with the event binding mechanism provided by [XHTML Events], these handlers provide a flexible means for forms authors to specify event processing at appropriate points within the XForms user interface.

Example: Action Syntax

NOTE: This example is based on the XHTML Events specification [XHTML Events], which is proceeding independently from XForms, and thus might be slightly incorrect.

<xform:button>
  <xform:caption>Reset</xform:caption>
  <xform:action evt:event="dom-activate">
    <xform:resetInstance/>
  </xform:action>
</xform:button>

This example recreates the behavior of a "reset" button, which this specification does not define as an independent form control. The same effect can be achived by attaching an XForms Action to a button.

This chapter lists the built-in actions defined, including:

Name
Description of behavior
XML Representation

8.2 dispatch

This action explicitly triggers an

XForms Event defined in 11 Processing Model.

Example: XML Representation: <dispatch>

<dispatch
  id = xsd:ID
  event = xsd:NMTOKEN
  target = xsd:IDREF
/>

id = xsd:ID - optional unique identifier.
event = xsd:NMTOKEN - required name of the event to fire.
target = xsd:IDREF - required reference to the event target.

8.3 refresh

This action explicitly initiates refresh processing, as defined in 11.4.6 UI Refresh Algorithm.

Example: XML Representation: <refresh>

<refresh
  id = xsd:ID
/>

id = xsd:ID - optional unique identifier.

8.4 recalculate

This action explicitly initiates recalculate processing, as defined in 11.4.5 Recalculation Sequence Algorithm.

Example: XML Representation: <recalculate>

<recalculate
  id = xsd:ID
/>

id = xsd:ID - optional unique identifier.

8.5 revalidate

This action explicitly initiates revalidate processing, as defined in 11.4.7 Revalidation Algorithm.

Example: XML Representation: <revalidate>

<revalidate
  id = xsd:ID
/>

id = xsd:ID - optional unique identifier.

8.6 setFocus

This action explicitly sets focus to the form control referenced by the idref attribute. Note that this action is implicitly invoked to implement XForms accessibility features such as accesskey.

Editorial note
Do we need a better way to specify an individual form control?

Example: XML Representation: <setFocus>

<setFocus
  id = xsd:ID
  idref = xsd:IDREF
/>

id = xsd:ID - optional unique identifier.
idref = xsd:IDREF - required reference to a form control

8.7 setValue

This action explicitly sets the value of the indicated instance data node.

Example: XML Representation: <setValue>

<setValue
  (single node binding attributes)
  value = xsd:string
/>

id = xsd:ID - optional unique identifier.
(single node binding attributes) - Selection of instance data node, defined at 7.14.2 Single Node Binding Attributes
value = xsd:string - new value to set

8.8 submitInstance

This action explicitly initates submit processing, as defined in 11.5.1 Submit.

Example: XML Representation: <submitInstance>

<submitInstance
  id = xsd:ID
  (nodeset binding attributes)
  withResponse = "replace" : "replace"
/>

id = xsd:ID - optional unique identifier.
(nodeset binding attributes) - Selection of instance data for submit, defined at 7.14.3 Nodeset Binding Attributes
withResponse = "replace" : "replace" - what to do with the response. Default is XHTML behavior where response document replaces the current document.

8.9 resetInstance

This action explicitly initiates reset processing, as defined in 11.5.2 Reset.

Example: XML Representation: <resetInstance>

<resetInstance
  id = xsd:ID
  (nodeset binding attributes)
/>

id = xsd:ID - optional unique identifier.
(nodeset binding attributes) - Selection of instance data for reset, defined at 7.14.3 Nodeset Binding Attributes

8.10 insert

This action inserts new nodes into editable lists e.g., within 9.3 Repeating Structures. This causes the instantiation of the necessary user interface for populating a new entry in the underlying collection. It also updates the instance data by instantiating the necessary nodes. Finally, the binding expression associated with this repeat is re-evaluated to update the node-set over which this repeat operates.

Example: XML Representation:Action <insert>

<insert
  id = xsd:ID
  repeat= xsd:IDREF
/>

id = xsd:ID - optional unique identifier.
idref = xsd:IDREF - required reference to a repeat

8.11 delete

This action deletes nodes from editable lists e.g., within 9.3 Repeating Structures. This causes the destruction of the necessary user interface for populating the entry at the current cursor position in the underlying collection. It also updates the instance data by destroying the necessary nodes. Finally, the binding expression associated with this repeat is re-evaluated to update the node-set over which this repeat operates.

Example: XML Representation:Action <delete>

<delete
  id = xsd:ID
  repeat= xsd:IDREF
/>

id = xsd:ID - optional unique identifier.
idref = xsd:IDREF - required reference to a repeat

8.12 scroll

This action changes the current item in an editable list e.g., within 9.3 Repeating Structures.

Example: XML Representation:Action <scroll>

<scroll
  id = xsd:ID
  repeat= xsd:IDREF
  step = xsd:integer
/>

id = xsd:ID - optional unique identifier.
repeat = xsd:IDREF - required reference to a repeat
step = xsd:integer - specifies the amount by which the list is scrolled. Negative values may be used to scroll the list in the reverse direction.

Issue (additional-actions):

We may add special values for scrolling to the top or bottom of the list, as well as other needed actions.

8.13 setRepeatCursor

This action marks an item as current in an editable list e.g., within 9.3 Repeating Structures.

Example: XML Representation:Action <setRepeatCursor>

<setRepeatCursor
  id = xsd:ID
  repeat = xsd:IDREF
  cursor = binding-expression
/>

id = xsd:ID - optional unique identifier.
repeat = xsd:IDREF - required reference to a repeat
cursor = binding-expression - binding expression that evaluates to an element of the node set being iterated over by this repeat construct.

Platform-specific user actions for selecting e.g., mouse focus, implicitly invoke handler setRepeatCursor on the item that got the selection.

8.14 toggle

This action selects one possible choice from an exclusive list e.g., within 9.2 Conditional Constructs For Dynamic User Interfaces.

Example: XML Representation: Action <toggle>

<toggle
  id = xsd:ID
  switch = xsd:IDREF
  case = xsd:IDREF
/>

id = xsd:ID - optional unique identifier.
switch = xsd:IDREF - required reference to a conditional construct
case = xsd:IDREF - required reference to a case section inside the conditional construct

8.15 script

Example: XML Representation: Action <script>

<script
  id = xsd:ID
  language = xsd:NMTOKEN
/>

id = xsd:ID - optional unique identifier.
language = xsd:NMTOKEN - optional identifier of scripting language used


Table of Contents	Prev	Next	Bottom

8 XForms Actions

8.1 Using XForms Actions

8.2 dispatch

8.3 refresh

8.4 recalculate

8.5 revalidate

8.6 setFocus

8.7 setValue

8.8 submitInstance

8.9 resetInstance

8.10 insert

8.11 delete

8.12 scroll

8.13 setRepeatCursor

8.14 toggle

8.15 script