/**
* The YUI Uploader Control
* @module uploader
* @description <p>YUI Uploader provides file upload functionality that goes beyond the basic browser-based methods.
* Specifically, the YUI Uploader allows for:
* <ol>
* <li> Multiple file selection in a single "Open File" dialog.</li>
* <li> File extension filters to facilitate the user's selection.</li>
* <li> Progress tracking for file uploads.</li>
* <li> A range of file metadata: filename, size, date created, date modified, and author.</li>
* <li> A set of events dispatched on various aspects of the file upload process: file selection, upload progress, upload completion, etc.</li>
* <li> Inclusion of additional data in the file upload POST request.</li>
* <li> Faster file upload on broadband connections due to the modified SEND buffer size.</li>
* <li> Same-page server response upon completion of the file upload.</li>
* </ol>
* </p>
* @title Uploader
* @namespace YAHOO.widget
* @requires yahoo, dom, element, event
*/
/**
* Uploader class for the YUI Uploader component.
*
* @namespace YAHOO.widget
* @class Uploader
* @uses YAHOO.widget.FlashAdapter
* @constructor
* @param containerId {HTMLElement} Container element for the Flash Player instance.
*/
YAHOO.widget.Uploader = function(containerId)
{
YAHOO.widget.Uploader.superclass.constructor.call(this, YAHOO.widget.Uploader.SWFURL, containerId, {wmode:"transparent"});
/**
* Fires when an upload of a specific file has started.
*
* @event rollOver
* @param event.type {String} The event type
*/
this.createEvent("rollOver");
/**
* Fires when an upload of a specific file has started.
*
* @event rollOut
* @param event.type {String} The event type
*/
this.createEvent("rollOut");
/**
* Fires when an upload of a specific file has started.
*
* @event uploadStart
* @param event.type {String} The event type
*/
this.createEvent("click");
/**
* Fires when the user has finished selecting files in the "Open File" dialog.
*
* @event fileSelect
* @param event.type {String} The event type
* @param event.fileList {Array} An array of objects with file information
* @param event.fileList[].size {Number} File size in bytes for a specific file in fileList
* @param event.fileList[].cDate {Date} Creation date for a specific file in fileList
* @param event.fileList[].mDate {Date} Modification date for a specific file in fileList
* @param event.fileList[].name {String} File name for a specific file in fileList
* @param event.fileList[].id {String} Unique file id of a specific file in fileList
*/
this.createEvent("fileSelect");
/**
* Fires when an upload of a specific file has started.
*
* @event uploadStart
* @param event.type {String} The event type
* @param event.id {String} The id of the file that's started to upload
*/
this.createEvent("uploadStart");
/**
* Fires when new information about the upload progress for a specific file is available.
*
* @event uploadProgress
* @param event.type {String} The event type
* @param event.id {String} The id of the file with which the upload progress data is associated
* @param bytesLoaded {Number} The number of bytes of the file uploaded so far
* @param bytesTotal {Number} The total size of the file
*/
this.createEvent("uploadProgress");
/**
* Fires when an upload for a specific file is cancelled.
*
* @event uploadCancel
* @param event.type {String} The event type
* @param event.id {String} The id of the file with which the upload has been cancelled.
*/
this.createEvent("uploadCancel");
/**
* Fires when an upload for a specific file is complete.
*
* @event uploadComplete
* @param event.type {String} The event type
* @param event.id {String} The id of the file for which the upload has been completed.
*/
this.createEvent("uploadComplete");
/**
* Fires when the server sends data in response to a completed upload.
*
* @event uploadCompleteData
* @param event.type {String} The event type
* @param event.id {String} The id of the file for which the upload has been completed.
* @param event.data {String} The raw data returned by the server in response to the upload.
*/
this.createEvent("uploadCompleteData");
/**
* Fires when an upload error occurs.
*
* @event uploadError
* @param event.type {String} The event type
* @param event.id {String} The id of the file that was being uploaded when the error has occurred.
* @param event.status {String} The status message associated with the error.
*/
this.createEvent("uploadError");
}
/**
* Location of the Uploader SWF
*
* @property Chart.SWFURL
* @private
* @static
* @final
* @default "assets/uploader.swf"
*/
YAHOO.widget.Uploader.SWFURL = "assets/uploader.swf";
YAHOO.extend(YAHOO.widget.Uploader, YAHOO.widget.FlashAdapter,
{
/**
* Starts the upload of the file specified by fileID to the location specified by uploadScriptPath.
*
* @param fileID {String} The id of the file to start uploading.
* @param uploadScriptPath {String} The URL of the upload location.
* @param method {String} Either "GET" or "POST", specifying how the variables accompanying the file upload POST request should be submitted. "GET" by default.
* @param vars {Object} The object containing variables to be sent in the same request as the file upload.
* @param fieldName {String} The name of the variable in the POST request containing the file data. "Filedata" by default.
* @param headers {Object} An object containing variables that should be set as headers in the POST request. The following header names
* cannot be used:
* <code>
* Accept-Charset, Accept-Encoding, Accept-Ranges, Age, Allow, Allowed, Authorization, Charge-To, Connect, Connection,
* Content-Length, Content-Location, Content-Range, Cookie, Date, Delete, ETag, Expect, Get, Head, Host, Keep-Alive,
* Last-Modified, Location, Max-Forwards, Options, Post, Proxy-Authenticate, Proxy-Authorization, Proxy-Connection,
* Public, Put, Range, Referer, Request-Range, Retry-After, Server, TE, Trace, Trailer, Transfer-Encoding, Upgrade,
* URI, User-Agent, Vary, Via, Warning, WWW-Authenticate, x-flash-version.
* </code>
*/
upload: function(fileID, uploadScriptPath, method, vars, fieldName, headers)
{
this._swf.upload(fileID, uploadScriptPath, method, vars, fieldName, headers);
},
/**
* Starts uploading all files in the queue. If this function is called, the upload queue is automatically managed.
*
* @param uploadScriptPath {String} The URL of the upload location.
* @param method {String} Either "GET" or "POST", specifying how the variables accompanying the file upload POST request should be submitted. "GET" by default.
* @param vars {Object} The object containing variables to be sent in the same request as the file upload.
* @param fieldName {String} The name of the variable in the POST request containing the file data. "Filedata" by default.
* @param headers {Object} An object containing variables that should be set as headers in the POST request. The following header names
* cannot be used:
* <code>
* Accept-Charset, Accept-Encoding, Accept-Ranges, Age, Allow, Allowed, Authorization, Charge-To, Connect, Connection,
* Content-Length, Content-Location, Content-Range, Cookie, Date, Delete, ETag, Expect, Get, Head, Host, Keep-Alive,
* Last-Modified, Location, Max-Forwards, Options, Post, Proxy-Authenticate, Proxy-Authorization, Proxy-Connection,
* Public, Put, Range, Referer, Request-Range, Retry-After, Server, TE, Trace, Trailer, Transfer-Encoding, Upgrade,
* URI, User-Agent, Vary, Via, Warning, WWW-Authenticate, x-flash-version.
* </code>
*/
uploadAll: function(uploadScriptPath, method, vars, fieldName, headers)
{
this._swf.uploadAll(uploadScriptPath, method, vars, fieldName, headers);
},
/**
* Cancels the upload of a specified file. If no file id is specified, all ongoing uploads are cancelled.
*
* @param fileID {String} The ID of the file whose upload should be cancelled.
*/
cancel: function(fileID)
{
this._swf.cancel(fileID);
},
/**
* Clears the list of files queued for upload.
*
*/
clearFileList: function()
{
this._swf.clearFileList();
},
/**
* Removes the specified file from the upload queue.
*
* @param fileID {String} The id of the file to remove from the upload queue.
*/
removeFile: function (fileID)
{
this._swf.removeFile(fileID);
},
/**
* Turns the logging functionality on.
* Uses Flash internal trace logging, as well as YUI Logger, if available.
*
* @param allowLogging {Boolean} If true, logs are output; otherwise, no logs are produced.
*/
setAllowLogging: function (allowLogging)
{
this._swf.setAllowLogging(allowLogging);
},
/**
* Sets the number of simultaneous uploads when using uploadAll()
* The minimum value is 1, and maximum value is 5. The default value is 2.
*
* @param simUploadLimit {int} Number of simultaneous uploads, between 1 and 5.
*/
setSimUploadLimit : function (simUploadLimit)
{
this._swf.setSimUploadLimit(simUploadLimit);
},
/**
* Sets the flag allowing users to select multiple files for the upload.
*
* @param allowMultipleFiles {Boolean} If true, multiple files can be selected. False by default.
*/
setAllowMultipleFiles : function (allowMultipleFiles)
{
this._swf.setAllowMultipleFiles(allowMultipleFiles);
},
/**
* Sets the file filters for the "Browse" dialog.
*
* @param newFilterArray An array of sets of key-value pairs of the form
* {extensions: extensionString, description: descriptionString, [optional]macType: macTypeString}
* The extensions string is a semicolon-delimited list of elements of the form "*.xxx",
* e.g. "*.jpg;*.gif;*.png".
*/
setFileFilters : function (fileFilters)
{
this._swf.setFileFilters(fileFilters);
}
});