Uploader

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.

Module: Uploader

Table of Contents

• Constructor
• Properties
  • id
  • state
  • features
  • runtime
  • files
  • settings
  • total
• Methods
  • init()
  • setOption(option, [value])
  • getOption([option])
  • refresh()
  • start()
  • stop()
  • disableBrowse(disable)
  • getFile(id)
  • addFile(file, [fileName])
  • removeFile(file)
  • splice([start=0], [length])
  • trigger(name, Multiple)
  • hasEventListener(name)
  • bind(name, fn, [scope], [priority=0])
  • unbind(name, fn)
  • unbindAll()
  • destroy()
• Events
  • Init
  • PostInit
  • OptionChanged
  • Refresh
  • StateChanged
  • Browse
  • FileFiltered
  • QueueChanged
  • FilesAdded
  • FilesRemoved
  • BeforeUpload
  • UploadFile
  • UploadProgress
  • BeforeChunkUpload
  • ChunkUploaded
  • FileUploaded
  • UploadComplete
  • Error
  • Destroy

Constructor

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.
  • [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.
  • [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 the browse_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.
    • [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. Dispatches plupload.FILE_SIZE_ERROR.
    • [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"}. Dispatches plupload.FILE_EXTENSION_ERROR
    • [prevent_duplicates=false] Boolean
      Do not let duplicates into the queue. Dispatches plupload.FILE_DUPLICATE_ERROR.
  • [flash_swf_url] String
    URL of the Flash swf.
  • [headers] Object
    Custom headers to send with the upload. Hash of name/value pairs.
  • [http_method="POST"] String
    HTTP method to use during upload (only PUT or POST allowed).
  • [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.
  • [multipart_params] Object
    Hash of key/value pairs to send with every file upload.
  • [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 resizng of images on client-side. Applies to image/jpeg and image/png only. e.g. {width : 200, height : 200, quality : 90, crop: true}
    • [width] Number
      If image is bigger, it will be resized.
    • [height] Number
      If image is bigger, it will be resized.
    • [quality=90] Number
      Compression quality for jpegs (1-100).
    • [crop=false] Boolean
      Whether to crop images to exact dimensions. By default they will be resized proportionally.
  • [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.
  • [send_chunk_number=true] Boolean
    Whether to send chunks and chunk numbers, or total and offset bytes.
  • [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).
  • url String
    URL of the server-side upload handler.
  • [unique_names=false] Boolean
    If true will generate unique filenames for uploaded files.

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

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.

runtime

Current runtime name.

files

Current upload queue, an array of File instances.

settings

Object with name/value settings.

total

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)

getOption([option])

Get the value for the specified option or the whole configuration, if not specified.

Arguments

• [option] String
  Name of the option to get

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.

start()

Starts uploading the queued files.

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)

Returns the specified file object by id.

Arguments

• id String
  File 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 file.

Arguments

• file plupload.File|String
  File to remove from queue.

splice([start=0], [length])

Removes part of the queue and returns the files removed. This will also trigger the FilesRemoved and QueueChanged events.

Arguments

• [start=0] Number
  Start index to remove from.
• [length] Number
  Number of files to remove (defaults to number of files in the queue).

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.

destroy()

Destroys Plupload instance and cleans after itself.

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 file objects that were added to queue by the 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 the upload for the specified 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.

BeforeChunkUpload

Fires just before a chunk is uploaded. This event enables you to override settings on the uploader instance before the chunk is uploaded.

Arguments

• uploader plupload.Uploader
  Uploader instance sending the event.
• file plupload.File
  File to be uploaded.
• args Object
  POST params to be sent.
• chunkBlob Blob
  Current blob.
• offset Offset
  Current offset.

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.

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.

UploadComplete

Fires when all files in a queue are uploaded.

Arguments

• uploader plupload.Uploader
  Uploader instance sending the event.
• files Array
  Array of file objects that was added to queue/selected by the user.

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).

Destroy

Fires when destroy method is called.

Arguments

• uploader plupload.Uploader
  Uploader instance sending the event.