XForms/Submit

The Submit Element

One of the reasons that we have been careful to store all of our data in the model is that once this is done it makes it easy for a web client to simply serialize this model into XML and send it to a file, a web service, or possibly to a database.

This is all done by using a simple submit command. submit is really just a trigger with an attribute of submission that points to a submission element in the model. This is usually a button with the word "Submit" or "Save" on it that appears at the end of the form.

On many HTML forms you fill out the form and press a button at the bottom of the form called "Save" or "Submit". You pressed the button and hoped your data would get saved. This is the same concept. But in this case the submit command can be triggered in many ways other that just a button being pressed and there are explicit ways of getting feedback from the receiver that the submission process succeeded.

The submit event behaves exactly like a trigger but with one key exception, the xforms-submit event is also dispatched.

A model can have more than one submission identified by id

<xforms:submission id="s001" method="post" action="action.php"/>
<xforms:submission id="s002" method="post" action="action2.php" replace="instance"/>
<xforms:submission id="s003" method="put" action="file:///tmp/final.xml"/>

The first submission sends the data to the specified action, while the second one will expect to get a return xml to update the current document/instance. The third one will save the file locally to the given location /tmp/final.xml

Screen Image

The interface is very simple. It is just a simple "Save" button created by a trigger called submit.

XForms save button

Sample Program

<html
   xmlns="http://www.w3.org/1999/xhtml"
   xmlns:xf="http://www.w3.org/2002/xforms"
   xmlns:ev="http://www.w3.org/2001/xml-events">
   <head>
      <title>XForms Submit Example</title>
      <xf:model>
         <xf:instance xmlns="">
            <MyData>
               <Data1>One</Data1>
               <Data2>Two</Data2>
               <Data3>Three</Data3>
            </MyData>
         </xf:instance>
         <xf:submission id="save" method="put" action="myData.xml" ref="/MyData"/>
      </xf:model>
   </head>
   <body>
       <xf:submit submission="save">
         <xf:label>Save</xf:label>
      </xf:submit>
   </body>
</html>

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" 
    xmlns:xf="http://www.w3.org/2002/xforms"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/20021/XMLSchema-instance">
    
    <head>
        <title>Submission with get and put</title>
        <xf:model>
            <xf:instance id="data_instance" src="data.xml" xmlns=""></xf:instance>
            <xf:submission id="read-from-file" method="get" action="data.xml" replace="instance"
                instance="data-instance"></xf:submission>
            <xf:submission id="save-to-file" method="put" action="data.xml" replace="instance"
                instance="data_instance"></xf:submission>
        </xf:model>
    </head>
    <body>
        <p>Demonstration of using XForms to get and put data to local file using the submission
            element.</p>
        <xf:input ref="Element1">
            <xf:label>Element1:</xf:label>
        </xf:input>
        <br />
        <xf:input ref="Element2">
            <xf:label>Element2:</xf:label>
        </xf:input>
        <br />
        <xf:input ref="Element3">
            <xf:label>Element3:</xf:label>
            <br />
        </xf:input>
        <xf:submit submission="read-from-file">
            <xf:label>Reload</xf:label>
        </xf:submit>
        <xf:submit submission="save-to-file">
            <xf:label>Save</xf:label>
        </xf:submit>
    </body>
</html>

Analysis

The save button is really just a trigger with the name of "submit" and an attribute called submission.

   <xf:submit submission="save">

The attribute submission="save" points to the ID of the submission element inside the model.

   <xf:submission id="save" method="put" action="myData.xml" ref="/MyData"/>

Note that because we used a "relative file name" (relative to the directory that the form was in) it will save the data in the same directory location that the form was located.

Discussion

You can also use absolute path names but you must be careful about how you describe a letter drive since there are no standards for this.

The following format worked for a Microsoft Windows system using the FireFox browser:

   <xf:submission id="save" method="put" action="file:/C:/tmp/myData.xml" ref="/MyData"/>

Web Server Configuration

Note: This section was written by a person that does not know much about web server administration. Read at your own risk and make sure a security professional reviews any changes to your public web servers.

Most of the examples in this tutorial are about learning XForms, not web server administration. That being said there are a few things we thought might be useful.

By default web servers are usually not configured to write files to your web server. Especially by un-authorized users. If this were the case hackers might use your web server to store their adult content.

To get XForms to save instance using "put", you should only allow writing to authorized users. To do this you will need to be able to administer your web server correctly.

Apache 2.2 Intranet Configuration with DAV

If you have a computer that is only accessible by internal users (usually called an Intranet) you can access, you can add the following to your Apache configuration file (usually called httpd.config and located in /usr/local/etc or similar location):

First, the following modules may have to be loaded:

mod_dav, mod_dav_fs, mod_dav_svn, mod_authz_svn.

This can be done by adding the following lines to your httpd.conf file:

LoadModule dav_module libexec/apache22/mod_dav.so
LoadModule dav_fs_module libexec/apache22/mod_dav_fs.so

<Directory "usr/local/www/apache22/data/forms/read-write-test">
   DAV on
   AllowOverride None
   Order allow,deny
   Allow from all
</Directory>

By turning on DAV you will enable all of the WebDAV operations including "PUT".

IIS Configuration

To be done...

References

Next Page: Encoding Parameters | Previous Page: Case Validation
Home: XForms