Registering for Events

It's extremely important in both Ajax and desktop applications to know how the submission of data is progressing. In XForms, information is provided to us both when the submission begins, and again when it ends.

The way in which all notifications happen in XForms is via events. A process will dispatch an event to any listener that registered for it, and this will in turn execute whatever actions have been marked up.

In the example we've been looking at we want to register to be notified if ever the xforms-submit-error event occurs on the submission labelled sub-add-link. The action we want to execute when this event does occur is to show a message. That may all sound very complicated, but in fact the mark-up to do this is as straightforward as adding the message handler as a child of the submission element:

    <xf:submission id="sub-add-link"
       action="http://del.icio.us/api/posts/add" method="get"
    >
      <xf:message level="modal" ev:event="xforms-submit-error">
        Please ensure that you have entered both a
        URL <em>and</em> a title.
      </xf:message>
    </xf:submission>

Making the message action a child of submission ensures that we are registered on the correct element, but we still need to say what event we are registered for, since there are many possible notifications. That's the purpose of the ev:event attribute, which specifies the event we're interested in--in this case xforms-submit-error.

One more thing to complete the mark-up is that ev:event is actually from a different language to XForms. We therefore need to ensure that the namespace for this language is at the top of our document:

<html
 xmlns="http://www.w3.org/1999/xhtml"
 xmlns:ev="http://www.w3.org/2001/xml-events"
 xmlns:xf="http://www.w3.org/2002/xforms"
>
  .
  .
  .

Update your form to include this namespace definition and the changes to the submission element described above, and then reload. Now if you try to post to del.icio.us without any values in the URL or Description fields you should get something like this:

Screenshot of the error message telling the user that they need to provide the required fields