Ajax stuff
**********

Description
-----------

A `jQuery <http://jquery.com>`_ plugin is provided as a helper.

To use it, you only need to add a script tag to your html head section::

  <script type="text/javascript">
      jQuery(document).ready(function() { jQuery('#sample').fileUpload(); });
  </script>

The `fileUpload` plugin has the following options:

- `replace_existing_form`: replace the existing form with a generated one.
   Defaults to false.

- `submit_label`: The label of the general submit button.

- `field_name`: A string to use as file field name for each form. Default to `file`.

- `hidden_submit_name`: A string to use in the hidden field name located below
   each file field. The hidden field is supposed to replace the missing button,
   and is required by form frameworks (such as z3c.form) which expect a button
   name (bound to an action). Default to `submit`.

- `submit_empty_forms`: if true, submit forms with empty file fields. Default:
  true.

- `use_iframes`: If set to `false` the form will be submitted as a normal form.
  If `true` the form target become an iframe and the page is not reloaded.

- `stat_delay`: delay between each stat request. Default: 1500.  

- `success`: A javascript function evaluated when all files are uploaded. The
  default one does nothing.

Examples
--------

If you want multiple file forms::

    <div id="forms"></div>

    <script type="text/javascript">
      jQuery(document).ready(function() {
        jQuery('#forms').fileUpload({action:'/upload', field_name:'file_field'})
      });
    </script>

This will show a form with addable file field and upload them to `/upload`.
The forms are submitted in iframes as target so the page does not change after
uploading.

If you already have forms. This is what is done in the
`jquery.fileupload.auto.js`::

    <script type="text/javascript">
      jQuery(document).ready(function() {
        jQuery('form[enctype^='multipart/form-data]')
            .fileUpload({use_iframes: false});
      });
    </script>

This will show a progress bar when the form is uploaded, then redirect to the
application page when the upload is completed. So the usage is totally
transparent for you.


