submission with replace="text", and the target attribute

New features are due to be added to the XForms specification, to allow submission to handle incoming non-XML data. A new possible value for the replace attribute--text--prevents a submit-error occurring on receipt of non-XML data, whilst a new attribute--target--contains an XPath expression indicating the node into which response data is to inserted.

Here is an example of how to use the new attributes to insert the content of the file SomeTextFile.txt into the node /x/y in the instance data.

<xf:model>
  <xf:instance id="i0">
    <x>
      <y />
    </x>
  </xf:instance>
  <xf:submission
   method="get" action="SomeTextFile.txt"
   replace="text" target="y"
  />
</xf:model>

Although this has not been fully discussed and decided by the PTB, here is my interpretation of the changes to be made to Section 11: Submit of the XForms spec:

5.

• For a success response including a body of a any 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 "text",
  • If there is no target attribute, nothing in the document is replaced and submit processing concludes after dispatching xforms-submit-error.
  • If a target attribute is specifed, A node from the instance data is selected based on the value of the target attribute, the context for the execution of this XPath expression will be the same as the context for the resolution of the ref attribute. The value of this node will be replaced by the returned text, in accordance with section 10.1.9 setvalue.
• For a success response including a body of an XML media type (as defined by the content type specifiers in [RFC 3023]), when the value of the replace attribute on element submission is "instance", the response is parsed as XML. An xforms-link-exception (4.5.2 The xforms-link-exception Event) occurs if the parse fails. If the parse succeeds, then
  • If there is no target attribute all of the internal instance data of the instance indicated by the instance attribute setting is replaced with the result.
  • If a target attribute is specifed, A node from the instance data is selected based on the value of the target attribute, the context for the execution of this XPath expression will be the same as the context for the resolution of the ref attribute. The parsed xml data is then inserted as a fragment into the selected node.

  Once the XML instance data has been replaced, the rebuild, recalculate, revalidate and refresh operations are performed on the model, without dispatching events to invoke those four operations. Submit processing then concludes after dispatching xforms-submit-done.

• For a success response including 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 in the document is replaced and submit processing concludes after dispatching xforms-submit-error.

More interesting uses can be seen when submitting to a server that supports XPointer queries. Consider the situation where a single value is required from a large XML document; prior to the introduction of this feature, the following unwieldy code would be required:

<xf:model>
  <xf:instance id="iRS">
    <dummy />
  </xf:instance>
  <xf:instance id="i">
    <x>
      <y />
    </x>
  </xf:instance>
  <xf:submission
   method="get" action="AnEnormousXMLFile.xml"
   instance="iRS" replace="instance"
  >
    <setvalue ev:event="xforms-submit-done"
     ref="instance('i')/y"
     value="instance('iRS')/some/deeply/nested/node"
    />
  </submission>
</model>

With the target attribute, and @replace="text", it can be condensed into the following:

<xf:model>
  <xf:instance>
    <x>
      <y />
    </x>
  </xf:instance>
  <xf:submission
   method="get" action="AnEnormousXMLFile.xml#xpointer(/some/deeply/nested/node/text())"
   target="y" replace="text"
  />
</xf:model>

A spin-off from this feature is that the target attribute can also be used in conjunction with @replace="instance", and so build up complex documents by inserting retrieved sub-trees into the current instance, instead of replacing it entirely. This can be particularly handy when dealing with large XForms documents containing instance data with potentially many optional sections. In this way, it can work like relevance, but in reverse, adding the sections you need, rather than disabling those you don't.

For example:

<xf:model>
  <xf:instance>
    <x>
      <y />
    </x>
  </xf:instance>
  <xf:submission
   method="get" action="ASmallXMLFile.xml"
   target="y" replace="instance"
  />
</xf:model>

The above example would insert the XML content of the document at ASmallXMLFile.xml, into the y element.