Important! This page is auto-generated from the comments in the source files. All changes will be overwritten! If you are looking to contribute, modify the comment in the corresponding source file instead.
Table of Contents
- Constructor
- Properties
- Methods
- init()
- setOption(option, [value])
- refresh()
- stop()
- disableBrowse(disable)
- getFile(id) (depricated: use getItem())
- addFile(file, [fileName])
- removeFile(file)
- splice(start, length)
- trigger(name, Multiple)
- hasEventListener(name)
- bind(name, fn, [scope], [priority=0])
- unbind(name, fn)
- unbindAll()
- addFileFilter(name, cb)
static
- predictRuntime(config, [runtimes])
static
- Events
Constructor
plupload.Uploader(settings)
_Arguments_
- settings
Object
For detailed information about each option check documentation.- browse_button
String|DOMElement
id of the DOM element or DOM element itself to use as file dialog trigger. - url
String
URL of the server-side upload handler. - [chunk_size=0]
Number|String
Chunk size in bytes to slice the file into. Shorcuts with b, kb, mb, gb, tb suffixes also supported.e.g. 204800 or "204800b" or "200kb"
. By default - disabled. - [send_chunk_number=true]
Boolean
Whether to send chunks and chunk numbers, or total and offset bytes. - [container]
String|DOMElement
id of the DOM element or DOM element itself that will be used to wrap uploader structures. Defaults to immediate parent of thebrowse_button
element. - [drop_element]
String|DOMElement
id of the DOM element or DOM element itself to use as a drop zone for Drag-n-Drop. - [file_data_name="file"]
String
Name for the file field in Multipart formated message. - [filters={}]
Object
Set of file type filters.- [mime_types=[]
Array
List of file types to accept, each one defined by title and list of extensions.e.g. {title : "Image files", extensions : "jpg,jpeg,gif,png"}
. Dispatchesplupload.FILE_EXTENSION_ERROR
- [max_file_size=0]
String|Number
Maximum file size that the user can pick, in bytes. Optionally supports b, kb, mb, gb, tb suffixes.e.g. "10mb" or "1gb"
. By default - not set. Dispatchesplupload.FILE_SIZE_ERROR
. - [prevent_duplicates=false]
Boolean
Do not let duplicates into the queue. Dispatchesplupload.FILE_DUPLICATE_ERROR
.
- [mime_types=[]
- [flash_swf_url]
String
URL of the Flash swf. - [headers]
Object
Custom headers to send with the upload. Hash of name/value pairs. - [max_retries=0]
Number
How many times to retry the chunk or file, before triggering Error event. - [multipart=true]
Boolean
Whether to send file and additional parameters as Multipart formated message. - [params]
Object
Hash of key/value pairs to send with every file upload. - [http_method="POST"]
String
HTTP method to use during upload (only PUT or POST allowed). - [multi_selection=true]
Boolean
Enable ability to select multiple files at once in file dialog. - [required_features]
String|Object
Either comma-separated list or hash of required features that chosen runtime should absolutely possess. - [resize]
Object
Enable resizing of images on client-side. Applies toimage/jpeg
andimage/png
only.e.g. {width : 200, height : 200, quality : 90, crop: true}
- width
Number
Resulting width - [height=width]
Number
Resulting height (optional, if not supplied will default to width) - [type='image/jpeg']
String
MIME type of the resulting image - [quality=90]
Number
In the case of JPEG, controls the quality of resulting image - [crop='cc']
Boolean
If not falsy, image will be cropped, by default from center - [fit=true]
Boolean
In case of crop whether to upscale the image to fit the exact dimensions - [preserveHeaders=true]
Boolean
Whether to preserve meta headers (on JPEGs after resize) - [resample='default']
String
Resampling algorithm to use during resize - [multipass=true]
Boolean
Whether to scale the image in steps (results in better quality)
- width
- [runtimes="html5,flash,silverlight,html4"]
String
Comma separated list of runtimes, that Plupload will try in turn, moving to the next if previous fails. - [silverlight_xap_url]
String
URL of the Silverlight xap. - [unique_names=false]
Boolean
If true will generate unique filenames for uploaded files. - [send_file_name=true]
Boolean
Whether to send file name as additional argument - 'name' (required for chunked uploads and some other cases where file name cannot be sent via normal ways).
- browse_button
Properties
id
Unique id for the Uploader instance.
state
Current state of the total uploading progress. This one can either be plupload.STARTED or plupload.STOPPED. These states are controlled by the stop/start methods. The default value is STOPPED.
features
(depricated)
Map of features that are available for the uploader runtime. Features will be filled before the init event is called, these features can then be used to alter the UI for the end user. Some of the current features that might be in this map is: dragdrop, chunks, jpgresize, pngresize.
settings
(depricated: Use `getOption()/setOption()`)
Object with name/value settings.
runtime
(depricated: There might be multiple runtimes per uploader)
Current runtime name
files
(depricated: use forEachItem(callback) to cycle over the items in the queue)
Current upload queue, an array of File instances
total
(depricated: use stats)
Total progess information. How many files has been uploaded, total percent etc.
Methods
init()
Initializes the Uploader instance and adds internal event listeners.
setOption(option, [value])
Set the value for the specified option(s).
_Arguments_
- option
String|Object
Name of the option to change or the set of key/value pairs - [value]
Mixed
Value for the option (is ignored, if first argument is object)
refresh()
Refreshes the upload instance by dispatching out a refresh event to all runtimes. This would for example reposition flash/silverlight shims on the page.
stop()
Stops the upload of the queued files.
disableBrowse(disable)
Disables/enables browse button on request.
_Arguments_
- disable
Boolean
Whether to disable or enable (default: true)
getFile(id)
(depricated: use getItem())
Returns the specified FileUploader object by id
_Arguments_
- id
String
FileUploader id to look for
addFile(file, [fileName])
Adds file to the queue programmatically. Can be native file, instance of Plupload.File, instance of mOxie.File, input[type="file"] element, or array of these. Fires FilesAdded, if any files were added to the queue. Otherwise nothing happens.
_Arguments_
- file
plupload.File|mOxie.File|File|Node|Array
File or files to add to the queue. - [fileName]
String
If specified, will be used as a name for the file
removeFile(file)
Removes a specific item from the queue
_Arguments_
- file
plupload.FileUploader|String
splice(start, length)
Removes part of the queue and returns removed files. Triggers FilesRemoved and consequently QueueChanged events.
_Arguments_
- start
Number
(Optional) Start index to remove from - length
Number
(Optional) Length of items to remove
trigger(name, Multiple)
Dispatches the specified event name and its arguments to all listeners.
_Arguments_
- name
String
Event name to fire. - Multiple
Object..
arguments to pass along to the listener functions.
hasEventListener(name)
Check whether uploader has any listeners to the specified event.
_Arguments_
- name
String
Event name to check for.
bind(name, fn, [scope], [priority=0])
Adds an event listener by name.
_Arguments_
- name
String
Event name to listen for. - fn
Function
Function to call ones the event gets fired. - [scope]
Object
Optional scope to execute the specified function in. - [priority=0]
Number
Priority of the event handler - handlers with higher priorities will be called first
unbind(name, fn)
Removes the specified event listener.
_Arguments_
- name
String
Name of event to remove. - fn
Function
Function to remove from listener.
unbindAll()
Removes all event listeners.
addFileFilter(name, cb) static
Registers a filter that will be executed for each file added to the queue. If callback returns false, file will not be added.
Callback receives two arguments: a value for the filter as it was specified in settings.filters and a file to be filtered. Callback is executed in the context of uploader instance.
_Arguments_
- name
String
Name of the filter by which it can be referenced in settings.filters - cb
String
Callback - the actual routine that every added file must pass
predictRuntime(config, [runtimes]) static
A way to predict what runtime will be choosen in the current environment with the specified settings.
_Arguments_
- config
Object|String
Plupload settings to check - [runtimes]
String
Comma-separated list of runtimes to check against
Events
Init
Fires when the current RunTime has been initialized.
_Arguments_
- uploader
plupload.Uploader
Uploader instance sending the event.
PostInit
Fires after the init event incase you need to perform actions there.
_Arguments_
- uploader
plupload.Uploader
Uploader instance sending the event.
OptionChanged
Fires when the option is changed in via uploader.setOption().
_Arguments_
- uploader
plupload.Uploader
Uploader instance sending the event. - name
String
Name of the option that was changed - value
Mixed
New value for the specified option - oldValue
Mixed
Previous value of the option
Refresh
Fires when the silverlight/flash or other shim needs to move.
_Arguments_
- uploader
plupload.Uploader
Uploader instance sending the event.
StateChanged
Fires when the overall state is being changed for the upload queue.
_Arguments_
- uploader
plupload.Uploader
Uploader instance sending the event.
Browse
Fires when browse_button is clicked and browse dialog shows.
_Arguments_
- uploader
plupload.Uploader
Uploader instance sending the event.
FileFiltered
Fires for every filtered file before it is added to the queue.
_Arguments_
- uploader
plupload.Uploader
Uploader instance sending the event. - file
plupload.File
Another file that has to be added to the queue.
QueueChanged
Fires when the file queue is changed. In other words when files are added/removed to the files array of the uploader instance.
_Arguments_
- uploader
plupload.Uploader
Uploader instance sending the event.
FilesAdded
Fires after files were filtered and added to the queue.
_Arguments_
- uploader
plupload.Uploader
Uploader instance sending the event. - files
Array
Array of FileUploader objects that were added to the queue by user.
FilesRemoved
Fires when file is removed from the queue.
_Arguments_
- uploader
plupload.Uploader
Uploader instance sending the event. - files
Array
Array of files that got removed.
BeforeUpload
Fires just before a file is uploaded. Can be used to cancel upload of the current file by returning false from the handler.
_Arguments_
- uploader
plupload.Uploader
Uploader instance sending the event. - file
plupload.File
File to be uploaded.
UploadFile
Fires when a file is to be uploaded by the runtime.
_Arguments_
- uploader
plupload.Uploader
Uploader instance sending the event. - file
plupload.File
File to be uploaded.
UploadProgress
Fires while a file is being uploaded. Use this event to update the current file upload progress.
_Arguments_
- uploader
plupload.Uploader
Uploader instance sending the event. - file
plupload.File
File that is currently being uploaded.
ChunkUploaded
Fires when file chunk is uploaded.
_Arguments_
- uploader
plupload.Uploader
Uploader instance sending the event. - file
plupload.File
File that the chunk was uploaded for. - result
Object
Object with response properties.- offset
Number
The amount of bytes the server has received so far, including this chunk. - total
Number
The size of the file. - response
String
The response body sent by the server. - status
Number
The HTTP status code sent by the server. - responseHeaders
String
All the response headers as a single string.
- offset
FileUploaded
Fires when a file is successfully uploaded.
_Arguments_
- uploader
plupload.Uploader
Uploader instance sending the event. - file
plupload.File
File that was uploaded. - result
Object
Object with response properties.- response
String
The response body sent by the server. - status
Number
The HTTP status code sent by the server. - responseHeaders
String
All the response headers as a single string.
- response
UploadComplete
Fires when all files in a queue are uploaded
_Arguments_
- uploader
plupload.Uploader
Uploader instance sending the event.
CancelUpload
Fires whenever upload is aborted for some reason
_Arguments_
- uploader
plupload.Uploader
Uploader instance sending the event.
Error
Fires when a error occurs.
_Arguments_
- uploader
plupload.Uploader
Uploader instance sending the event. - error
Object
Contains code, message and sometimes file and other details.- code
Number
The plupload error code. - message
String
Description of the error (uses i18n).
- code
Destroy
Fires when destroy method is called.
_Arguments_
- uploader
plupload.Uploader
Uploader instance sending the event.