ASP and XForms

This example shows how to obtain and manipulate submitted XForms instance data within an Active Server Page. Our ASP is called EchoPerson.asp, which takes the submitted XML and outputs it to the browser in a tabular format. (The full ASP code is available here.)

In the ASP, to get hold of the XML instance data, we create an MSXML DOMDocument and load the HTTP Request (the submitted XML) into it, using the load method, as follows:

     ... 
     var oXML = new ActiveXObject("MSXML2.DOMDocument");
     oXML.load(Request);
     ...

Now we have the instance data in the DOMDocument we can retrieve values from it to set our script variables. Using the selectSingleNode XPath function we return a node from which we can get the value:

     ...
     var oFirstName = oXML.selectSingleNode("/person/firstname");
     var sFirstName = oFirstName.text;
     var oSurname   = oXML.selectSingleNode("/person/surname");
     var sSurname   = oSurname.text;
     ...

Now we have the instance data values stored into our JavaScript variables we can do as we want with them, in this case just format them for display using an HTML table:

     ...
     var sHTML = "";
     sHTML += ";"
     sHTML += ";"
     ...
     sHTML += "
First name : 
" + sFirstName + "
Surname : 
" + sSurname + 
"
     ...

Once we have built up the complete HTML string we return it to the browser:

     ...
     Response.Write(sHTML);         

To try this for yourself:

1. Extract the person.html and EchoPersonDataASP.asp files from the xfserverscripts.zip (see 'Prerequisites') to the root directory of your default IIS site.
2. Open the person.html file in notepad, or other text editor, and change the submission element action attribute to "EchoPersonDataASP.asp".
3. Open up Internet Explorer and go to http://localhost/person.html
4. Change any data and submit the form.

ColdFusion (6.1) and XForms

As with the previous examples, this one shows how to output the submitted XForms data in an HTML table but this time we are using ColdFusion 6.1 as the scripting language. (The full ColdFusion code is available here.)

After submission of the XForm, the first thing to do in the ColdFusion page is to get hold of the request data and put it into a variable. This is achieved using the GetHttpRequestData() system function:

     ...
     
     ...     

The GetHttpRequestData() function gets ALL of the request data, the headers and the body. We are only interested in the body of the request in this example which is obtained with the content parameter. Once we have that, we convert it to a string using ToString and parse it, using the XMLParse function:

     ...
     
     ...              

Now we have the XML document available to our ColdFusion page we can do what we want with the data. In our sample it is just to display the values in an HTML table:

     ...
     <td>
          First name
     </td>
     <td>
          #xmlDoc.person.firstname.XmlText#
     </td>
     ...

To try this example for yourself:

1. Install and configure ColdFusion 6.1 (Trial version available from Macromedia site).
2. Extract the person.html and showdata.cfm files from the xfserverscripts.zip (see 'Prerequisites') to the same directory in the site you have configured to use with ColdFusion.
3. Open the person.html file in notepad, or other text editor, and change the submission element action attribute to "showdata.cfm".
4. Open up Internet Explorer and go to your website eg. http://localhost/person.html
5. Change any data and submit the form.

Java servlets and XForms

This example shows one way to obtain and manipulate submitted XForms instance data within a Java Servlet. Our Servlet is called EchoPersonDataServlet, which takes the submitted XML and outputs to the browser in a tabular format the names and values of the XML elements. Any empty elments are ignored. (The full PHP code is available here.)

NOTE: If you wish to compile and use the EchoPerson Servlet with Tomcat you will need to have added the following .jar files to your classpath. %TOMCAT_HOME%\common\lib\servlet-api.jar, %TOMCAT_HOME%\common\endorsed\xercesImpl.jar and %TOMCAT_HOME%\common\endorsed\xmlParserAPIs.jar. You will also have to configure the web.xml file in your web application to reference the Servlet.

In the Servlet, to get hold of the XML instance data, we read in the body of the request to a string:

     ...    
     String xml      = new String("");
     String thisLine = new String("");
     ...
     BufferedReader br = request.getReader();
     while ((thisLine = br.readLine()) != null) {
          xml = xml.concat(thisLine);
     }
     ...              

