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
• Methods
  • start()
  • stop()
  • enable()
  • disable()
  • getFile(id)
  • getFiles()
  • removeFile(file)
  • clearQueue()
  • getUploader()
  • refresh()
  • notify(type, message)
  • destroy()
• Events
  • ready
  • selected
  • removed
  • started
  • stopped
  • progress
  • uploaded
  • complete
  • viewchanged
  • error

Constructor

UI.Plupload(settings)

jQuery UI based implementation of the Plupload API - multi-runtime file uploading API.

To use the widget you must include jQuery and jQuery UI bundle (including ui.core, ui.widget, ui.button, ui.progressbar and ui.sortable).

In general the widget is designed the way that you do not usually need to do anything to it after you instantiate it. But! You still can intervenue, to some extent, in case you need to. Although, due to the fact that widget is based on jQuery UI widget factory, there are some specifics. See examples below for more details.

_Arguments_

• settings Object
  For detailed information about each option check documentation.
  • 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.
  • [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"}. Dispatches plupload.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. Dispatches plupload.FILE_SIZE_ERROR.
    • [prevent_duplicates=false] Boolean
      Do not let duplicates into the queue. Dispatches plupload.FILE_DUPLICATE_ERROR.
    • [max_file_count=0] Number
      Limit the number of files that can reside in the queue at the same time (default is 0 - no limit).
  • [flash_swf_url] String
    URL of the Flash swf.
  • [headers] Object
    Custom headers to send with the upload. Hash of name/value pairs.
  • [max_file_size] Number|String
    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.
  • [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.
  • [prevent_duplicates=false] Boolean
    Do not let duplicates into the queue. Dispatches plupload.FILE_DUPLICATE_ERROR.
  • [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.
  • [unique_names=false] Boolean
    If true will generate unique filenames for uploaded files.
  • [autostart=false] Boolean
    Whether to auto start uploading right after file selection.
  • [dragdrop=true] Boolean
    Enable ability to add file to the queue by drag'n'dropping them from the desktop.
  • [rename=false] Boolean
    Enable ability to rename files in the queue.
  • [sortable=false] Boolean
    Enable ability to sort files in the queue, changing their uploading priority.
  • [buttons] Object
    Control the visibility of functional buttons.
    • [browse=true] Boolean
      Display browse button.
    • [start=true] Boolean
      Display start button.
    • [stop=true] Boolean
      Display stop button.
  • [views] Object
    Control various views of the file queue.
    • [list=true] Boolean
      Enable list view.
    • [thumbs=false] Boolean
      Enable thumbs view.
    • [default='list'] String
      Default view.
    • [remember=true] Boolean
      Whether to remember the current view (requires jQuery Cookie plugin).
  • [multiple_queues=true] Boolean
    Re-activate the widget after each upload procedure.

_Example_

  <!-- Instantiating: -->
  <div id="uploader">
    <p>Your browser doesn't have Flash, Silverlight or HTML5 support.</p>
  </div>

  <script>
    $('#uploader').plupload({
      url : '../upload.php',
      filters : [
        {title : "Image files", extensions : "jpg,gif,png"}
      ],
      rename: true,
      sortable: true,
      flash_swf_url : '../../js/Moxie.swf',
      silverlight_xap_url : '../../js/Moxie.xap',
    });
  </script>

  // Invoking methods:
  $('#uploader').plupload(options);

  // Display welcome message in the notification area
  $('#uploader').plupload('notify', 'info', "This might be obvious, but you need to click 'Add Files' to add some files.");

  // Subscribing to the events...
  // ... on initialization:
  $('#uploader').plupload({
    ...
    viewchanged: function(event, args) {
      // stuff ...
    }
  });
  // ... or after initialization
  $('#uploader').on("viewchanged", function(event, args) {
    // stuff ...
  });

Methods

start()

Start upload. Triggers start event.

stop()

Stop upload. Triggers stop event.

enable()

Enable browse button.

disable()

Disable browse button.

getFile(id)

Retrieve file by its unique id.

_Arguments_

• id String
  Unique id of the file

getFiles()

Return array of files currently in the queue.

removeFile(file)

Remove the file from the queue.

_Arguments_

• file plupload.File|String
  File to remove, might be specified directly or by its unique id

clearQueue()

Clear the file queue.

getUploader()

Retrieve internal plupload.Uploader object (usually not required).

refresh()

Trigger refresh procedure, specifically browse_button re-measure and re-position operations. Might get handy, when UI Widget is placed within the popup, that is constantly hidden and shown again - without calling this method after each show operation, dialog trigger might get displaced and disfunctional.

notify(type, message)

Display a message in notification area.

_Arguments_

• type Enum
  Type of the message, either error or info
• message String
  The text message to display.

destroy()

Destroy the widget, the uploader, free associated resources and bring back original html.

Events

ready

Dispatched when the widget is initialized and ready.

_Arguments_

• uploader plupload.Uploader
  Uploader instance sending the event.

selected

Dispatched when file dialog is closed.

_Arguments_

• uploader plupload.Uploader
  Uploader instance sending the event.
• files Array
  Array of selected files represented by plupload.File objects

removed

Dispatched when file dialog is closed.

_Arguments_

• uploader plupload.Uploader
  Uploader instance sending the event.
• files Array
  Array of removed files represented by plupload.File objects

started

Dispatched when upload is started.

_Arguments_

• uploader plupload.Uploader
  Uploader instance sending the event.

stopped

Dispatched when upload is stopped.

_Arguments_

• uploader plupload.Uploader
  Uploader instance sending the event.

progress

Dispatched during the upload process.

_Arguments_

• uploader plupload.Uploader
  Uploader instance sending the event.
• file plupload.File
  File that is being uploaded (includes loaded and percent properties among others).
• size Number
  Total file size in bytes.
• loaded Number
  Number of bytes uploaded of the files total size.
• percent Number
  Number of percentage uploaded of the file.

uploaded

Dispatched when file is uploaded.

_Arguments_

• uploader plupload.Uploader
  Uploader instance sending the event.
• file plupload.File
  File that was uploaded.
• status Enum
  Status constant matching the plupload states QUEUED, UPLOADING, FAILED, DONE.

complete

Dispatched when upload of the whole queue is complete.

_Arguments_

• uploader plupload.Uploader
  Uploader instance sending the event.
• files Array
  Array of uploaded files represented by plupload.File objects

viewchanged

Dispatched when the view is changed, e.g. from list to thumbs or vice versa.

_Arguments_

• uploader plupload.Uploader
  Uploader instance sending the event.
• type String
  Current view type.

error

Dispatched when error of some kind is detected.

_Arguments_

• uploader plupload.Uploader
  Uploader instance sending the event.
• error String
  Error message.
• file plupload.File
  File that was uploaded.
• status Enum
  Status constant matching the plupload states QUEUED, UPLOADING, FAILED, DONE.