XForms Tip: Differentiating Between Submit Errors

With XForms 1.0, it is not possible to differenciate between a submission error due to an invalid form (or with required-but-empty values) and a submission error due to, for example, a network issue, an HTTP 404 error response, etc.

XForms 1.1 is adding many submission-related improvements that will for example allow an XForms page to directly speak the Atom Publishing Protocol, a fully REST-based API.

We will talk more about this support in the future, but already a new event, xforms-submit-serialize allows you to determine at a high-level why a submission has failed. This event is fired just after the instance has passed validation and just before the instance data is serialized.

If you set a control flag upon receiving this event, you can determine, upon receiving an xforms-submit-error event, whether the instance has already passed validation or not. If it has not, the error is a validation error. If it has, then the error has occurred during serialization, actual submission, or as a result of processing the response. Here is how you set the status flag in an instance called submission-status:

<xforms:instance id="submission-status">
    <submission-status xmlns=""/>
</xforms:instance>
<xforms:submission ...>
    <xforms:setvalue ev:event="xforms-submit-serialize"
                     ref="instance('submission-status')">validated</xforms:setvalue>
</xforms:submission>

Now when a submission error occurs, you want to be able to display an appropriate message, here stored in an instance called message. You can do this using the XForms 1.1 conditional action feature by providing the if attribute on the xforms:setvalue action:

<xforms:action ev:event="xforms-submit-error">
    <xforms:setvalue if="not(instance('submission-status') = 'validated')"
      ref="instance('message')">Please check for errors in your form.</xforms:setvalue>
    <xforms:setvalue if="instance('submission-status') = 'validated'"
      ref="instance('message')">Please contact your system administrator.</xforms:setvalue>
    <xforms:setvalue ref="instance('submission-status')"/>
</xforms:action>

Note that XForms 1.1 is still a working draft and its content may change until it is an actual recommendation.