Usage example¶

To make use of the Upload plugin, you’ll need to include the sijax_upload.js file on your page.

sijax_upload.js can be mirrored to a directory of your choise using sijax.helper.init_static_path().

To associate a handler function with an upload form on the page you need to use sijax.plugin.upload.register_upload_callback().

static upload.register_upload_callback(sijax_instance, form_id, callback, **options)

Helps you easily register Upload functions with Sijax.

We recommend the args_extra option to be used here, so that the response function would receive the files object or anything else it might be needing to manipulate file uploads. By using args_extra you could change the response function’s default signature from:

def upload_handler(obj_response, form_values)

to:

def upload_handler(obj_response, files, form_values)

where the args_extra=[files] option was passed during registering. To learn more on how the args_extra option works, refer to sijax.Sijax.register_callback().

It’s very important to keep in mind that unlike the regular sijax.Sijax.register_callback() function, this one returns some javascript code as a response. You need to execute that code on the page that contains the form you want to transform to Sijax upload.

Parameters:	sijax_instance – the sijax.Sijax instance to register callbacks with form_id – the id of the form as it appears in the DOM callback – the function to call to process the upload request options – options to pass to sijax.Sijax.register_callback()
Returns:	string - javascript code you need to put on your page, to make your form use Sijax when submitted

Here’s an example. Suppose you have this markup on your page:

<form id="formOne" name="formOne"
     style="width: 400px" method="post" enctype="multipart/form-data">
    Text field:
    <input type="text" name="message" value="Some text" /><br />

    Drop-down:
    <select name="dropdown">
        <option>1</option>
        <option selected="selected">2</option>
        <option>3</option>
    </select>
    <br />

    Chechbox:
    <input type="checkbox" checked="checked" name="chkbox" /><br />

    File:
    <input type="file" name="file" /><br />

    <input type="submit" value="Upload" />
</form>

To convert this form to a Sijax-enabled one, you need the following Python code:

from sijax.plugin.upload import register_upload_callback

def upload_handler(obj_response, form_values):
    # form_values = {'message': ['Some text'], 'chkbox': ['on'], 'dropdown': ['2']}
    obj_response.alert(repr(form_values))

js = register_upload_callback(sijax_instance, 'formOne', upload_handler)

# put the returned javascript code somewhere on your page to make your form Sijax-enabled

Notes on function registration¶

It’s important to note that the register_upload_callback function returns a short javascript code snippet, which takes care of preparing the form, so that it can be submitted using Sijax.

The args_extra function registration parameter can be used here (see Passing extra arguments (context)) It’s a good idea to always register upload handler function with one extra argument - the files object, which would be used to manipulate the uploaded files. For some environments there’s really no way around it, because at the context at which the upload handler function executes, there may not be an easy way (if any at all) to get a reference to the files object.

To pass an additional argument to upload_handler just do:

files = {'your': 'file', 'object' 'here'}

def upload_handler(obj_response, files, form_values):
    pass

register_upload_callback(sijax_instance, 'formOne', upload_handler, args_extra=[files])

The UploadResponse object¶

Functions registered via the Upload plugin using sijax.plugin.upload.register_upload_callback() receive an obj_response as their first argument, just like any other Sijax function.

The difference is that the obj_response object is an instance of the sijax.plugin.upload.UploadResponse class, which provides a bit more functionality than the regular sijax.response.BaseResponse class.

class sijax.plugin.upload.UploadResponse(*args, **kwargs)

Class used for Upload handler functions, instead of the sijax.response.BaseResponse class.

This class extends sijax.response.BaseResponse and every available method from it works here too.

UploadResponse.form_id

The id of the form that was submitted.

You can have several forms handled by the same upload handler function, which can be confusing unless you know the form id.

UploadResponse.reset_form()

Resets the form to the state it was in at page loading time.

Any changes made to it after that will be cleared.

Streaming responses (Comet functionality)¶

The way the Upload plugin works is very similar to the way the Comet plugin works (see Comet Plugin). They share most of their code, so you can do Comet streaming from your upload handler functions too. Let’s take a look at an example which handles a hypothetical image upload:

def upload_handler(obj_response, files, form_values):
    obj_response.alert("Processing your image file..")
    yield obj_response

    resize_image(files)
    url = get_image_url()

    obj_response.redirect(url)

You don’t need to do anything special to get streaming support in your upload handler functions. Every function registered via sijax.plugin.upload.register_upload_callback() supports Comet (it can yield/flush whenever you want).