Skip to content

UI.Plupload

Jump to bottom Edit New page
Davit Barbakadze edited this page Aug 6, 2017 · 16 revisions

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: UI.Plupload

Table of Contents

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.
Add a custom footer

Table of Contents

Clone this wiki locally