Simple Ajax Uploader - Javascript API Reference
For setup instructions and examples, visit the Github project page. To view the API reference for the included PHP class, go here.
| Name | Description |
|---|---|
| ss.SimpleUpload( options ) | Constructor |
| ss.uploadSetup( options ) | Sets default uploader options that will apply to all uploader instances. Accepts an object. |
Settings
| Name | Type | Description |
|---|---|---|
| button | Mixed Default: "" |
File upload button. Accepts either a single button (element ID string, element, or jQuery object), or an array of buttons. If an array is passed, each element in the array will work as an upload button. Required if dropzone is not set. |
| url | String Default: "" |
Location of the server-side file upload handler. Required. |
| name | String Default: "" |
Upload parameter name. Required. |
| dropzone | Mixed Default: "" |
Enable drag and drop uploading by setting this option as the element onto which files will be dragged for uploading. Accepts an element ID string, element, or jQuery object. |
| dragClass | String Default: "" |
CSS class to be applied to drop zone element when a file is dragged over. |
| customHeaders | Object Default: {} |
Additional HTTP request headers. Ex: customHeaders: { header1: 'value', header2: 'value'; } |
| customProgressHeaders | Object Default: {} |
Additional HTTP request headers to be sent with upload progress update requests in legacy browsers. Ex: customProgressHeaders: { header1: 'value', header2: 'value'; } |
| encodeHeaders | Boolean Default: true |
UTF-8 encode request headers. |
| encodeCustomHeaders Removed in v2.3 |
Boolean Default: false |
Set to true to encode the value of any custom headers added with the customHeaders option. Header values will be encoded using native encodeURIComponent() function. |
| cors | Boolean Default: false |
Set to true to enable cross-domain file uploading. More info » |
| multiple | Boolean Default: false |
Set to true to enable multiple, concurrent file uploads. |
| multipleSelect | Boolean Default: false |
Set to true to enable multiple file selection. |
| maxUploads | Integer Default: 3 |
Max number of simultaneous uploads. If the queue option is true (default), files selected after the limit is reached will be queued and then automatically uploaded as prior uploads are completed. |
| maxSize | Integer Default: false |
Maximum allowed file size (in kilobytes). Only works in browsers that support File API. |
| noParams | Boolean Default: true |
Set to false to append the file name to the url query string. |
| allowedExtensions | Array Default: [] |
Only allow file uploading for these extensions (case insensitive). Ex:
allowedExtensions: ["jpg", "jpeg", "png", "gif"]
|
| accept | String Default: "" |
Sets the value of the accept file input attribute in supporting browsers. |
| queue | Boolean Default: true |
If upload limit is reached, allow any files selected afterward to be queued and then automatically uploaded as prior uploads are completed. |
| data | Object Default: {} |
Additional data to be sent to the server. |
| multipart | Boolean Default: true |
Set to true for all files to be uploaded using multipart form method instead of direct binary stream. |
| method | String Default: "POST" |
The HTTP method to use for XHR uploads. Note: Only the POST method can be used in older browsers which rely on the iframe upload method. |
| autoSubmit | Boolean Default: true |
By default, uploads commence as soon as a file is selected. Set to false to delay the upload and instead trigger manually with the submit() function. |
| autoCalibrate | Boolean Default: true |
By default, upload buttons which are not visible upon initilization are auto reset with updatePosition() upon becoming visible. |
| responseType | String Default: "" |
The type of data you're expecting back from the server (and passed as the first argument of the onComplete() callback).Optional values: "" (empty or unrecognized string): Plain text (default). "json": Response will be evaluated as JSON and will return a Javascript object. An empty or malformed response will trigger onError() rather than onComplete(). For an empty response, return either null or {}. |
| debug | Boolean Default: false |
Set to true to log progress messages and server response in the console. |
| hoverClass | String Default: "" |
Class applied to upload button when mouse is hovered. |
| focusClass | String Default: "" |
Class applied to upload button when focused. |
| disabledClass | String Default: "" |
Class applied to button when disabled. |
| form | Mixed Default: "" |
Integrate a form with the plugin. Accepts element ID string, element, or jQuery object. See README.md for more info. |
Cross-Browser Progress Utilities
See also: Cross-Browser Upload Progress Bars with Simple Ajax Uploader
Older, non-HTML5 browsers (IE9 and older) do not support upload progress tracking. In these browsers, Simple Ajax Uploader can mimic native progress tracking by retrieving progress updates from the server as files are uploading. Three server-side options are currently supported:
| Name | Type | Description |
|---|---|---|
| nginxProgressUrl | String Default: "" |
(Nginx) The URL for reporting upload progress, as set by the module's report_uploads directive in your Nginx configuration file. |
| nginxProgressHeader | String Default: "X-Progress-ID" |
(Nginx) The header of the upload progress ID, defined by the upload_progress_header directive in your Nginx config. The module default value is "X-Progress-ID" |
| progressUrl | String Default: "" |
(PHP-APC) The location of the included uploadProgress.php file. |
| keyParamName | String Default: "APC_UPLOAD_PROGRESS" |
(PHP-APC) The name specified in PHP configuration to activate APC upload progress. This is the value of apc.rfc1867_name in PHP runtime config. (PHP default value is "APC_UPLOAD_PROGRESS")
More info at php.net |
| sessionProgressUrl | String Default: "" |
(PHP Session Progress) The location of the included sessionProgress.php file. |
| sessionProgressName | String Default: "PHP_SESSION_UPLOAD_PROGRESS" |
(PHP Session Progress) The value specified in the session.upload_progress PHP runtime option.
More info at php.net |
| checkProgressInterval | Integer Default: 50 |
Length of delay (in milliseconds) between completed progress update checks. |
| onUpdateFileSize( filesize ) | Function | This callback function serves the specific purpose of providing the upload file size in browsers that do not support the HTML5 File API. It is called after the first progress update. The function gets passed one argument: the size (in KB) of the uploaded file. |
Callback Functions
Note: When returning false from a callback to prevent an upload, the current file will remain in the queue as the next to be uploaded. To remove the current file while in a callback, use: this.removeCurrent();
| Name | Arguments | Description |
|---|---|---|
| onChange( filename, extension, uploadBtn, fileSize, file ) | filename (String), extension (String), uploadBtn (Element), fileSize (Integer), file (Object) |
Function to be called when user selects a file. The function gets passed five arguments: (1) a string containing the filename; (2) a string containing the file extension; (3) a reference to the button which triggered the upload; (4) an integer, representing the file size (null in IE9 and older); (5) the file selected to be uploaded. Return false to prevent the upload from starting. |
| onSubmit( filename, extension, uploadBtn, fileSize ) | filename (String), extension (String), uploadBtn (Element), fileSize (Integer) |
Function to be called before file is uploaded. The function gets passed four arguments, depending on browser capability: (1) a string containing the filename; (2) a string containing the file extension; (3) a reference to the button which triggered the upload; 4) an integer, representing the file size (null in IE9 and older). Return false to prevent the upload from starting. |
| onAbort( filename, uploadBtn, fileSize ) | filename (String), uploadBtn (Element), fileSize (Integer) |
Function to be called when an upload is manually aborted by clicking on an element that was passed to setAbortBtn().The function gets passed three arguments: (1) a string containing the filename; (2) a reference to the button which triggered the upload; (3) an integer, representing the file size (null in IE9 and older). |
| onProgress( pct ) | pct (Integer) |
Function to be called on the progress event in browsers that support XHR uploads. In older browsers, it will be called when server progress updates are received if progressURL is defined.The function gets passed one argument: an integer representing the upload completion percentage. |
| onComplete( filename, response, uploadBtn, fileSize ) | filename (String), response (Mixed, uploadBtn (Element), fileSize (Integer) |
Function to be called when the upload is completed. The function gets passed four arguments: (1) a string containing the filename; (2) the data returned from the server, formatted according to the responseType setting; (3) a reference to the button which triggered the upload; 4) an integer, representing the file size (null in IE9 and older).If responseType is "json", the response will be evaluated as JSON and will return a Javascript object. |
| onDone( filename, status, statusText, response, uploadBtn, fileSize ) | filename (String), status (Mixed), statusText (Mixed), response (Mixed), uploadBtn (Element), fileSize (Integer) |
Function to be called after each individual upload finishes. The function gets passsed six arguments: (1) a string containing the filename; (2) the response status code, if any; (3) the response status text, if any; (4) the data returned from the server, or false if no response; (5) a reference to the button which triggered the upload; (6) an integer, representing the file size (null in IE9 and older). |
| onAllDone() | none | Function to be called when all active uploads finish. |
| onExtError( filename, extension ) | filename (String), extension (String) |
Function to be called if the extension of a file is not permitted in the allowedExtensions option, if it is set.The function gets passsed two arguments: (1) a string containing the filename; (2) a string containing the file extension. Note: The disallowed file is removed from the queue before onExtError() is called. |
| onSizeError( filename, fileSize ) | filename (String), fileSize (Integer) |
Function to be called if the file size exceeds the limit which is set in the maxSize option, if it is set.The function gets passsed two arguments: (1) a string containing the filename; (2) an integer representing the file size. Note: The disallowed file is removed from the queue before onSizeError() is called. |
| onError( filename, errorType, status, statusText, response, uploadBtn, fileSize ) | filename (String), errorType (String), status (Mixed), statusText (Mixed), response (Mixed), uploadBtn (Element), fileSize (Integer) |
Function to be called if an error occurs during upload. The function gets passsed seven arguments: (1) a string containing the filename; (2) a string containing the error type (either "error" or "parseerror"); (3) the response status code, if any; (4) the response status text, if any; (5) the data returned from the server, or false if no response; (6) a reference to the button which triggered the upload; (7) an integer, representing the file size (null in IE9 and older). |
| startXHR( filename, fileSize, uploadBtn ) | filename (String), fileSize (Integer), uploadBtn (Element) |
Function to be called only in browsers that support XHR uploads. Called after onSubmit() but prior to upload start.The function gets passed three arguments: (1) a string containing the filename; (2) a number that is the file size in kilobytes; (3) a reference to the button which triggered the upload. Return false to prevent the upload from starting. |
| endXHR( filename, uploadBtn ) | filename (String), uploadBtn (Element) |
Function to be called only in browsers that support XHR uploads. Called after upload is completed but prior to onComplete().The function gets passed two arguments: (1) a string containing the filename; (2) a reference to the button which triggered the upload. |
| startNonXHR( filename, uploadBtn ) | filename (String, uploadBtn (Element) |
Function to be called only in browsers that do not support XHR uploads (IE9 and older). Called after onSubmit() but prior to upload start.The function gets passed two arguments: (1) a string containing the filename; (2) a reference to the button which triggered the upload. Return false to prevent the upload from starting. |
| endNonXHR( filename, uploadBtn ) | filename (String), uploadBtn (Element) |
Function to be called only in browsers that do not support XHR uploads (IE9 and older). Called after upload is completed but prior to onComplete().The function gets passed two arguments: (1) a string containing the filename; (2) a reference to the button which triggered the upload. |
Instance Methods
| Name | Parameters | Description |
|---|---|---|
| submit() | none | Begins the file upload process. Note that if autoSubmit is set to true (the default value), there is no need to manually call submit(). The upload process will begin immediately after the user selects a file. |
| destroy() | none | Completely removes upload functionality. |
| setOptions( options ) | options (Object) |
Set or change uploader options. |
| setData( data ) | data (Object) |
Replaces the data to be sent to the server. Note that all previously set data is entirely removed and replaced. |
| disable() | none | Disables upload functionality. |
| enable() | none | Restores upload functionality. |
| clearQueue() | none | Clear all files in upload queue. |
| getQueueSize() | none | Returns number of files currently waiting in queue. |
| removeCurrent() | none | Remove the currently active file from the queue. Must be called prior to the start of upload (for example, within onSubmit() or onChange()). |
| setProgressBar( element ) | element (Element) |
Designates an element to serve as an upload progress bar. The CSS width of the element will be set to 0% at the start of the upload, and then updated accordingly by percentage as the upload progresses. |
| setPctBox( element ) | element (Element) |
Designates an element to be injected with upload progress percentage. The string "0%" will be inserted at the start of the upload, and then updated accordingly as the upload progresses. |
| setFileSizeBox( element ) | element (Element) |
Designates an element to be injected with the file size of an uploading file at the start of the upload. |
| setProgressContainer( element ) | element (Element) |
Designates an element to be removed from the DOM upon completion of an upload. Useful for cleaning up dynamically created progress bars. |
| setAbortBtn( element, remove ) | element (Element), remove (Boolean)Default: false |
Designates an element to serve as an upload "cancel" button. If the second argument is true, the button will be removed from the DOM after the upload completes. |
| updatePosition() | none | Updates invisible button position. Dynamically altering elements on the page in some situations may result in invisible button misalignment. Calling updatePosition() will reset position. |
| addButton( element ) | element (Mixed) |
Designates an element to serve as upload button. Accepts either a single button (element ID string, element, or jQuery object), or an array of buttons. If an array is passed, each element in the array will work as an upload button. |
| addDZ( element ) | element (Mixed) |
Designate an element to serve as a drop zone. |
| setForm( element ) | element (Mixed) |
Designate a form to integrate with the plugin. See README.md for more info. |
Simple Ajax Uploader
More code projects from LPology