jQuery-File-Upload.doc

Setup instructionsSimple version using the provided example for websites running PHPThe provided example works out of the box and only needs one step for you to add it to your PHP based website:1. Download the plugin archive, extract it and upload the extracted folder (you may rename it) to your server.Visit the uploaded folders example directory - you should see a file upload interface similar to the demo, allowing you to upload files to your website.If uploading files doesnt work, make sure that the files and thumbnails directories permissions allow your server write access.Note:The provided PHP upload handler allows anyone to upload files. The uploaded files are also accessible for anyone to download.The easiest way to add some kind of authentication system is to protect the example directory by adding .htaccess based password protection.Simple version using the provided example for websites without PHP1. Implement a file upload handler on your platform (Ruby, Python, Java, etc.) that handles normal form based file uploads and upload it to your server. See also the Server-side specific tutorials on the Documentation Homepage.2. Download and extract the plugin archive.3. Edit example/index.html and adjust the action attribute of the HTML form element to the URL of your custom file upload handler. Adjust the file input name attribute if your upload handler requires another parameter name for the file uploads.4. Edit example/application.js and remove the maxChunkSize and continueAbortedUploads options (these options require support for chunked uploads on server-side).5. Upload the jQuery-File-Upload folder to your website.6. Extend your custom server-side upload handler to return a JSON response akin to the following output: name:picture.jpg,size:902604,url:/jQuery-File-Upload/example/files/picture.jpg,thumbnail:/jQuery-File-Upload/example/thumbnails/picture.jpgVisit the uploaded folders example directory - you should see a file upload interface similar to the demo, allowing you to upload files to your website.Note:The file upload plugin makes use of iframes for browsers like Microsoft Internet Explorer and Opera, which do not yet support XMLHTTPRequest uploads.Iframe based uploads require a Content-type of text/plain or text/html for the JSON response - they will offer a download dialog if the iframe response is set to application/json.Advanced version without using the provided example code1. Download the plugin archive, extract it and upload the contents without the example directory to your server.2. Add the following two lines to the head of your page (adjust the path to the jquery.fileupload-ui.css file): 3. Add the following form to the body of your page (replace upload.php with the path to your upload handler): Upload Upload files4. Add the following line to the body of your page, where you want the upload/download table to appear: 5. Add the following lines to the bottom of your page, before the closing body tag (adjust the paths to the jquery.fileupload.js and jquery.fileupload-ui.js files): 6. Create the file application.js with the following code - feel free to adjust the content returned by buildUploadRow and buildDownloadRow, as long as one tr or tbody element is returned: $(function () $(#file_upload).fileUploadUI( uploadTable: $(#files), buildUploadRow: function (files, index, handler) return $( + + + + + + Cancel + ); , buildDownloadRow: function (file, handler) return $( + + ); ););7. Implement your server-side file upload handler to store the uploaded files and return a JSON response with the file information, e.g.: name:picture.jpg,type:image/jpeg,size:123456789OptionsThe jQuery File Upload Plugin consists of a basic version (jquery.fileupload.js) providing the basic File Upload API and an additional plugin providing a user interface API (jquery.fileupload-ui.js).This page lists the various options that can be set for the plugin and examples on how to use them.Setting options on plugin initializationThe default way to set options is on plugin initialization - an example for the basic version: $(#file_upload).fileUpload( url: /path/to/upload/handler.json, sequentialUploads: true);And an example for the advanced user interface version: $(#file_upload).fileUploadUI( url: /path/to/upload/handler.json uploadTable: $(#upload_files), downloadTable: $(#download_files);Note: The advanced user interface version requires three options, as described in the Setup Guide: uploadTable buildUploadRow buildDownloadRowSetting options after plugin initializationIt is also possible to set options after plugin initialization, similar to jQuery UI widgets: $(#file_upload).fileUploadUI( option, url, /path/to/upload/handler.json);Or multiple options at once: $(#file_upload).fileUploadUI( option, url: /path/to/upload/handler.json, fieldName: file_parameter_name );Options for the basic jQuery File Upload PluginnamespaceAllows to use multiple instances of the File Upload Plugin on the same upload form.Mutliple instances of the plugin can be used on the same page without having to set different namespaces. Type: String Default: file_upload initAllows to define a function that is run after plugin initialization.Note: The File Upload UI plugin makes use of this option and provides an alternative with the initExtended option. Type: function Default: undefined destroyAllows to define a function that is run before plugin de-initialization.Note: The File Upload UI plugin makes use of this option and provides an alternative with the destroyExtended option. Type: function Default: undefined uploadFormFilterThis option allows to filter the selected forms if the plugin is called on a container with multiple forms.Accepts any parameter that is suitable for the jQuery filter method. Type: String or function or object Default: A function returning true so no forms are filtered out: function (index) return true; Example: .upload_form_1 fileInputFilterThis option allows to filter the selected file input fields if the upload form contains multiple.Accepts any parameter that is suitable for the jQuery filter method. Type: String or function or object Default: A function returning true so no file input fields are filtered out: function (index) return true; Example: .file_2 cssClassThe CSS class that is added on plugin initialization to the dropZone.The dropZone is the HTML form or HTML DOM node containing the form and defines the area on which files can be dropped. Type: String Default: file_upload dragDropSupportIf set to false, disables the drag and drop support of the plugin.This prevents the plugin from adding listeners for drag and drop events but does not prevent default browser drag and drop handling.For example, some browsers will allow to change the file input field value via drag and drop. Type: boolean Default: true dropZoneThe jQuery DOM node where files can be dropped.By default this is the element node on which the plugin is called - the upload form or the container holding the form. Type: Object Example: $(#drop_zone) urlThe url to which the file upload form is submitted.Accepts a String or a function returning a String. Type: String or function Default: A function returning the action attribute of the file upload form: function (form) return form.attr(action); Example: /path/to/upload/handler.json methodThe method of the HTTP request used to send the file(s) to the server.Can be POST (multipart/formdata file upload) or PUT (streaming file upload).Accepts a String or a function returning a String. Type: String or function Default: A function returning the method attribute of the file upload form (POST): function (form) return form.attr(method); Example: PUT fieldNameThe parameter name used to submit the file(s) to the server.Accepts a String or a function returning a String. Type: String or function Default: A function returning the name attribute of the file input field: function (input) return input.attr(name); Example: file formDataAllows to define additional parameters, that are send with the file(s) to the server url.Accepts an Array of Objects with name and value attributes, a Function returning such an Array or a simple Object.Note: Additional form data is ignored when the multipart option is set to false. Type: Array, Object or function Default: A function returning the form fields as serialized Array: function (form) return form.serializeArray(); Example: name: a, value: 1 , name: b, value: 2 requestHeadersAllows to define additional request headers, that are send with each file upload request to the server url.Accepts an Array of Objects with name and value attributes, or a simple Object.Note: Additional requestHeaders can only be added to XMLHttpRequest uploads, not to iframe based uploads.If you are making up your own HTTP header, you MUST put a X- in front of the name. Type: Array or Object Default: The basic file upload doesnt set this option (undefined), but the advanced user interface version uses the following default to make sure the server sends JSON as response type: Accept: application/json, text/javascript, */*; q=0.01 Example: name: Accept, value: application/json, text/javascript, */*; q=0.01 , name: X-CSRF-Token, value: token multipartIf set to false, streams the file content to the server url instead of sending a RFC 2388 multipart message.Non-multipart uploads are also referred to as HTTP PUT file upload.Notes:Setting the multipart option to false has only an effect on browsers supporting XHR file uploads.Form data is ignored when the multipart option is set to false. Type: boolean Default: true multiFileRequestIf set to true, uploads multiple selected files with one request instead of using one request per file.If this option is true, the index parameter used for the callBacks is undefined for browsers which support multiple file selection.Note: Uploading multiple files with one request requires the multipart option to be set to true (the default). Type: boolean Default: false withCredentialsIndicates whether or not cross-site XMLHttpRequest file uploads should be made using credentials such as cookies or authorization headers.Sets the withCredentials property on the XMLHttpRequest object. Type: boolean Default: false forceIframeUploadIf set to true, forces the use of iframes for the upload process, even if the browser is capable of XMLHttpRequest file uploads.This can be useful for cross-site file uploads, if the Access-Control-Allow-Origin header cannot be set for the server-side upload handler which is required for cross-site XMLHttpRequest file uploads. Type: boolean Default: false sequentialUploadsBy default, the plugin uploads multiple files simultaneously and asynchronously.However it is possible to force a sequential upload, that is starting the upload of the second selected file after the upload of the first one has completed, starting the upload of the third file after the second file has been uploaded and so on, by setting this option to true. Type: boolean Default: false maxChunkSizeTo upload large files in smaller chunks, set this option to a preferred maximum chunk size.If set to 0 or null, files will be uploaded as a whole. See Chunked Uploads.Notes:Only browsers supporting the Blob API will respect this setting, other browsers will always upload complete files.This setting is ignored if the option multiFileRequest is set to true. Type: integer Default: null uploadedBytesWhen a non-multipart upload or a chunked multipart upload has been aborted, this option can be used to resume the upload by setting it to the size of the already uploaded bytes. See Chunked Uploads. Type: integer Default: undefined maxFileReaderSizeThis option limits the size of files that are transferred as multipart/form-data via XHR using the FileReader interface, when the FormData interface is not available.If the file size is bigger than maxFileReaderSize, the file is submitted using the iframe method. The default maxFileReaderSize setting is 50 MB to address lockup problems in Firefox 3.6. Type: integer Default: 50000000 resumeUploadThis callback function is called before uploading the next chunk when maxChunkSize has been set.If defined, the upload resumes when the callBack parameter is called. Type: function Arguments: 1. event: XHR onload event object.2. files: Array of all File objects.3. index: The index of the current File object.4. xhr: The XMLHttpRequest object for the current file upload.5. handler: A reference to the uploadHandler, gives access to all handler methods and allows to override the current upload settings.6. callBack: The function to be called to start the next chunk upload. Example: function (event, files, index, xhr, handler, callBack) handler.url = /path/to/upload/handler.json; callBack(); onSendA callback function that is called on upload start.The jQuery File Upload UI Plugin makes use of this callback to set the progress bar to a full animated view for browsers which dont support progress events.Note: If this callback returns false the upload will not start. Type: function Arguments: 1. event: drop or input change event object.2. files: Array of all File objects.3. index: The index of the current File object.4. xhr: The XMLHttpRequest object for the current file upload. A jQuery iframe node for legacy browsers.5. handler: A reference to the uploadHandler, gives access to all handler methods and upload settings.The jQuery File Upload UI Plugin provides the attributes handler.uploadRow and gressbar with references to the uploadRow and progressbar. Example: function (event, files, index, xhr, handler) if (!xhr.upload & gressbar) gressbar( value, 100 / indeterminate progress displayed by a full animated progress bar ); onProgressA callback function that is called on upload progress.Note: This is only called for browsers which support the XMLHttpRequest object as well as XMLHttpRequestUpload. Also, the browser must support either the FormData or FileReader interfaces or the multipart option has to be set to false.The jQuery File Upload UI Plugin makes use of this callback to update the progress bar. If you override this setting, you need to update the progress bar yourself. Type: function Arguments: 1. event: XHR onprogress event object.2. files: Array of all File objects.3. index: The index of the current File object.4. xhr: The XMLHttpRequest object for the current file upload.5. handler: A reference to the uploadHandler, gives access to all handler methods and upload settings.The jQuery File Upload UI Plugin provides the attributes handler.uploadRow and gressbar with references to the uploadRow and progressbar. Default: function (event, files, index, xhr, handler) if (gressbar) gressbar( value, parseInt(event.loaded / event.total * 100, 10) ); onProgressAllA callback function that is called on overall upload progress.The jQuery File Upload UI Plugin makes use of this callback to update the overall progress bar. If you override this setting, you need to update the progress bar yourself. Type: function Arguments: 1. event: progress event object, or a similar object providing the attributes lengthComputable/loaded/total).2. list: Array of argument lists of all current uploads. Default: function (event, list) if (uploadHgressbarAll & event.lengthComputable) uploadHgressbarAgressbar( value, parseInt(event.loaded / event.total * 100, 10) ); ;onLoadA callback function that is called when the client receives the server response for the file upload.The jQuery File Upload UI Plugin