zofuthan / lite-uploader

LiteUploader - HTML5 jQuery File Uploader ^v2.1.2

This is a small jQuery plugin (featured in this jQuery plugin top 10) which utilises the HTML5 features (File API and XHR2) to make uploading files a doddle.

The aim was to see, at its absolute minimum, how little code do you need to make a small, but very usable and easily expandable jQuery upload plugin. With some useful options including basic validation it turns out not many. After minification it is very small in size and is a good choice for any developer who is not so worried about supporting legacy browsers.

Bower

bower install lite-uploader --save

Options

Name	Type	Default	Description
script	String (required)	null	the path to the script file that will handle the upload
rules	Object	{allowedFileTypes: null, maxSize: null}	object where you can specify validation rules for the files to be uploaded - current supported rules are: allowedFileTypes (list of comma-separated mime-types) maxSize (in bytes)
params	Object	{}	object of params to be sent to the server in addition to the files being uploaded
changeHandler	Boolean	true	initiate the upload on file input change
clickElement	jQuery Element	null	initiate the upload on the click event of the jQuery element passed here

Events

Name	Parameters	Description
lu:errors	event, errors	triggered after input and file validation - see 'File Error Types' section for more
lu:before	event, files	triggered before the uploading starts
lu:progress	event, percentage	triggered whilst uploading files
lu:success	event, response	triggered on upload success
lu:fail	event, jqXHR	triggered on upload failure
lu:cancelled	event	triggered on upload abort

File Error Types

Below is an overview of the error types that can be returned when validating files

• type - when file mime type does not match any mime types supplied in the rule.allowedFileTypes option
• size - when file size is above the size (in bytes) supplied in the rule.maxSize option

Public API

addParam(key, value)

Allows parameters to be added after plugin instantiation

Name	Type	Default	Description
key	String (required)	n/a	name of parameter to be added
value	String (required)	n/a	value of parameter to be added

cancelUpload()

Allows the upload to be cancelled, triggers lu:cancelled

Name	Type	Default	Description
No parameters

Gotchas

• make sure your uploads directory is writable (chmod 777)
• make sure your HTML file input has a name attribute as the plugin will not work without it

Browser Support

The two main HTML5 dependencies for the plugin are the File API and XHR2, and using caniuse (File API, XHR2) as a reference, if you are using any of the following browser versions you shouldn't have any problem with the code:

• Chrome 13+
• Firefox 4+
• Internet Explorer 10+
• Safari 6+
• Opera 12+

Using this tool I built which is based on stats from gs.statcounter.com, as of June 2014 the browser versions listed above should account for approx 81% of all internet users

Examples & Tests

There are 3 examples in the example directory (using PHP as the server-side language) to help you get on your way and also there is a full suite of Jasmine tests to back the plugin. They can be found in the tests directory and run by opening runner.html

Changelog

2.1.2 (29 October 2014)

• adds bower support

2.1.1 (09 June 2014)

• form data construction fix (thanks to @aFarkas for spotting this one)

2.1.0 (12 May 2014)

• adds ability to abort the upload
• adds blanket.js for test coverage reports
• adds more tests for better test coverage

2.0.0 (09 Apr 2014)

• complete rewrite - THIS VERSION IS NOT BACKWARDS COMPATIBLE
• you can now add params after instantiation
• you can now control when the uploader starts (on file input change or click of a element or both)
• callback functions have been replaced with triggered events

1.4.2 (20 Sept 2013)

• decouples main uploader functionality from jquery plugin instantiation
• adds mechanism to cancel upload within 'each' function
• files array now passed into 'before' function

1.4.1 (25 July 2013)

• adds progress option

1.4.0 (24 July 2013)

• a complete code overhaul
• adds 'customParams' option
• adds mechanism to cancel upload within 'before' function
• removes 'typeMessage' option
• removes 'sizeMessage' option
• the errors param for the 'each' function has changed format, it now returns {type, given, rule} rather than {type, message}

1.3.1 (28 Feb 2013)

• adds version and link at the top of un-minified js

1.3.0 (23 Feb 2013)

• removed multi option, this can be achieved by adding the multiple attribute to the file input instead
• if an ID attribute is set on file input, it is now sent through as POST data to the server script
• example improved to show how to handle multiple lite-uploader inputs on a single page

1.2.0 (30 Jan 2013)

• adds 'fail' function option
• updates ajax call to use new jquery methods (always, done, fail etc)

Suggestions, comments and queries welcome, send to [email protected]