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.
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:
|
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 |
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 |
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
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 |
Allows the upload to be cancelled
Name | Type | Default | Description |
---|---|---|---|
No parameters |
- 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
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 March 2014 the browser versions listed above should account for approx 80% of all internet users
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
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)