src/fileupload/static/lib/jQuery-File-Upload-10.32.0/README.md

   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, progress
  25 > 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 Web server 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.
 135 - [JavaScript Load Image library](https://github.com/blueimp/JavaScript-Load-Image)
 136   v2+: Required for the image previews and resizing functionality.
 137 - [JavaScript Canvas to Blob polyfill](https://github.com/blueimp/JavaScript-Canvas-to-Blob)
 138   v3+:Required for the resizing functionality.
 139 - [blueimp Gallery](https://github.com/blueimp/Gallery) v2+: Used to display the
 140   uploaded images in a lightbox.
 141 - [Bootstrap](https://getbootstrap.com/) v3+: Used for the demo design.
 142 - [Glyphicons](https://glyphicons.com/) Icon set used by Bootstrap.
 143
 144 ### Cross-domain requirements
 145
 146 [Cross-domain File Uploads](https://github.com/blueimp/jQuery-File-Upload/wiki/Cross-domain-uploads)
 147 using the
 148 [Iframe Transport plugin](https://github.com/blueimp/jQuery-File-Upload/blob/master/js/jquery.iframe-transport.js)
 149 require a redirect back to the origin server to retrieve the upload results. The
 150 [example implementation](https://github.com/blueimp/jQuery-File-Upload/blob/master/js/main.js)
 151 makes use of
 152 [result.html](https://github.com/blueimp/jQuery-File-Upload/blob/master/cors/result.html)
 153 as a static redirect page for the origin server.
 154
 155 The repository also includes the
 156 [jQuery XDomainRequest Transport plugin](https://github.com/blueimp/jQuery-File-Upload/blob/master/js/cors/jquery.xdr-transport.js),
 157 which enables limited cross-domain AJAX requests in Microsoft Internet Explorer
 158 8 and 9 (IE 10 supports cross-domain XHR requests).
 159 The XDomainRequest object allows GET and POST requests only and doesn't support
 160 file uploads. It is used on the
 161 [Demo](https://blueimp.github.io/jQuery-File-Upload/) to delete uploaded files
 162 from the cross-domain demo file upload service.
 163
 164 ## Browsers
 165
 166 ### Desktop browsers
 167
 168 The File Upload plugin is regularly tested with the latest browser versions and
 169 supports the following minimal versions:
 170
 171 - Google Chrome
 172 - Apple Safari 4.0+
 173 - Mozilla Firefox 3.0+
 174 - Opera 11.0+
 175 - Microsoft Internet Explorer 6.0+
 176
 177 ### Mobile browsers
 178
 179 The File Upload plugin has been tested with and supports the following mobile
 180 browsers:
 181
 182 - Apple Safari on iOS 6.0+
 183 - Google Chrome on iOS 6.0+
 184 - Google Chrome on Android 4.0+
 185 - Default Browser on Android 2.3+
 186 - Opera Mobile 12.0+
 187
 188 ### Extended browser support information
 189
 190 For a detailed overview of the features supported by each browser version and
 191 known operating system / browser bugs, please have a look at the
 192 [Extended browser support information](https://github.com/blueimp/jQuery-File-Upload/wiki/Browser-support).
 193
 194 ## Testing
 195
 196 The project comes with three sets of tests:
 197
 198 1. Code linting using [ESLint](https://eslint.org/).
 199 2. Unit tests using [Mocha](https://mochajs.org/).
 200 3. End-to-end tests using [blueimp/wdio](https://github.com/blueimp/wdio).
 201
 202 To run the tests, follow these steps:
 203
 204 1. Start [Docker](https://docs.docker.com/).
 205 2. Install development dependencies:
 206    ```sh
 207    npm install
 208    ```
 209 3. Run the tests:
 210    ```sh
 211    npm test
 212    ```
 213
 214 ## Support
 215
 216 This project is actively maintained, but there is no official support channel.
 217 If you have a question that another developer might help you with, please post
 218 to
 219 [Stack Overflow](https://stackoverflow.com/questions/tagged/blueimp+jquery+file-upload)
 220 and tag your question with `blueimp jquery file upload`.
 221
 222 ## License
 223
 224 Released under the [MIT license](https://opensource.org/licenses/MIT).