Skip to content

Latest commit

 

History

History
148 lines (110 loc) · 5.34 KB

readme.md

File metadata and controls

148 lines (110 loc) · 5.34 KB
Raw

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.

Demo Donate

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 GNU GPL 2 or later. If this license doesn't suit you mail me at andrew (at) valums.com.

Please donate 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

// 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, try the following steps before asking for help.

Install Chrome or Safari to get their excellent developer tools, or alternatively use Firebug. Open resources tab in developer tools.

Try to upload a file, you will either see an error in the console, or a new item will be added to the resource list which should point to your upload script.

Select a content tab, and there you will see a server response. It should be {success:true} for completed requests. If it's not, you will probably see a reason there.

Contributors

Thanks to everybody who contributed, either by sending bug reports or donating. And special thanks to:

Sidney Maestre
Patrick Pfeiffer
Sean Sandy (SeanJA)
Andy Newby
Ivan Valles