uploader.js revision e0047f099a90bbd6805761981cd17c03e354e237
/**
* Upload files to the server with support for file filtering, multiple file uploads
* and progress monitoring.
* @module uploader
*/
/**
* The Uploader widget is a tool for uploading files to the server.
* @module uploader
* @title Uploader
* @requires swf, node, event
* @namespace YAHOO.widget
*/
/**
* Creates the Uploader instance and keeps the initialization data
*
* @class Uploader
* @extends Y.Base
* @constructor
* @param {Object} config (optional) Configuration parameters for the Uploader. The following parameters are available:
* <dl>
* <dt>boundingBox : String|Node (required)</dt>
* <dd></dd>
* <dt>buttonSkin : String (optional)</dt>
* <dd></dd>
* <dt>transparent : String (optional)</dt>
* <dd></dd>
* <dt>swfURL : String (optional)</dt>
* <dd></dd>
* </dl>
*/
};
};
};
};
};
/**
* The reference to the instance of Y.SWF that encapsulates the instance of the Flash player with uploader logic.
*
* @private
* @property uploaderswf
* @type {SWF}
* @default null
*/
uploaderswf:null,
/**
* The id of this instance of uploader.
*
* @private
* @property _id
* @type {String}
*/
_id:"",
/**
* Construction logic executed during Uploader instantiation.
*
* @method initializer
* @protected
*/
initializer : function () {
flashVars: {}};
}
if (this.get("transparent")) {
}
var upswf = this.uploaderswf;
/**
* Announces that the uploader is ready and available for calling methods
* and setting properties
*
* @event uploaderReady
* @param event {Event} The event object for the uploaderReady.
*/
/**
* Fired when the mouse button is clicked on the Uploader's 'Browse' button.
*
* @event click
* @param event {Event} The event object for the click.
*/
/**
* Fires when the user has finished selecting a set of files to be uploaded.
*
* @event fileselect
* @param event {Event} The event object for the fileSelect.
* <dl>
* <dt>fileList</dt>
* <dd>The file list Object with entries in the following format:
fileList[fileID] = {id: fileID, name: fileName, cDate: fileCDate, mDate: fileMDate, size: fileSize}</dd>
* </dl>
*/
/**
* Fired when the mouse button is pressed on the Uploader's 'Browse' button.
*
* @event mousedown
* @param event {Event} The event object for the mousedown.
*/
/**
* Fired when the mouse button is raised on the Uploader's 'Browse' button.
*
* @event mouseup
* @param event {Event} The event object for the mouseup.
*/
/**
* Fired when the mouse leaves the Uploader's 'Browse' button.
*
* @event mouseleave
* @param event {Event} The event object for the mouseleave.
*/
/**
* Fired when the mouse enters the Uploader's 'Browse' button.
*
* @event mouseenter
* @param event {Event} The event object for the mouseenter.
*/
/**
* Announces that the uploader is ready and available for calling methods
* and setting properties
*
* @event uploadcancel
* @param event {Event} The event object for the uploaderReady.
* <dl>
* <dt>ddEvent</dt>
* <dd><code>drag:start</code> event from the thumb</dd>
* </dl>
*/
/**
* Fires when a specific file's upload is cancelled.
*
* @event uploadcomplete
* @param event {Event} The event object for the uploadcancel.
* <dl>
* <dt>id</dt>
* <dd>The id of the file whose upload has been cancelled.</dd>
* </dl>
*/
/**
* If the server has sent a response to the file upload, this event is
* fired and the response is added to its payload.
*
* @event uploadcompletedata
* @param event {Event} The event object for the uploadcompletedata.
* <dl>
* <dt>id</dt>
* <dd>The id of the file for which the response is being provided.</dd>
* <dt>data</dt>
* <dd>The content of the server response.</dd>
* </dl>
*/
/**
* Provides error information if an error has occurred during the upload.
*
* @event uploaderror
* @param event {Event} The event object for the uploadeerror.
* <dl>
* <dt>id</dt>
* <dd>The id of the file for which the upload error has occurred.</dd>
* <dt>status</dt>
* <dd>Relevant error information.</dd>
* </dl>
*/
/**
* Provides progress information on a specific file upload.
*
* @event uploadprogress
* @param event {Event} The event object for the uploadprogress.
* <dl>
* <dt>id</dt>
* <dd>The id of the file for which the progress information is being provided.</dd>
* <dt>bytesLoaded</dt>
* <dd>The number of bytes of the file that has been uploaded.</dd>
* <dt>bytesTotal</dt>
* <dd>The total number of bytes in the file that is being uploaded.</dd>
* </dl>
*/
/**
* Announces that the upload has been started for a specific file.
*
* @event uploadstart
* @param event {Event} The event object for the uploadstart.
* <dl>
* <dt>id</dt>
* <dd>The id of the file whose upload has been started.</dd>
* </dl>
*/
},
/**
* Removes a specific file from the upload queue.
*
* @method removeFile
* @param fileID {String} The ID of the file to be removed
* @return {Object} The updated file list, which is an object of the format:
* fileList[fileID] = {id: fileID, name: fileName, cDate: fileCDate, mDate: fileMDate, size: fileSize}
*/
},
/**
* Clears the upload queue.
*
* @method clearFileList
* @return {Boolean} This method always returns true.
*/
clearFileList : function () {
},
/**
* Starts the upload of a specific file.
*
* @method upload
* @param fileID {String} The ID of the file to be uploaded.
* @param url {String} The URL to upload the file to.
* @param method {String} (optional) The HTTP method to use for sending additional variables, either 'GET' or 'POST' ('GET' by default)
* @param postVars {Object} (optional) A set of key-value pairs to send as variables along with the file upload HTTP request.
* @param postFileVarName {String} (optional) The name of the POST variable that should contain the uploaded file ('Filedata' by default)
* @return {Boolean} This method always returns true.
*/
upload : function (fileID /*String*/, url /*String*/, method /*String*/, postVars /*Object*/, postFileVarName /*String*/) {
}
}
},
/**
* Starts the upload of a set of files, as specified in the first argument.
* The upload queue is managed automatically.
*
* @method uploadThese
* @param fileIDs {Array} The array of IDs of the files to be uploaded.
* @param url {String} The URL to upload the files to.
* @param method {String} (optional) The HTTP method to use for sending additional variables, either 'GET' or 'POST' ('GET' by default)
* @param postVars {Object} (optional) A set of key-value pairs to send as variables along with the file upload HTTP request.
* @param postFileVarName {String} (optional) The name of the POST variable that should contain the uploaded file ('Filedata' by default)
*/
uploadThese : function (fileIDs /*Array*/, url /*String*/, method /*String*/, postVars /*Object*/, postFileVarName /*String*/) {
},
/**
* Starts the upload of the files in the upload queue.
* The upload queue is managed automatically.
*
* @method uploadAll
* @param url {String} The URL to upload the files to.
* @param method {String} (optional) The HTTP method to use for sending additional variables, either 'GET' or 'POST' ('GET' by default)
* @param postVars {Object} (optional) A set of key-value pairs to send as variables along with the file upload HTTP request.
* @param postFileVarName {String} (optional) The name of the POST variable that should contain the uploaded file ('Filedata' by default).
*/
uploadAll : function (url /*String*/, method /*String*/, postVars /*Object*/, postFileVarName /*String*/) {
},
/**
* Cancels the upload of a specific file, if currently in progress.
*
* @method cancel
* @param fileID {String} (optional) The ID of the file whose upload should be cancelled. If no ID is specified, all uploads are cancelled.
*/
},
/**
* @private
* Setter for the 'log' property.
* @method setAllowLogging
* @param value {Boolean} The value for the 'log' property.
*/
},
/**
* @private
* Setter for the 'multiFiles' property.
* @method setAllowMultipleFiles
* @param value {Boolean} The value for the 'multiFiles' property.
*/
},
/**
* @private
* Setter for the 'simLimit' property.
* @method setSimUploadLimit
* @param value {Boolean} The value for the 'simLimit' property.
*/
},
/**
* @private
* Setter for the 'fileFilters' property.
* @method setFileFilters
* @param value {Boolean} The value for the 'fileFilters' property.
*/
},
/**
* Enables the uploader user input (mouse clicks on the 'Browse' button). If the button skin
* is applied, the sprite is reset from the "disabled" state.
*
* @method enable
*/
enable : function () {
},
/**
* Disables the uploader user input (mouse clicks on the 'Browse' button). If the button skin
* is applied, the sprite is set to the 'disabled' state.
*
* @method enable
*/
disable : function () {
},
/**
* @private
* Called when the uploader SWF is initialized
* @method _initializeUploader
* @param event {Object} The event to be propagated from Flash.
*/
_initializeUploader: function (event) {
this.fire("uploaderReady", {});
},
/**
* @private
* Called when an event is dispatched from Uploader
* @method _relayEvent
* @param event {Object} The event to be propagated from Flash.
*/
_relayEvent: function (event) {
},
toString: function()
{
return "Uploader " + this._id;
}
},
{
ATTRS: {
/**
* The flag that allows Flash player to
* output debug messages to its trace stack
* (if the Flash debug player is used).
*
* @attribute log
* @type {Boolean}
* @default false
*/
log: {
value: false,
setter : "setAllowLogging"
},
/**
* The flag that allows the user to select
* more than one files during the 'Browse'
* dialog (using 'Shift' or 'Ctrl' keys).
*
* @attribute multiFiles
* @type {Boolean}
* @default false
*/
multiFiles : {
value: false,
setter : "setAllowMultipleFiles"
},
/**
* The number of files that can be uploaded
* simultaneously if the automatic queue management
* is used. This value can be in the range between 2
* and 5.
*
* @attribute simLimit
* @type {Number}
* @default 2
*/
simLimit : {
value: 2,
setter : "setSimUploadLimit"
},
/**
* The array of filters on file extensions for
* the 'Browse' dialog. These filters only provide
* convenience for the user and do not strictly
* limit the selection to certain file extensions.
*
* @attribute fileFilters This attribute is an array of Objects, each
* in the following format: {description:"SomeDescription", extensions:"*.ext;*.ext;*.ext"}
* @type {Array}
* @default []
*/
fileFilters : {
value: [],
setter : "setFileFilters"
},
/**
* The Node containing the uploader's 'Browse' button.
*
* @attribute boundingBox
* @type {Node}
* @default null
* @writeOnce
*/
boundingBox : {
value: null,
writeOnce: 'initOnly'
},
/**
* The URL of the image sprite for skinning the uploader's 'Browse' button.
*
* @attribute buttonSkin
* @type {String}
* @default null
* @writeOnce
*/
buttonSkin : {
value: null,
writeOnce: 'initOnly'
},
/**
* The flag indicating whether the uploader is rendered
* with a transparent background.
*
* @attribute transparent
* @type {Boolean}
* @default true
* @writeOnce
*/
transparent : {
value: true,
writeOnce: 'initOnly'
},
/**
* The URL of the uploader's SWF.
*
* @attribute swfURL
* @type {String}
* @default "assets/uploader.swf"
* @writeOnce
*/
swfURL : {
writeOnce: 'initOnly'
}
}
}
);