Now we have the instance data in a string we will use DocumentBuilderFactory and DocumentBuilder objects along with the Document interface to help manipulate it. From java.sun.com - "The Document interface represents the entire HTML or XML document. Conceptually, it is the root of the document tree, and provides the primary access to the document's data".

     ...
     DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
     try {
          DocumentBuilder builder  = factory.newDocumentBuilder();
          Document        document = builder.parse(new InputSource(new StringReader(xml)));
     ...

All the rest of the Servlet does is to iterate through the nodes of the XML and format the names and values of the elements in an HTML table which is returned to the browser to be displayed.

NOTE: How to manipulate the submitted XForms data and whether to use DOM or SAX to do it is really up to the developer and it depends what the exact needs are. For more information on using XML and Java please take a look at the Java Web Services Tutorial.

To try this example for yourself:
NOTE: Installing and configuring Tomcat goes beyond the scope of this tutorial but listed below are the major steps involved in running this tutorial. For complete instructions on using web applications with Tomcat please follow the documentation available on the Apache website.

1. Install and configure Jakarta Tomcat 5 (download from The Apache Site).
2. Make sure that your CLASSPATH contains references to the servlet-api.jar, xercesImpl.jar and xmlParserAPIs.jar files that are mentioned earlier in this section.
3. Create your own 'webapp' structure and extract the person.html file to the root of it.
4. Extract the EchoPersonDataServlet.java file to the 'classes' directory of your webapp and compile.
5. Use the web.xml file for your webapp to map the EchoPersonDataServlet class to a URL.
6. Open the person.html file in notepad, or other text editor, and change the submission element action attribute to the value of the URL you specified in the web.xml file. Remember Tomcat defaults to use port 8080.
7. Start Tomcat, open Internet Explorer and point it to the location of the person.html file.
8. Change any data and submit the form.

PHP and XForms

NOTE: You can download the PHP installer from http://www.php.net. This example was tested with the default installation. The PHP 4.3.7 installation also includes expat, an XML toolkit written by James Clark that parses XML in C. This is an event based XML parser which we will make use of.

This example shows how to obtain and manipulate submitted XForms instance data within a PHP script. Our PHP script is called EchoPerson.php, and it simply outputs the received data to the browser in a tabular format. (The full PHP code is available here.)

The first thing we need to do in the script is to make sure that there is some data for us to process. Any submitted data will be available to us in the HTTP_RAW_POST_DATA global variable. We check to see if this has a value and if it has, assign the data to a local variable:

     ... 
     if (!empty($GLOBALS['HTTP_RAW_POST_DATA'])) {
    
          $req = $HTTP_RAW_POST_DATA;
     ...
     }
     ...

Once we have some data, we create an XML parser, set up the event handler functions--using xml_set_element_handler() and xml_set_character_data_handler(), and then set any other options we need with xml_parser_set_option:

     ...
     $xmlParser = xml_parser_create();
     xml_set_element_handler($xmlParser, "startElement", "endElement");
     xml_set_character_data_handler($xmlParser, "characterData");
     xml_parser_set_option($xmlParser, XML_OPTION_CASE_FOLDING, FALSE);
     ...

The startElement() and endElement() functions are defined further up in the script and these functions are where we put any code to call when the parser comes across a new element or finishes reading an element. The characterData() function is also defined further up the script, and this deals with what to do with data contained inside the element. Within these functions we also reference two global variables $currentEle and $sHTML. The first is to keep track of the name of the current element that is being processed, and the other will hold the HTML that will eventually be displayed:

     ...
     $currentEle = "";
     $sHTML      = "";
     
     function startElement($parser, $name, $attrs) {
          global $currentEle;
          global $sHTML;
          $currentEle = $name;
          if (!ignoreElement($currentEle)) {
               $sHTML .= "$name";
          }     
     }
     
     function endElement($parser, $name) {
          global $currentEle;
          $currentEle = "";
     }
     
     function characterData($parser, $data) { 
          global $currentEle;
          global $sHTML;
          if (!ignoreElement($currentEle)) {
               $sHTML .= "$data";
          }
     }
     ...

There is also one more function defined in the script (ignoreElement()) that is used by a couple of the parser event handlers. As we have elements that don't contain data (person and address) we don't want to display them in our HTML table; the elements we don't want to display have their names contained in an array so that we can compare the current element name (global variable $currentEle) with the values in our array, and decide to ignore the element if we have a match:

     ...
      function ignoreElement($eleName) {
          $ignore      = false;
          $ignoreThese = array(0 => "person", 
                               1 => "address",
                               2 => ""
                              );
          foreach ($ignoreThese as $value) {
               if ($value == $eleName) {
                    $ignore = true;  
                    break;
               } 
          }
          return $ignore;
     }    
     ...    

Now we actually parse the XML using the conveniently named xml_parse() function. This returns either true or false depending on whether there were any errors or not. If there are any errors we just add them to the HTML string that has been built up:

     ...
     if(!xml_parse($xmlParser, $req, TRUE)) {
          $sHTML .= "";
          $sHTML .= "An error occurred : ";
          $sHTML .= xml_error_string(xml_get_error_code($xmlParser));
          $sHTML .= "Line : " . xml_get_current_line_number($xmlParser);
          $sHTML .= "Column : " . xml_get_current_column_number($xmlParser);
          $sHTML .= "";
     }     
     ...

After finishing off the HTML table and freeing up the parser memory (using xml_parser_free()) we output the HTML:

    ...
     print $sHTML;
    ...

NOTE: Documentation for all PHP functions, including those for the XML parser are available online at http://www.php.net/docs.php.

To try this for yourself:

1. Get the person.html and EchoPerson.php files, and place them in the root directory of your website.
2. Open person.html in notepad, or some other text editor, and change the submission element action attribute to EchoPerson.php.
3. Open up Internet Explorer and go to http://localhost/person.html, or wherever you have located the file.
4. Change any data and submit the form.
5. The browser page should be replaced with the output form the server.