diff options
Diffstat (limited to 'addon/js_upload/file-uploader/readme.md')
| -rw-r--r-- | addon/js_upload/file-uploader/readme.md | 152 |
1 files changed, 152 insertions, 0 deletions
diff --git a/addon/js_upload/file-uploader/readme.md b/addon/js_upload/file-uploader/readme.md new file mode 100644 index 000000000..c107bf122 --- /dev/null +++ b/addon/js_upload/file-uploader/readme.md @@ -0,0 +1,152 @@ +[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 + +This plugin uses XHR for uploading multiple files with progress-bar in FF3.6+, Safari4+, +Chrome and falls back to hidden iframe based upload in other browsers, +providing good user experience everywhere. + +### <a href="http://valums.com/files/2010/file-uploader/demo.htm">Demo</a> [Donate][donation_link] ### + +### Features ### +* multiple file select, progress-bar in FF, Chrome, Safari +* drag-and-drop file select in FF, Chrome +* uploads are cancellable +* no external dependencies +* doesn't use Flash +* fully working with https +* keyboard support in FF, Chrome, Safari +* tested in IE7,8; Firefox 3,3.6,4; Safari4,5; Chrome; Opera10.60; + +### License ### +This plugin is open sourced under <a href="http://www.gnu.org/licenses/gpl-2.0.html">GNU GPL 2</a> or later. +If this license doesn't suit you mail me at andrew (at) valums.com. + +Please [donate][donation_link] if you are willing to support the further development of file upload plugin. + +### Known Issues ### +Plugin breaks back button functionality in Opera. + +### Getting started ### +The fileuploader.js contains two classes that are meant to be used directly. +If you need a complete upload widget (from demo) to quickly drop +into your current design, use qq.FileUploader. + +If you want to customize uploader, by using a different looking file list +or change the behaviour or functionality use qq.FileUploaderBasic. + +The difference between them is that qq.FileUploader provides a list of files, +drag-and-drop, but qq.FileUploaderBasic only creates button and handles validation. +Basic uploader is easier extendable, and doesn't limit possible customization. + +qq.FileUploader extends qq.FileUploaderBasic, so that all the options present +in the basic uploader also exist in the full widget. + +### qq.FileUploader - Setting up full upload widget ### + +Include fileuploader.js and fileuploader.css into your page. +Create container element. + + <div id="file-uploader"> + <noscript> + <p>Please enable JavaScript to use file uploader.</p> + <!-- or put a simple form for upload here --> + </noscript> + </div> + +Initialize uploader when the DOM is ready. Change the action option. +For example ../server/php.php for the default folder structure. +In the server folder you will find examples for different platforms. +If you can't find the one you need, check the readme.txt in the same folder. + + var uploader = new qq.FileUploader({ + // pass the dom node (ex. $(selector)[0] for jQuery users) + element: document.getElementById('file-uploader'), + // path to server-side upload script + action: '/server/upload' + }); + +### Options of both classes ### + + // url of the server-side upload script, should be on the same domain + action: '/server/upload', + // additional data to send, name-value pairs + params: {}, + + // validation + // ex. ['jpg', 'jpeg', 'png', 'gif'] or [] + allowedExtensions: [], + // each file size limit in bytes + // this option isn't supported in all browsers + sizeLimit: 0, // max size + minSizeLimit: 0, // min size + + // set to true to output server response to console + debug: false, + + // events + // you can return false to abort submit + onSubmit: function(id, fileName){}, + onProgress: function(id, fileName, loaded, total){}, + onComplete: function(id, fileName, responseJSON){}, + onCancel: function(id, fileName){}, + + messages: { + // error messages, see qq.FileUploaderBasic for content + }, + showMessage: function(message){ alert(message); } + +Instance methods + +* setParams(newParams) + +#### Changing alert/messages to something more user friendly #### + +If you limited file types and max size, you will probably want to change the default alert and +messages as you see fit, this is possible using showMessage callback and messages option. + +#### Sending additional params #### + +To add a parameter that will be passed as a query string with each upload use params option. + + var uploader = new qq.FileUploader({ + element: document.getElementById('file-uploader'), + action: '/server-side.upload', + // additional data to send, name-value pairs + params: { + param1: 'value1', + param2: 'value2' + } + }); + +To change params based on the state of your app, use + + uploader.setParams({ + anotherParam: 'value' + }); + +It can be nicely used in onSubmit callback. + +#### Troubleshooting #### + +If you can't get the uploader to work, please try the following steps +before asking for help. + +If the upload doesn't complete, saying failed. + +* Set the debug option of the FileUploader to true. +* Open the page where you have a FileUploader. +* Open developer console in your browser. +* Try to upload the file. You should see a server serponse. + +It should be {success:true} for completed requests. If it's not, +then you have a problem with your server-side script. + +#### Contributors #### + +Thanks to everybody who contributed, either by sending bug reports or donating. And special thanks to: + +John Yeary +Sidney Maestre +Patrick Pfeiffer +Sean Sandy (SeanJA) +Andy Newby +Ivan Valles
\ No newline at end of file |