|
| 1 | +# jQuery File Upload |
| 2 | + |
| 3 | +## Contents |
| 4 | + |
| 5 | +- [Description](#description) |
| 6 | +- [Demo](#demo) |
| 7 | +- [Features](#features) |
| 8 | +- [Security](#security) |
| 9 | +- [Setup](#setup) |
| 10 | +- [Requirements](#requirements) |
| 11 | + - [Mandatory requirements](#mandatory-requirements) |
| 12 | + - [Optional requirements](#optional-requirements) |
| 13 | + - [Cross-domain requirements](#cross-domain-requirements) |
| 14 | +- [Browsers](#browsers) |
| 15 | + - [Desktop browsers](#desktop-browsers) |
| 16 | + - [Mobile browsers](#mobile-browsers) |
| 17 | + - [Extended browser support information](#extended-browser-support-information) |
| 18 | +- [Testing](#testing) |
| 19 | +- [Support](#support) |
| 20 | +- [License](#license) |
| 21 | + |
| 22 | +## Description |
| 23 | + |
| 24 | +> File Upload widget with multiple file selection, drag&drop support, |
| 25 | +> progress bars, validation and preview images, audio and video for jQuery. |
| 26 | +> Supports cross-domain, chunked and resumable file uploads and client-side |
| 27 | +> image resizing. |
| 28 | +> Works with any server-side platform (PHP, Python, Ruby on Rails, Java, |
| 29 | +> Node.js, Go etc.) that supports standard HTML form file uploads. |
| 30 | +
|
| 31 | +## Demo |
| 32 | + |
| 33 | +[Demo File Upload](https://blueimp.github.io/jQuery-File-Upload/) |
| 34 | + |
| 35 | +## Features |
| 36 | + |
| 37 | +- **Multiple file upload:** |
| 38 | + Allows to select multiple files at once and upload them simultaneously. |
| 39 | +- **Drag & Drop support:** |
| 40 | + Allows to upload files by dragging them from your desktop or file manager and |
| 41 | + dropping them on your browser window. |
| 42 | +- **Upload progress bar:** |
| 43 | + Shows a progress bar indicating the upload progress for individual files and |
| 44 | + for all uploads combined. |
| 45 | +- **Cancelable uploads:** |
| 46 | + Individual file uploads can be canceled to stop the upload progress. |
| 47 | +- **Resumable uploads:** |
| 48 | + Aborted uploads can be resumed with browsers supporting the Blob API. |
| 49 | +- **Chunked uploads:** |
| 50 | + Large files can be uploaded in smaller chunks with browsers supporting the |
| 51 | + Blob API. |
| 52 | +- **Client-side image resizing:** |
| 53 | + Images can be automatically resized on client-side with browsers supporting |
| 54 | + the required JS APIs. |
| 55 | +- **Preview images, audio and video:** |
| 56 | + A preview of image, audio and video files can be displayed before uploading |
| 57 | + with browsers supporting the required APIs. |
| 58 | +- **No browser plugins (e.g. Adobe Flash) required:** |
| 59 | + The implementation is based on open standards like HTML5 and JavaScript and |
| 60 | + requires no additional browser plugins. |
| 61 | +- **Graceful fallback for legacy browsers:** |
| 62 | + Uploads files via XMLHttpRequests if supported and uses iframes as fallback |
| 63 | + for legacy browsers. |
| 64 | +- **HTML file upload form fallback:** |
| 65 | + Allows progressive enhancement by using a standard HTML file upload form as |
| 66 | + widget element. |
| 67 | +- **Cross-site file uploads:** |
| 68 | + Supports uploading files to a different domain with cross-site XMLHttpRequests |
| 69 | + or iframe redirects. |
| 70 | +- **Multiple plugin instances:** |
| 71 | + Allows to use multiple plugin instances on the same webpage. |
| 72 | +- **Customizable and extensible:** |
| 73 | + Provides an API to set individual options and define callback methods for |
| 74 | + various upload events. |
| 75 | +- **Multipart and file contents stream uploads:** |
| 76 | + Files can be uploaded as standard "multipart/form-data" or file contents |
| 77 | + stream (HTTP PUT file upload). |
| 78 | +- **Compatible with any server-side application platform:** |
| 79 | + Works with any server-side platform (PHP, Python, Ruby on Rails, Java, |
| 80 | + Node.js, Go etc.) that supports standard HTML form file uploads. |
| 81 | + |
| 82 | +## Security |
| 83 | + |
| 84 | +⚠️ Please read the [VULNERABILITIES](VULNERABILITIES.md) document for a list of |
| 85 | +fixed vulnerabilities |
| 86 | + |
| 87 | +Please also read the [SECURITY](SECURITY.md) document for instructions on how to |
| 88 | +securely configure your Webserver for file uploads. |
| 89 | + |
| 90 | +## Setup |
| 91 | + |
| 92 | +jQuery File Upload can be installed via [NPM](https://www.npmjs.com/): |
| 93 | + |
| 94 | +```sh |
| 95 | +npm install blueimp-file-upload |
| 96 | +``` |
| 97 | + |
| 98 | +This allows you to include [jquery.fileupload.js](js/jquery.fileupload.js) and |
| 99 | +its extensions via `node_modules`, e.g: |
| 100 | + |
| 101 | +```html |
| 102 | +<script src="node_modules/blueimp-file-upload/js/jquery.fileupload.js"></script> |
| 103 | +``` |
| 104 | + |
| 105 | +The widget can then be initialized on a file upload form the following way: |
| 106 | + |
| 107 | +```js |
| 108 | +$('#fileupload').fileupload(); |
| 109 | +``` |
| 110 | + |
| 111 | +For further information, please refer to the following guides: |
| 112 | + |
| 113 | +- [Main documentation page](https://github.com/blueimp/jQuery-File-Upload/wiki) |
| 114 | +- [List of all available Options](https://github.com/blueimp/jQuery-File-Upload/wiki/Options) |
| 115 | +- [The plugin API](https://github.com/blueimp/jQuery-File-Upload/wiki/API) |
| 116 | +- [How to setup the plugin on your website](https://github.com/blueimp/jQuery-File-Upload/wiki/Setup) |
| 117 | +- [How to use only the basic plugin.](https://github.com/blueimp/jQuery-File-Upload/wiki/Basic-plugin) |
| 118 | + |
| 119 | +## Requirements |
| 120 | + |
| 121 | +### Mandatory requirements |
| 122 | + |
| 123 | +- [jQuery](https://jquery.com/) v1.7+ |
| 124 | +- [jQuery UI widget factory](https://api.jqueryui.com/jQuery.widget/) v1.9+ |
| 125 | + (included): Required for the basic File Upload plugin, but very lightweight |
| 126 | + without any other dependencies from the jQuery UI suite. |
| 127 | +- [jQuery Iframe Transport plugin](https://github.com/blueimp/jQuery-File-Upload/blob/master/js/jquery.iframe-transport.js) |
| 128 | + (included): Required for |
| 129 | + [browsers without XHR file upload support](https://github.com/blueimp/jQuery-File-Upload/wiki/Browser-support). |
| 130 | + |
| 131 | +### Optional requirements |
| 132 | + |
| 133 | +- [JavaScript Templates engine](https://github.com/blueimp/JavaScript-Templates) |
| 134 | + v3+: Used to render the selected and uploaded files for the Basic Plus UI and |
| 135 | + jQuery UI versions. |
| 136 | +- [JavaScript Load Image library](https://github.com/blueimp/JavaScript-Load-Image) |
| 137 | + v2+: Required for the image previews and resizing functionality. |
| 138 | +- [JavaScript Canvas to Blob polyfill](https://github.com/blueimp/JavaScript-Canvas-to-Blob) |
| 139 | + v3+:Required for the image previews and resizing functionality. |
| 140 | +- [blueimp Gallery](https://github.com/blueimp/Gallery) v2+: Used to display the |
| 141 | + uploaded images in a lightbox. |
| 142 | +- [Bootstrap](https://getbootstrap.com/) v3+: Used for the demo design. |
| 143 | +- [Glyphicons](https://glyphicons.com/) Icon set used by Bootstrap. |
| 144 | + |
| 145 | +### Cross-domain requirements |
| 146 | + |
| 147 | +[Cross-domain File Uploads](https://github.com/blueimp/jQuery-File-Upload/wiki/Cross-domain-uploads) |
| 148 | +using the |
| 149 | +[Iframe Transport plugin](https://github.com/blueimp/jQuery-File-Upload/blob/master/js/jquery.iframe-transport.js) |
| 150 | +require a redirect back to the origin server to retrieve the upload results. The |
| 151 | +[example implementation](https://github.com/blueimp/jQuery-File-Upload/blob/master/js/main.js) |
| 152 | +makes use of |
| 153 | +[result.html](https://github.com/blueimp/jQuery-File-Upload/blob/master/cors/result.html) |
| 154 | +as a static redirect page for the origin server. |
| 155 | + |
| 156 | +The repository also includes the |
| 157 | +[jQuery XDomainRequest Transport plugin](https://github.com/blueimp/jQuery-File-Upload/blob/master/js/cors/jquery.xdr-transport.js), |
| 158 | +which enables limited cross-domain AJAX requests in Microsoft Internet Explorer |
| 159 | +8 and 9 (IE 10 supports cross-domain XHR requests). |
| 160 | +The XDomainRequest object allows GET and POST requests only and doesn't support |
| 161 | +file uploads. It is used on the |
| 162 | +[Demo](https://blueimp.github.io/jQuery-File-Upload/) to delete uploaded files |
| 163 | +from the cross-domain demo file upload service. |
| 164 | + |
| 165 | +## Browsers |
| 166 | + |
| 167 | +### Desktop browsers |
| 168 | + |
| 169 | +The File Upload plugin is regularly tested with the latest browser versions and |
| 170 | +supports the following minimal versions: |
| 171 | + |
| 172 | +- Google Chrome |
| 173 | +- Apple Safari 4.0+ |
| 174 | +- Mozilla Firefox 3.0+ |
| 175 | +- Opera 11.0+ |
| 176 | +- Microsoft Internet Explorer 6.0+ |
| 177 | + |
| 178 | +### Mobile browsers |
| 179 | + |
| 180 | +The File Upload plugin has been tested with and supports the following mobile |
| 181 | +browsers: |
| 182 | + |
| 183 | +- Apple Safari on iOS 6.0+ |
| 184 | +- Google Chrome on iOS 6.0+ |
| 185 | +- Google Chrome on Android 4.0+ |
| 186 | +- Default Browser on Android 2.3+ |
| 187 | +- Opera Mobile 12.0+ |
| 188 | + |
| 189 | +### Extended browser support information |
| 190 | + |
| 191 | +For a detailed overview of the features supported by each browser version and |
| 192 | +known operating system / browser bugs, please have a look at the |
| 193 | +[Extended browser support information](https://github.com/blueimp/jQuery-File-Upload/wiki/Browser-support). |
| 194 | + |
| 195 | +## Testing |
| 196 | + |
| 197 | +The project comes with three sets of tests: |
| 198 | + |
| 199 | +1. Code linting using [ESLint](https://eslint.org/). |
| 200 | +2. Unit tests using [Mocha](https://mochajs.org/). |
| 201 | +3. End-to-end tests using [blueimp/wdio](https://github.com/blueimp/wdio). |
| 202 | + |
| 203 | +To run the tests, follow these steps: |
| 204 | + |
| 205 | +1. Start [Docker](https://docs.docker.com/). |
| 206 | +2. Install development dependencies: |
| 207 | + ```sh |
| 208 | + npm install |
| 209 | + ``` |
| 210 | +3. Run the tests: |
| 211 | + ```sh |
| 212 | + npm test |
| 213 | + ``` |
| 214 | + |
| 215 | +## Support |
| 216 | + |
| 217 | +This project is actively maintained, but there is no official support channel. |
| 218 | +If you have a question that another developer might help you with, please post |
| 219 | +to |
| 220 | +[Stack Overflow](https://stackoverflow.com/questions/tagged/blueimp+jquery+file-upload) |
| 221 | +and tag your question with `blueimp jquery file upload`. |
| 222 | + |
| 223 | +## License |
| 224 | + |
| 225 | +Released under the [MIT license](https://opensource.org/licenses/MIT). |
0 commit comments