js_upload/file-uploader/readme.md

   1 [donation_link]: https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=3PMY37SL9L888&lc=US&item_name=JavaScript%20file%20uploader&currency_code=USD&bn=PP%2dDonationsBF%3abtn_donate_SM%2egif%3aNonHosted
   2
   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.
   6
   7 ### <a href="http://valums.com/files/2010/file-uploader/demo.htm">Demo</a> [Donate][donation_link] ###
   8
   9 ### Features ###
  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
  14 * doesn't use Flash
  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;
  18
  19 ### License ###
  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.
  22
  23 Please [donate][donation_link] if you are willing to support the further development of file upload plugin.
  24
  25 ### Known Issues ###
  26 Plugin breaks back button functionality in Opera.
  27
  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.
  32
  33 If you want to customize uploader, by using a different looking file list
  34 or change the behaviour or functionality use qq.FileUploaderBasic.
  35
  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.
  39
  40 qq.FileUploader extends qq.FileUploaderBasic, so that all the options present
  41 in the basic uploader also exist in the full widget.
  42
  43 ### qq.FileUploader - Setting up full upload widget ###
  44
  45 Include fileuploader.js and fileuploader.css into your page.
  46 Create container element.
  47
  48     <div id="file-uploader">
  49         <noscript>
  50             <p>Please enable JavaScript to use file uploader.</p>
  51             <!-- or put a simple form for upload here -->
  52         </noscript>
  53     </div>
  54
  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.
  59
  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'
  65     });
  66
  67 ### Options of both classes ###
  68
  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
  72     params: {},
  73
  74     // validation
  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
  81
  82     // set to true to output server response to console
  83     debug: false,
  84
  85     // events
  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){},
  91
  92     messages: {
  93         // error messages, see qq.FileUploaderBasic for content
  94     },
  95     showMessage: function(message){ alert(message); }
  96
  97 Instance methods
  98
  99 * setParams(newParams)
 100
 101 #### Changing alert/messages to something more user friendly ####
 102
 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.
 105
 106 #### Sending additional params ####
 107
 108 To add a parameter that will be passed as a query string with each upload use params option.
 109
 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
 114         params: {
 115             param1: 'value1',
 116             param2: 'value2'
 117         }
 118     });
 119
 120 To change params based on the state of your app, use
 121
 122     uploader.setParams({
 123        anotherParam: 'value'
 124     });
 125
 126 It can be nicely used in onSubmit callback.
 127
 128 #### Troubleshooting ####
 129
 130 If you can't get the uploader to work, please try the following steps
 131 before asking for help.
 132
 133 If the upload doesn't complete, saying failed.
 134
 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.
 139
 140 It should be {success:true} for completed requests. If it's not,
 141 then you have a problem with your server-side script.
 142
 143 #### Contributors ####
 144
 145 Thanks to everybody who contributed, either by sending bug reports or donating. And special thanks to:
 146
 147 John Yeary
 148 Sidney Maestre
 149 Patrick Pfeiffer
 150 Sean Sandy (SeanJA)
 151 Andy Newby
 152 Ivan Valles