4.2
Rating: 4.2/5 (5 votes)

File Uploader

A file upload control that supports uploading multiple files, uploading inline (without reloading the page), and displaying upload progress on supported browser (Chrome, FF, Safari).

Demo

Select files to upload:
(10 MB limit)

Select a suitably large file (>1 MB) to see the progress indicator on Chrome, Firefox or Safari

After uploading, view the upload directory to see your files (cleared out every hour.)

Source Example

<html> <head> <script language="javascript" src="protoplasm.js"></script> <script language="javascript"> Protoplasm.use('upload').transform('input.upload', { 'inline': true, 'multiple': true }); </script> </head> <body> <form action="upload.php" method="post"> <input type="file" name="file" class="upload" /> </form> </body> </html>

Usage

To create upload controls out of all elements that match a given CSS rule:

Protoplasm.use('upload').transform(selector[, options]);

Parameters:

Parameter Required Description
selector yes A CSS rule matching the text inputs to turn into color pickers
options no An object (hash) containing name/value pairs of additional options.

Available options:
multiple Allow multiple uploads (default: false)
inline Upload files immediately without reloading the page instead of submitting with the parent form. IMPORTANT: see "Upload Handling" section if you set this to true. (default: false)
progress Display file upload progress. Has no effect if "inline" is false. (default: true)
batch Use batch mode. Requires manually submission instead of uploading files as they are selected. Has no effect if "inline" is false. (default: false)
onSuccess Callback function when a file upload succeeds.
onFailure Callback function when a file upload fails
onComplete Callback function when a file upload completes.

Upload Handling

Displaying upload progress in inline mode requires passing the data to the server in a different format than usual. Rather than encoding the file data as multipart/form-data, the upload control sets a "Content-Disposition" header, and passes the file data as the POST body. Since not all browsers support this, if you want to display file upload progress on supported browsers (the default in "inline" mode), you will need to support both upload methods in your server's upload handler.

In your upload handler, simply check for a "Content-Disposition" header. If it exists, the POST body contains the file data, and the file name can be retrieved from the header. If it does not exist, the file was uploaded in "multipart/form-data" encoding and can be processed like any other file upload.

Sample PHP upload handler

To avoid this complication, you can also simply set the progress option to false, and files will always be submitted using multipart/form-data encoding.

Advanced Usage

If you want more control over creation and destruction of the upload control, you can instantiate it manually instead of using Protoplasm.transform.

In your <head> section:

Protoplasm.use('upload');

To create an upload control:

var upload = new Control.FileUpload(element[, options]);

To destroy the upload control:

upload.destroy();

For more details, see the API documentation for Control.FileUpload.