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
The interface is very simple. It is just a simple "Save" button created by a trigger called submit.
<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>
When you press the Save button it will create a file in the same directory that the form was in called "myData.xml". This file will contain the XML instance data in your model.
Contents of "myData.xml":
<?xml version="1.0" encoding="UTF-8"?> <MyData xmlns:xf="http://www.w3.org/2002/xforms" xmlns:ev="http://www.w3.org/2001/xml-events"> <Data1>One</Data1> <Data2>Two</Data2> <Data3>Three</Data3> </MyData>
Note that this program works easily when the form and the instance data are on a local file system. Getting this example to save to a web server is a much more complex process due to security concerns.
The save button is really just a trigger with the name of "submit" and an attribute called submission.
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.
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".
To be done...