7) APyaX Form (and File) Upload

Another useful APyaX feature allows form data to be uploaded to the server and passed to a python function. Forms may include text fields and files.

The APyaX generator searches the input (X)HTML document for forms with an onsubmit function call of the form:

apyax_upload(<pre-javascript-handler>,
<python-function>,
<post-javascript-handler>
[,<error-javascript-handler>])

where:

<pre-javascipt-handler>

This javascript function (if not null) is called to validate the form before it is submitted. The form object is passed into the function as a parameter. If the form is invalid, the function should return false, and the form will not be submitted.

<python-function>

All python scripts referenced from this page are searched for this function. This function is invoked on the server, once the form has been uploaded. The function is passed the usual apyax object as its first parameter and an object allowing the form contents to be retrieved as its second parameter. The function can return a value which is passed to the <post-javascript-handler> function (see below).

<post-javascript-handler>

This JavaScript function (if not null) is called after form upload and processing has successfully completed. The result value returned by the python function is passed into the function as a parameter.

<error-javascript-handler>

A javascript function which (if provided) is called in the event of an error. The value passed into this function is the value of the error string returned by APyaX.

The example (X)HTML illustrates how a <form> is set up to integrate with APyaX.


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<title>APyaX file upload</title>
	<script type="text/python" src="uploadit.py" />
	<script type="text/javascript" src="display.js" />
	<link rel="stylesheet" type="text/css" href="../../css/velocikit.css"/>
</head>

<body>

	<h2>APyaX File Upload</h2>

	<form id="form0" target="" onsubmit="apyax_upload(pre,uploadForm,post,post)">
		<div><label>Name:</label> <input type="text" name="form[name]" /></div>
		<div><label>File:</label> <input type="file" name="form[file]" /></div>
		<div><input type="submit" value="SUBMIT" /></div>
	</form>	

	<p><b>Status=<span id="result"></span></b></p>

</body>
</html>


Example XHTML source file for APyaX form upload


The function uploadForm below shows how the form object can be inspected from Python.



def uploadForm(apyax,form):
    pstr = "uploadit:"
    pstr += " strings: "
    stringkeys = form.getStringKeys()
    for stringkey in stringkeys:
	s = form.getString(stringkey)
	pstr += s
	pstr += " "

    pstr += " files: "
    filekeys = form.getFileKeys()
    for filekey in filekeys:
	(filename,file,type) = form.getFile(filekey)
	file.seek(0,2)
	filesize = file.tell()
	pstr += "(" + filename + "," + str(type) + "," + str(filesize)+" bytes) "

    return "OK (" + pstr +")"

    

The example APyaX python script uploadit.py


The apyax_form object that APyaX passes as the second argument to the form upload function provides access to the form's contents via the following methods:

class apyax_form
Server side object to provide access to the contents of an uploaded form
method getFile
def getFile(self,name)

Get information on an uploaded file associated with a form

Returns a tuple (<filename>,<file>,<type>) for a file with a matching key value <key> (or None if no match found) where:
<filename> is the name of the file
<file> is a file-like object
<type> is a string containing the mime-type

Parameters
namethe string key which identifies the file
Return Value
tuple describing file
method getFileKeys
def getFileKeys(self)

get keys associated with a form's uploaded files

Return Value
a list of the keys (as string values) for files included in the form
method getString
def getString(self,name)

Get information on a non-file parameter associated with a form

Parameters
namethe string key which identifies the value
Return Value
the value for the given key value <key>, or None if no matching key is found.
method getStringKeys
def getStringKeys(self)

get keys associated with a form's non-file values

Return Value
a list of the keys (as string values) for non-file objects in the form.

Finally, the JavaScript file display.js provides the functions pre and post to validate the form and return the result to the web page respectively.


/* display.js

pre and post processing for an example APyaX powered form

pre  : validate form.  Perform no checking and return true

post : assign the result string to the innerHTML
       of a tag in the document
*/

function pre(form) {
    return true
}

function post(result) {
    document.getElementById('result').innerHTML = result;
}

JavaScript support functions for the form upload example - display.js