1 [donation_link]: https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=3PMY37SL9L888&lc=US&item_name=JavaScript%20file%20uploader¤cy_code=USD&bn=PP%2dDonationsBF%3abtn_donate_SM%2egif%3aNonHosted
3 This plugin uses XHR for uploading multiple files with progress-bar in FF3.6+, Safari4+,
4 Chrome and falls back to hidden iframe based upload in other browsers,
5 providing good user experience everywhere.
7 ### <a href="http://valums.com/files/2010/file-uploader/demo.htm">Demo</a> [Donate][donation_link] ###
10 * multiple file select, progress-bar in FF, Chrome, Safari
11 * drag-and-drop file select in FF, Chrome
12 * uploads are cancellable
13 * no external dependencies
15 * fully working with https
16 * keyboard support in FF, Chrome, Safari
17 * tested in IE7,8; Firefox 3,3.6,4; Safari4,5; Chrome; Opera10.60;
20 This plugin is open sourced under <a href="http://www.gnu.org/licenses/gpl-2.0.html">GNU GPL 2</a> or later.
21 If this license doesn't suit you mail me at andrew (at) valums.com.
23 Please [donate][donation_link] if you are willing to support the further development of file upload plugin.
26 Plugin breaks back button functionality in Opera.
28 ### Getting started ###
29 The fileuploader.js contains two classes that are meant to be used directly.
30 If you need a complete upload widget (from demo) to quickly drop
31 into your current design, use qq.FileUploader.
33 If you want to customize uploader, by using a different looking file list
34 or change the behaviour or functionality use qq.FileUploaderBasic.
36 The difference between them is that qq.FileUploader provides a list of files,
37 drag-and-drop, but qq.FileUploaderBasic only creates button and handles validation.
38 Basic uploader is easier extendable, and doesn't limit possible customization.
40 qq.FileUploader extends qq.FileUploaderBasic, so that all the options present
41 in the basic uploader also exist in the full widget.
43 ### qq.FileUploader - Setting up full upload widget ###
45 Include fileuploader.js and fileuploader.css into your page.
46 Create container element.
48 <div id="file-uploader">
50 <p>Please enable JavaScript to use file uploader.</p>
51 <!-- or put a simple form for upload here -->
55 Initialize uploader when the DOM is ready. Change the action option.
56 For example ../server/php.php for the default folder structure.
57 In the server folder you will find examples for different platforms.
58 If you can't find the one you need, check the readme.txt in the same folder.
60 var uploader = new qq.FileUploader({
61 // pass the dom node (ex. $(selector)[0] for jQuery users)
62 element: document.getElementById('file-uploader'),
63 // path to server-side upload script
64 action: '/server/upload'
67 ### Options of both classes ###
69 // url of the server-side upload script, should be on the same domain
70 action: '/server/upload',
71 // additional data to send, name-value pairs
75 // ex. ['jpg', 'jpeg', 'png', 'gif'] or []
76 allowedExtensions: [],
77 // each file size limit in bytes
78 // this option isn't supported in all browsers
79 sizeLimit: 0, // max size
80 minSizeLimit: 0, // min size
82 // set to true to output server response to console
86 // you can return false to abort submit
87 onSubmit: function(id, fileName){},
88 onProgress: function(id, fileName, loaded, total){},
89 onComplete: function(id, fileName, responseJSON){},
90 onCancel: function(id, fileName){},
93 // error messages, see qq.FileUploaderBasic for content
95 showMessage: function(message){ alert(message); }
99 * setParams(newParams)
101 #### Changing alert/messages to something more user friendly ####
103 If you limited file types and max size, you will probably want to change the default alert and
104 messages as you see fit, this is possible using showMessage callback and messages option.
106 #### Sending additional params ####
108 To add a parameter that will be passed as a query string with each upload use params option.
110 var uploader = new qq.FileUploader({
111 element: document.getElementById('file-uploader'),
112 action: '/server-side.upload',
113 // additional data to send, name-value pairs
120 To change params based on the state of your app, use
123 anotherParam: 'value'
126 It can be nicely used in onSubmit callback.
128 #### Troubleshooting ####
130 If you can't get the uploader to work, please try the following steps
131 before asking for help.
133 If the upload doesn't complete, saying failed.
135 * Set the debug option of the FileUploader to true.
136 * Open the page where you have a FileUploader.
137 * Open developer console in your browser.
138 * Try to upload the file. You should see a server serponse.
140 It should be {success:true} for completed requests. If it's not,
141 then you have a problem with your server-side script.
143 #### Contributors ####
145 Thanks to everybody who contributed, either by sending bug reports or donating. And special thanks to: