diff options
Diffstat (limited to 'vendor/blueimp/jquery-file-upload/README.md')
| -rw-r--r-- | vendor/blueimp/jquery-file-upload/README.md | 268 |
1 files changed, 186 insertions, 82 deletions
diff --git a/vendor/blueimp/jquery-file-upload/README.md b/vendor/blueimp/jquery-file-upload/README.md index ef839d6c7..f3ca43f3c 100644 --- a/vendor/blueimp/jquery-file-upload/README.md +++ b/vendor/blueimp/jquery-file-upload/README.md @@ -1,121 +1,225 @@ -# jQuery File Upload Plugin +# jQuery File Upload + +## Contents + +- [Description](#description) +- [Demo](#demo) +- [Features](#features) +- [Security](#security) +- [Setup](#setup) +- [Requirements](#requirements) + - [Mandatory requirements](#mandatory-requirements) + - [Optional requirements](#optional-requirements) + - [Cross-domain requirements](#cross-domain-requirements) +- [Browsers](#browsers) + - [Desktop browsers](#desktop-browsers) + - [Mobile browsers](#mobile-browsers) + - [Extended browser support information](#extended-browser-support-information) +- [Testing](#testing) +- [Support](#support) +- [License](#license) ## Description -File Upload widget with multiple file selection, drag&drop support, progress bars, validation and preview images, audio and video for jQuery. -Supports cross-domain, chunked and resumable file uploads and client-side image resizing. Works with any server-side platform (PHP, Python, Ruby on Rails, Java, Node.js, Go etc.) that supports standard HTML form file uploads. -## Demo -[Demo File Upload](https://blueimp.github.io/jQuery-File-Upload/) - -## ⚠️ Security Notice -Security related releases: - -* [v9.25.1](https://github.com/blueimp/jQuery-File-Upload/releases/tag/v9.25.1) Mitigates some [Potential vulnerabilities with PHP+ImageMagick](VULNERABILITIES.md#potential-vulnerabilities-with-php-imagemagick). -* [v9.24.1](https://github.com/blueimp/jQuery-File-Upload/releases/tag/v9.24.1) Fixes a [Remote code execution vulnerability in the PHP component](VULNERABILITIES.md#remote-code-execution-vulnerability-in-the-php-component). -* v[9.10.1](https://github.com/blueimp/jQuery-File-Upload/releases/tag/9.10.1) Fixes an [Open redirect vulnerability in the GAE components](VULNERABILITIES.md#open-redirect-vulnerability-in-the-gae-components). -* Commit [4175032](https://github.com/blueimp/jQuery-File-Upload/commit/41750323a464e848856dc4c5c940663498beb74a) (*fixed in all tagged releases*) Fixes a [Cross-site scripting vulnerability in the Iframe Transport](VULNERABILITIES.md#cross-site-scripting-vulnerability-in-the-iframe-transport). +> File Upload widget with multiple file selection, drag&drop support, +> progress bars, validation and preview images, audio and video for jQuery. +> Supports cross-domain, chunked and resumable file uploads and client-side +> image resizing. +> Works with any server-side platform (PHP, Python, Ruby on Rails, Java, +> Node.js, Go etc.) that supports standard HTML form file uploads. -Please read the [SECURITY](SECURITY.md) document for instructions on how to securely configure your Webserver for file uploads. +## Demo -## Setup -* [How to setup the plugin on your website](https://github.com/blueimp/jQuery-File-Upload/wiki/Setup) -* [How to use only the basic plugin (minimal setup guide).](https://github.com/blueimp/jQuery-File-Upload/wiki/Basic-plugin) +[Demo File Upload](https://blueimp.github.io/jQuery-File-Upload/) ## Features -* **Multiple file upload:** + +- **Multiple file upload:** Allows to select multiple files at once and upload them simultaneously. -* **Drag & Drop support:** - Allows to upload files by dragging them from your desktop or file manager and dropping them on your browser window. -* **Upload progress bar:** - Shows a progress bar indicating the upload progress for individual files and for all uploads combined. -* **Cancelable uploads:** +- **Drag & Drop support:** + Allows to upload files by dragging them from your desktop or file manager and + dropping them on your browser window. +- **Upload progress bar:** + Shows a progress bar indicating the upload progress for individual files and + for all uploads combined. +- **Cancelable uploads:** Individual file uploads can be canceled to stop the upload progress. -* **Resumable uploads:** +- **Resumable uploads:** Aborted uploads can be resumed with browsers supporting the Blob API. -* **Chunked uploads:** - Large files can be uploaded in smaller chunks with browsers supporting the Blob API. -* **Client-side image resizing:** - Images can be automatically resized on client-side with browsers supporting the required JS APIs. -* **Preview images, audio and video:** - A preview of image, audio and video files can be displayed before uploading with browsers supporting the required APIs. -* **No browser plugins (e.g. Adobe Flash) required:** - The implementation is based on open standards like HTML5 and JavaScript and requires no additional browser plugins. -* **Graceful fallback for legacy browsers:** - Uploads files via XMLHttpRequests if supported and uses iframes as fallback for legacy browsers. -* **HTML file upload form fallback:** - Allows progressive enhancement by using a standard HTML file upload form as widget element. -* **Cross-site file uploads:** - Supports uploading files to a different domain with cross-site XMLHttpRequests or iframe redirects. -* **Multiple plugin instances:** +- **Chunked uploads:** + Large files can be uploaded in smaller chunks with browsers supporting the + Blob API. +- **Client-side image resizing:** + Images can be automatically resized on client-side with browsers supporting + the required JS APIs. +- **Preview images, audio and video:** + A preview of image, audio and video files can be displayed before uploading + with browsers supporting the required APIs. +- **No browser plugins (e.g. Adobe Flash) required:** + The implementation is based on open standards like HTML5 and JavaScript and + requires no additional browser plugins. +- **Graceful fallback for legacy browsers:** + Uploads files via XMLHttpRequests if supported and uses iframes as fallback + for legacy browsers. +- **HTML file upload form fallback:** + Allows progressive enhancement by using a standard HTML file upload form as + widget element. +- **Cross-site file uploads:** + Supports uploading files to a different domain with cross-site XMLHttpRequests + or iframe redirects. +- **Multiple plugin instances:** Allows to use multiple plugin instances on the same webpage. -* **Customizable and extensible:** - Provides an API to set individual options and define callback methods for various upload events. -* **Multipart and file contents stream uploads:** - Files can be uploaded as standard "multipart/form-data" or file contents stream (HTTP PUT file upload). -* **Compatible with any server-side application platform:** - Works with any server-side platform (PHP, Python, Ruby on Rails, Java, Node.js, Go etc.) that supports standard HTML form file uploads. +- **Customizable and extensible:** + Provides an API to set individual options and define callback methods for + various upload events. +- **Multipart and file contents stream uploads:** + Files can be uploaded as standard "multipart/form-data" or file contents + stream (HTTP PUT file upload). +- **Compatible with any server-side application platform:** + Works with any server-side platform (PHP, Python, Ruby on Rails, Java, + Node.js, Go etc.) that supports standard HTML form file uploads. + +## Security + +⚠️ Please read the [VULNERABILITIES](VULNERABILITIES.md) document for a list of +fixed vulnerabilities + +Please also read the [SECURITY](SECURITY.md) document for instructions on how to +securely configure your Webserver for file uploads. + +## Setup + +jQuery File Upload can be installed via [NPM](https://www.npmjs.com/): + +```sh +npm install blueimp-file-upload +``` + +This allows you to include [jquery.fileupload.js](js/jquery.fileupload.js) and +its extensions via `node_modules`, e.g: + +```html +<script src="node_modules/blueimp-file-upload/js/jquery.fileupload.js"></script> +``` + +The widget can then be initialized on a file upload form the following way: + +```js +$('#fileupload').fileupload(); +``` + +For further information, please refer to the following guides: + +- [Main documentation page](https://github.com/blueimp/jQuery-File-Upload/wiki) +- [List of all available Options](https://github.com/blueimp/jQuery-File-Upload/wiki/Options) +- [The plugin API](https://github.com/blueimp/jQuery-File-Upload/wiki/API) +- [How to setup the plugin on your website](https://github.com/blueimp/jQuery-File-Upload/wiki/Setup) +- [How to use only the basic plugin.](https://github.com/blueimp/jQuery-File-Upload/wiki/Basic-plugin) ## Requirements ### Mandatory requirements -* [jQuery](https://jquery.com/) v. 1.6+ -* [jQuery UI widget factory](https://api.jqueryui.com/jQuery.widget/) v. 1.9+ (included): Required for the basic File Upload plugin, but very lightweight without any other dependencies from the jQuery UI suite. -* [jQuery Iframe Transport plugin](https://github.com/blueimp/jQuery-File-Upload/blob/master/js/jquery.iframe-transport.js) (included): Required for [browsers without XHR file upload support](https://github.com/blueimp/jQuery-File-Upload/wiki/Browser-support). + +- [jQuery](https://jquery.com/) v1.6+ +- [jQuery UI widget factory](https://api.jqueryui.com/jQuery.widget/) v1.9+ + (included): Required for the basic File Upload plugin, but very lightweight + without any other dependencies from the jQuery UI suite. +- [jQuery Iframe Transport plugin](https://github.com/blueimp/jQuery-File-Upload/blob/master/js/jquery.iframe-transport.js) + (included): Required for + [browsers without XHR file upload support](https://github.com/blueimp/jQuery-File-Upload/wiki/Browser-support). ### Optional requirements -* [JavaScript Templates engine](https://github.com/blueimp/JavaScript-Templates) v. 2.5.4+: Used to render the selected and uploaded files for the Basic Plus UI and jQuery UI versions. -* [JavaScript Load Image library](https://github.com/blueimp/JavaScript-Load-Image) v. 1.13.0+: Required for the image previews and resizing functionality. -* [JavaScript Canvas to Blob polyfill](https://github.com/blueimp/JavaScript-Canvas-to-Blob) v. 2.1.1+:Required for the image previews and resizing functionality. -* [blueimp Gallery](https://github.com/blueimp/Gallery) v. 2.15.1+: Used to display the uploaded images in a lightbox. -* [Bootstrap](http://getbootstrap.com/) v. 3.2.0+ -* [Glyphicons](http://glyphicons.com/) -The user interface of all versions, except the jQuery UI version, is built with [Bootstrap](http://getbootstrap.com/) and icons from [Glyphicons](http://glyphicons.com/). +- [JavaScript Templates engine](https://github.com/blueimp/JavaScript-Templates) + v3+: Used to render the selected and uploaded files for the Basic Plus UI and + jQuery UI versions. +- [JavaScript Load Image library](https://github.com/blueimp/JavaScript-Load-Image) + v2+: Required for the image previews and resizing functionality. +- [JavaScript Canvas to Blob polyfill](https://github.com/blueimp/JavaScript-Canvas-to-Blob) + v3+:Required for the image previews and resizing functionality. +- [blueimp Gallery](https://github.com/blueimp/Gallery) v2+: Used to display the + uploaded images in a lightbox. +- [Bootstrap](https://getbootstrap.com/) v3+: Used for the demo design. +- [Glyphicons](https://glyphicons.com/) Icon set used by Bootstrap. ### Cross-domain requirements -[Cross-domain File Uploads](https://github.com/blueimp/jQuery-File-Upload/wiki/Cross-domain-uploads) using the [Iframe Transport plugin](https://github.com/blueimp/jQuery-File-Upload/blob/master/js/jquery.iframe-transport.js) require a redirect back to the origin server to retrieve the upload results. The [example implementation](https://github.com/blueimp/jQuery-File-Upload/blob/master/js/main.js) makes use of [result.html](https://github.com/blueimp/jQuery-File-Upload/blob/master/cors/result.html) as a static redirect page for the origin server. - -The repository also includes the [jQuery XDomainRequest Transport plugin](https://github.com/blueimp/jQuery-File-Upload/blob/master/js/cors/jquery.xdr-transport.js), which enables limited cross-domain AJAX requests in Microsoft Internet Explorer 8 and 9 (IE 10 supports cross-domain XHR requests). -The XDomainRequest object allows GET and POST requests only and doesn't support file uploads. It is used on the [Demo](https://blueimp.github.io/jQuery-File-Upload/) to delete uploaded files from the cross-domain demo file upload service. - -### Custom Backends -You can add support for various backends by adhering to the specification [outlined here](https://github.com/blueimp/jQuery-File-Upload/wiki/JSON-Response). +[Cross-domain File Uploads](https://github.com/blueimp/jQuery-File-Upload/wiki/Cross-domain-uploads) +using the +[Iframe Transport plugin](https://github.com/blueimp/jQuery-File-Upload/blob/master/js/jquery.iframe-transport.js) +require a redirect back to the origin server to retrieve the upload results. The +[example implementation](https://github.com/blueimp/jQuery-File-Upload/blob/master/js/main.js) +makes use of +[result.html](https://github.com/blueimp/jQuery-File-Upload/blob/master/cors/result.html) +as a static redirect page for the origin server. + +The repository also includes the +[jQuery XDomainRequest Transport plugin](https://github.com/blueimp/jQuery-File-Upload/blob/master/js/cors/jquery.xdr-transport.js), +which enables limited cross-domain AJAX requests in Microsoft Internet Explorer +8 and 9 (IE 10 supports cross-domain XHR requests). +The XDomainRequest object allows GET and POST requests only and doesn't support +file uploads. It is used on the +[Demo](https://blueimp.github.io/jQuery-File-Upload/) to delete uploaded files +from the cross-domain demo file upload service. ## Browsers ### Desktop browsers -The File Upload plugin is regularly tested with the latest browser versions and supports the following minimal versions: -* Google Chrome -* Apple Safari 4.0+ -* Mozilla Firefox 3.0+ -* Opera 11.0+ -* Microsoft Internet Explorer 6.0+ +The File Upload plugin is regularly tested with the latest browser versions and +supports the following minimal versions: + +- Google Chrome +- Apple Safari 4.0+ +- Mozilla Firefox 3.0+ +- Opera 11.0+ +- Microsoft Internet Explorer 6.0+ ### Mobile browsers -The File Upload plugin has been tested with and supports the following mobile browsers: -* Apple Safari on iOS 6.0+ (see Caveats below) -* Google Chrome on iOS 6.0+ (see Caveats below) -* Google Chrome on Android 4.0+ -* Default Browser on Android 2.3+ -* Opera Mobile 12.0+ +The File Upload plugin has been tested with and supports the following mobile +browsers: + +- Apple Safari on iOS 6.0+ +- Google Chrome on iOS 6.0+ +- Google Chrome on Android 4.0+ +- Default Browser on Android 2.3+ +- Opera Mobile 12.0+ + +### Extended browser support information + +For a detailed overview of the features supported by each browser version and +known operating system / browser bugs, please have a look at the +[Extended browser support information](https://github.com/blueimp/jQuery-File-Upload/wiki/Browser-support). -### Caveats +## Testing -- iOS 9 has a [known bug](https://apple.stackexchange.com/questions/118154) where photos chosen from the Photo Library are all given the name `image.jpeg`, which is problematic when uploading multiple files at a time. Ideally your server should be responsible for deduplicating file uploads ([example](https://github.com/blueimp/jQuery-File-Upload/blob/master/server/php/UploadHandler.php#L490)). If you don't have control, as in the case of direct uploads to S3, you can pass an option `uniqueFilenames: {}` as part of the options object, which tells the uploader to deduplicate filenames. More details [here](https://github.com/blueimp/jQuery-File-Upload/commit/d419f43478aeafe95a794815f80a3016f58eb3b7). +The project comes with three sets of tests: -### Supported features -For a detailed overview of the features supported by each browser version, please have a look at the [Extended browser support information](https://github.com/blueimp/jQuery-File-Upload/wiki/Browser-support). +1. Code linting using [ESLint](https://eslint.org/). +2. Unit tests using [Mocha](https://mochajs.org/). +3. End-to-end tests using [blueimp/wdio](https://github.com/blueimp/wdio). -## Contributing -**Bug fixes** and **new features** can be proposed using [pull requests](https://github.com/blueimp/jQuery-File-Upload/pulls). -Please read the [contribution guidelines](https://github.com/blueimp/jQuery-File-Upload/blob/master/CONTRIBUTING.md) before submitting a pull request. +To run the tests, follow these steps: + +1. Start [Docker](https://docs.docker.com/). +2. Install development dependencies: + ```sh + npm install + ``` +3. Run the tests: + ```sh + npm test + ``` ## Support + This project is actively maintained, but there is no official support channel. -If you have a question that another developer might help you with, please post to [Stack Overflow](http://stackoverflow.com/questions/tagged/blueimp+jquery+file-upload) and tag your question with `blueimp jquery file upload`. +If you have a question that another developer might help you with, please post +to +[Stack Overflow](https://stackoverflow.com/questions/tagged/blueimp+jquery+file-upload) +and tag your question with `blueimp jquery file upload`. ## License + Released under the [MIT license](https://opensource.org/licenses/MIT). |