Upload middleware
*****************

The principle is to count uploaded chunks in the wsgi loop, transmit them to the
application, and provide a link with up-to-date json information. The optional
javascript code is able to use an existing form and replace it with a progress
bar during upload. It can also generate its own upload form, then upload several
files sequentially with multiple progress bars. gp.fileupload can be used
without modifying your application, just by adding it in the wsgi stack.

It has currently been tested with Pylons and Zope 3.

Middleware
----------

Wrap your wsgi application with the middleware::

  >>> from gp.fileupload import FileUpload

  >>> def my_application(environ, start_response):
  ...     start_response('200 OK', [('Content-Type', 'txt/html')])
  ...     return ['<html><body>My app</body></html>']

  >>> app = FileUpload(my_application, tempdir=TEMP_DIR,
  ...                  max_size=None)

  >>> def application(environ, start_response):
  ...     return app(environ, start_response)

The `FileUpload` middleware has the following options:

- `tempdir`: A path to a temporary folder

- `max_size`: Max allowed size. If the file size is larger than `max_size` a
  `RuntimeError` is raised. 

- `include_files`: A list of static files that the middleware should include in
  your html body (see below). You might want to include the files by yourself
  in the relevant pages, or they will be included in all of your pages.

Application code
----------------

Write an html form like this::

  <form enctype="multipart/form-data"
        method="POST"
        action=".?gp.fileupload.id=1">
    <input type="file" name="file" />
    <input type="submit" />
  </form>

Where 1 is the session id. The session id **must** be a digit.

When the form is submitted, you can use some ajax stuff to get the stats of the upload with the url::

  http://yourhost/gp.fileupload.stat/1

This will return some JSON data like::

  {'state': 1, 'percent': 69}

`state` can have the following values:

- `0`: nothing done yet.

- `1`: upload is active

- `-1`: file is larger than max_size.

You can use this to display the upload progress.


