XForms/Upload

Motivation

The upload element allows you to select a file from the file system using your operating system's "Browse" user interface. This file can then be transferred to the file server that the web form resides.

Screen Image

Here is a screen image of the Firefox XForms extension upload control after the C:\tmp\Foo.xml file was selected:

The XForms `upload` Element

<xf:upload ref="XPathExpression" mediatype="text/xml">
  <xf:filename ref="XPathExpression" />
  <xf:mediatype ref="XPathExpression" />
</xf:upload>

Sample Program

This sample program has a single instance variable called "File". At the end of the select this variable is set to the path-name of the file you just selected.

<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"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
>
   <head>
       <title/>
       <xf:model>
           <xf:instance xmlns="">
               <Data>
                   <File xsi:type="xs:anyURI"/>
               </Data>
           </xf:instance>
       </xf:model>
   </head>
   <body>
       <xf:upload ref="/Data/File">
           <xf:filename>file:///C:/tmp/*.xml</xf:filename>
           <xf:mediatype>text/xml</xf:mediatype>
       </xf:upload>
       <br/>
       <xf:output ref="/Data/File">
          <xf:label>File: </xf:label>
       </xf:output>
   </body>
</html>

Discussion

At the time of this writing, there is little documentation on how the upload control works. The screen shot above was taken from the Firefox XForms 0.8 running on Firefox 3 implementation. Note that the file name appears twice in the control itself. This may not be the future behavior. This may be that the filename and mediatype text inside the control are being displayed. There is no documentation yet on how to disable the clear trigger.

There is not yet documentation on how to upload instance data into the model using the upload control. Right now instance data must be hard-coded into the src attribute of an instance.

The following loads both an image and a URI.

<html xmlns="http://www.w3.org/1999/xhtml" 
xmlns:ev="http://www.w3.org/2001/xml-events" 
xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:xf="http://www.w3.org/2002/xforms" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <head>
        <title/>
        <xf:model>
            <xf:instance xmlns="">
                <data>
                    <image xsi:type="xs:base64Binary"/>
                    <uri xsi:type="xs:anyURI"/>
                </data>
            </xf:instance>
            <xf:submission id="save" action="http://xformstest.org/cgi-bin/showinstance.sh" method="post"/>
        </xf:model>
    </head>
    <body>
        <xf:upload ref="image">
            <xf:label>Upload Photo:</xf:label>
        </xf:upload>
        <br/>
        <xf:upload ref="uri">
            <xf:label>Upload File:</xf:label>
            <xf:filename>file:///C:/tmp/*.xml</xf:filename>
            <xf:mediatype>text/xml</xf:mediatype>
        </xf:upload>
        <br/>
        <xf:output ref="image">
            <xf:label>image: </xf:label>
        </xf:output>
        <br/>
        <xf:output ref="uri">
            <xf:label>uri: </xf:label>
        </xf:output>
        <br/>
        <xf:submit submission="save">
            <xf:label>Save</xf:label>
        </xf:submit>
    </body>
</html>

Uploading Binary Files

Any file type such as an image or XML file can be converted to a 64bit encoded file, stored in the instance and then transmitted to the server inside of a POST. On the server the file can be converted back to a string or binary.

Sample Echo With Binary to String Unencoding

The following is a simple echo script written in XQuery that echos back the binary file in XML. It is an XQuery script that uses a binary-to-string conversion function. This takes a file of type xs:base64binary and returns a string representation of the file. The data to be returned is in the element with the element name "xml-base64".

   xquery version "1.0";
   declare option exist:serialize "method=xml media-type=text/xml indent=yes"; 

   (: this gets the data from the HTTP POST :)
   let $post-data := request:get-data()
(: this converts the base-64 binary to a plaintext string that holds the unparsed XML content :)
   let $xml-as-string := util:base64-decode($post-data//xml-base64)
   let $parsed-xml := util:parse($xml-as-string)

   return
   <results>
      <xml-as-string>{$xml-as-string}</xml-as-string>
      <parsed-xml>{$parsed-xml}</parsed-xml>
   </results>

Sample Form

<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"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    >
    <head>
        <title>Upload XML</title>
        <xf:model>
            <xf:instance xmlns=''>
                <data>
                    <xml-base64 xsi:type="xs:base64Binary"/>
                </data>
            </xf:instance>
            
            <xf:submission id='post-to-echo' 
                action='echo-base64-binary.xq' replace="all"
                method='post'/>
            
        </xf:model>
    </head>
    <body>
        <br/>
        
        <xf:upload ref="xml-base64">
            <xf:label>Upload XML File:</xf:label>
        </xf:upload>
        
        <br/>
        <xf:output ref="xml-base64">
            <xf:label>XML file encoded in base64binary: </xf:label>
        </xf:output>
        <br/>
        
        <xf:submit submission="post-to-echo">
            <xf:label>Post to Echo</xf:label>
        </xf:submit>
        
    </body>
</html>

Sample File

<test>This is a small XML file.</test>

Warnings

The attribute data type assignment xsi:type="xs:anyURI" must be associated with the variable used to store the file path name.

References

W3C Upload Page

Next Page: Trigger | Previous Page: Formatting a date
Home: XForms