Asynchronous submissions

For many of your forms the fact that submission is now asynchronous will not require a change, since it was already good practice to not execute code after a send. Take the following example:

<xf:action ev:event="my-event">
  <xf:send submission="sub" />
  <xf:setvalue ref="x" value=". + 1" />
</xf:action>

In previous versions of formsPlayer with synchronous submissions, the setvalue would not be executed until the submission had completed. However, there is no way to know whether the submission was successful or not. In some situations this may be ok, but in others--perhaps a case is toggled so that some search results can be shown--it is not, since if the submission fails there will be nothing to see.

So even with synchronous submission it was better to put the code that comes after the send into an xforms-submit-done handler:

<xf:action ev:event="my-event">
  <xf:send submission="sub" />
</xf:action>

<xf:action ev:observer="sub" ev:event="xforms-submit-done">
  <xf:setvalue ref="x" value=". + 1" />
</xf:action>

Now the setvalue will only take place if the data was correctly returned.

If your code already took this approach then you having nothing to change to take advantage of asynchronous submissions. But if it didn't you may see slightly different behaviour since actions following the send will now occur straight away. So toggling a case in a switch, for example, may not be desirable if the form then sits waiting for data to arrive.

For an example of how to make use of this to show an 'in progress' animation, see The Toggle action in the Introduction to XForms.

Default error messages in submission

To give the author more control over how errors are handled there is now no longer a default error message for a failed submission. This can be confusing to a user if you don't have a handler for xforms-submit-error in your forms. In the past this would have been handled by formsPlayer showing a default message, but since this would often conflict with any message that the form author might have added themselves we decided to remove it. It's therefore a good idea to add something like the following to your forms:

<xf:action ev:observer="sub" ev:event="xforms-submit-error">
  <xf:message level="modal">
    Failed to update the customer details.
  </xf:message>
</xf:action>

Section 3.3.2 The instance Element

If creation of the detached copy of the inline instance data fails due to an XML error, then processing should halt with an xforms-link-exception.

All data relevant to the XPath data model must be preserved during processing and submission, including processing instructions, comment nodes and all whitespace.

Section 4.1 Events overview

The target for the xforms-submit-error event is now the submission object that is in error, rather than the model that contains it.

Section 4.3.2 The xforms-focus Event

Setting focus to a repeating structure sets the focus to the repeat item represented by the repeat index.

Section 4.3.4 The xforms-refresh Event

All UI bindings should be reevaluated as necessary.

If the value of an instance data node was changed, then the node must be marked for dispatching the xforms-value-changed event. A node can be changed by:

• confirmed user input to a form control;
• xforms-recalculate (section 4.3.6);
• setvalue (section 10.1.9) action.

If the xforms-value-changed event is marked for dispatching, then all of the appropriate model item property notification events must also be marked for dispatching (xforms-optional or xforms-required, xforms-readwrite or xforms-readonly, and xforms-enabled or xforms-disabled).

For each form control, each notification event that is marked for dispatching on the bound node must be dispatched (xforms-value-changed, xforms-valid, xforms-invalid, xforms-optional, xforms-required, xforms-readwrite, xforms-readonly, and xforms-enabled, xforms-disabled). The notification events xforms-out-of-range or xforms-in-range must also be dispatched as appropriate. No ordering is specified for the events.

Section 4.3.6 The xforms-recalculate Event

Events are "marked for dispatch" instead of dispatched as they are tested.

Section 4.4.2 The xforms-value-changed Event

This event is now dispatched during xforms-refresh if the bound instance data node has changed.

Section 4.4.3 The xforms-select and xforms-deselect Events

itemset now supports xforms-select and xforms-deselect.

Section 4.4.6 to 4.4.15 The MIP Events

These are now dispatched whenever the instance node changes, not just when the state of the MIP changes. This means it is no longer possible to spot when the transition is made from enabled to disabled, for example, and also means that a form that is using any of these events will now receive more occurrences than it used to.

Section 4.5.1 The xforms-binding-exception Event

This is now also dispatched if the instance attribute on the submission element refers to an instance element that is in a different model to the submission element.

Section 4.6.7 Sequence: Value Change

The event sequence is now slightly different.

Section 6.1.4 The relevant Property

When false, associated form controls (and any children) and group and switch elements (including content) should be made unavailable, removed from the navigation order, and not allowed focus.

Section 7.7.1 The boolean-from-string() Function

This function now returns false() if it receives an invalid value, rather than throwing a compute exception.

Section 7.8.1 The avg() Function

If any of the input nodes evaluate to NaN then the return value is also NaN.

Section 7.8.5 The index() Function

If the argument to the function does not actually identify a repeat element then the function returns NaN.

Section 9.1.1 The group Element

If a group is non-relevant, then the rendering approach used to signify non-relevance is applied to the entire content of the group. This clarification was made because the old wording implied that when a group was non-relevant, its children could still be relevant.

Section 9.3.5 The insert Element

The at attribute used in insert and delete is evaluated in the context created by nodeset.

Sections 10.1.3, .4, .5, .6 and .11 The rebuild, recalculate, revalidate, refresh and reset Elements

The model is now optional and if absent obeys the usual 'first model' rule.

Sections 7.10.2 and 7.10.3 The days-from-date() and seconds-from-dateTime() Functions

These functions now clarify that the return value is normalised to UTC.

Section 11.1 The xforms-submit Event

All selected instance data nodes are checked for validity as if the xforms-revalidate event was being executed, but no notification events are marked for dispatching. Any selected instance data node that is required but empty, or is found to be invalid, stops submission processing after dispatching the xforms-submit-error event.

If the response includes a body of a non-XML media type (i.e. with a content type not matching any of the specifiers in [RFC 3023]), when the value of the replace attribute on element submission is "instance", nothing is replaced and submit processing concludes after dispatching the xforms-submit-error event.

If an instance is replaced, then the rebuild, recalculate, revalidate and refresh operations are performed on the model, but without dispatching events to invoke those four operations.