Views
XForms Actions
From PicoForms
Web forms usually have actions performed on them, such as submission of the form or sending notification when there is error in submission. The action can be triggered by the user, such as clicking a button to save the form, or it can be an automated action that doesn’t require the user to trigger it, such as submitting data to server after a certain period. These actions can be created with XForms Actions.
During a form processing, certain actions are needed to occur. XForms actions are invoked by the XForms events in the form.
XForms Actions are XML elements that represent the functions which, if used in event handlers, will change the instance data or the user interface. XForms Actions are declarative XML event handlers and high levels of semantics are captured by it.
Several elements, which specify declarative actions such as setting focus (setfocus), changing a data value (setvalue) and message are defined by XForms.
Sometimes, it is more convenient to add another declarative action than to write script. In such cases, a new element can be used as an XForms Action.
Contents |
[edit] Event and Action
The events in a form trigger XForms actions. XML events are enabled by XForms specification to respond to various events and invoke action. The type of event actually triggered by an event is determined by XForms action.
The point where the main action occurs is represented by a target element which every event has. Each event may also have a default action that the event triggers effectively. For example, an xforms-focus event will have a form control element as a target and a default action of changing the active focus.
A method is available in Document Object Model (DOM) Level 2 for configuring an observer which can respond to an event and take a specific action, perhaps as an alternative to the default action. Attaching the observer directly to the target element is the most common case.
[edit] The <action> tag
XFoprms actions are defined by the < xforms:action > tag.
The <action> tag is an XML event handler. A set of declarative XML handlers controlling most of the standard use cases populate this tag and eliminate the necessity of using complex scripts.
[edit] The Xforms Actions
While processing a form, some particular action needs to occur.
In the following table the Xforms Actions are listed along with the functions performed by them.
| XForms Actions | Description |
| setvalue | Sets the value of a particular node. |
| setfocus | Gives focus to a particular form control. |
| message | Displays a message to the user. |
| send | Submits all or part of the instance data. |
| reset | Resets all or part of the instance data. |
| refresh | Refreshes the view of the instance data. |
| load | Opens a document in the same or a new window. |
| recalculate | Recalculates the instance data. |
| revalidate | Revalidates the instance data. |
| setindex | Navigates through a repeating sequence. |
| delete | Removes a node from a repeating sequence. |
| insert | Inserts a node from a repeating sequence. |
| toggle | Selects a case of a switch |
| dispatch | Dispatch an event. |
[edit] setvalue
The setvalue element explicitly sets the value of a particular instance data node in the form. The location in the instance data from where the value is received is selected by the binding attribute on this element. The value of an attribute node or an element's text node can be set by the <setvalue> action, and the value can be set either to a fixed value or to the result of evaluating XPath. The value that this action sets in the instance data can either be an XPath expression the value attribute contains, or text as the content of the element. However, if both value and text are present in the element, the evaluated XPath is used. It must be noted that the value is always simpleContent.
Example:
<setvalue> with Expression
<setvalue bind="put-here" value="xyz"/>
Here, the string value at xyz in the instance data is caused to be placed on the single node by the setvalue element, the node being selected by the bind element with id="put-here".
<setvalue> with Text
<setvalue bind="put-here">Text</setValue>
Here, the value “Text” in the instance data is caused to be placed on the single node by the setvalue element, the node being selected by the bind element with id="put-here".
In the example for <setvalue> with Text we can see that the element content of the action specifies the literal value (Text) to set. This is an alternative specifying a computed value via attribute value.
If the setvalue element does not have either of a value attribute or text content, then the value of the selected node is set to the empty string (""). This is also equivalent to clearing a value which is specified by setting a zero-length string where neither a value attribute nor element content is present.
[edit] setfocus
The <setfocus> action explicitly sets focus to a particular form control.
The form control is identified by the IDREF attribute control and the setvalue action dispatches an xforms:focus event to the form control.
It should be noted that the xforms:focus event is implicitly invoked for implementing XForms accessibility features such as the accesskey.
The setfocus action can be used as follows:
<setfocus control="Item Name" ev:event="xforms-ready"/>
The focus is redirected to a different form control in the form by the setvalue action. If there is form control that logically needs to be filled in first, this action becomes useful to the user. The usability of a form improves considerably when the necessity of a mouse click is avoided.
Suppose a form requires the “Item Name” to be entered and the author wants to have the focus on an xforms:input form control for the purpose, the code for the form control will be:
<xforms:input id=”itemname”/>
The author can use the xforms:setfocus action as:
<xforms:setfocus idref-“itemname”/>
If we set focus to a repeating structure, focus will be set to the member which the repeat cursor represents.
[edit] message
The <xforms:message> action displays a message to the user, typically in a dialogue box. This action provides a wonderful option to make the form interactive by providing additional information to the user (in the form of hint and help) and enhance user experience with the form.
The content of the message element is typically the message to be displayed to the user. The message content can come from the instance data (the binding attributes) defined by ref or bind, from an external source file (the linking attribute) defined by src or it can exist as inline text. However, only a single source can be used at a time. When there is more than one source specified in the message element to render the message content, a particular order of preference, as provided below, is followed.
Binding attributes (ref) > Linking attributes (xlink:href) > Inline Text
Depending on the type of intrusiveness we want to create with the message, there are three types of message that can be displayed with the message action.
Modal message
The modal message provides the most intrusive message display where the user can proceed only after closing the message dialogue box.
Example
The following example shows message action that instructs a graphical browser to render a modal message as “This field is mandatory”
<model> <message level="modal" ev:event="xforms-ready">This field is mandatory</message> ... </model>
Modeless message
The modeless message is less intrusive compared to modal message. It is moderate visual-centric and keeps the rest of the form out of its interference, though the message remains displayed until it is dismissed. Modeless messages are used to display help messages to user.
Example
The following example shows message action that instructs a graphical browser to render a modeless message to offer help to the user while login.
<secret ref="/login/username"> <label>User Name</label> <help>Your login id is the Relationship Number assigned to you</help> </secret>
Ephemeral message
The ephemeral message is least intrusive among all the messages and it is the friendliest to the user. These are fleeting messages and go away themselves after being displayed for certain periods. Ephemeral messages are displayed as brief status bar or tool tip. Ephemeral messages are used to display hint messages to user when the cursor is taken on a form control.
Example
A message action instructing a graphical browser to render an ephemeral message that provides a hint to the user is given below:
<input ref="itemname/brand/itemcode"> <label>Item Code</label> <hint>Please enter the Item Code correctly</hint> </input>
It should be noted that the <xforms:message> element must have a level attribute with either of the values “modal”, “modeless” or “ephemeral”. At present the only value supported for the level attribute is modal. When a value is provided for a linking attribute defined by src, the value must be an absolute URL that starts with oxf:, http: or other supported protocols.
[edit] send
The <xforms:send> submits a form by invoking submission of a form. All the instance data or a part of it can be submitted by the send action.
The <xforms:send> action dispatches an xforms-submit event to initiate the submission process. Thus, the effect of the send action is the same as that of dispatching an xforms-submit event to the submission element.
Details of what and how to submit are contained by a submission element which is held by an IDREF, and a submission attribute holds the IDREF.
The <xforms:send> action can be used as follows:
<xforms:action event>
<xforms:send submission="submission"/>
</xforms:action>
Note that the send action has no effect if the submission attribute is present but does not identify a submission element. If the submission attribute is excluded, then the submission element coming first in the document order from the model that is related to the in-scope evaluation context will be used.
