jssource/src_files/include/javascript/yui3/build/uploader/uploader.js

   1 /*
   2 Copyright (c) 2010, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.com/yui/license.html
   5 version: 3.3.0
   6 build: 3167
   7 */
   8 YUI.add('uploader', function(Y) {
   9
  10 /**
  11  * Upload files to the server with support for file filtering, multiple file uploads
  12  * and progress monitoring.
  13  * @module uploader
  14  */
  15
  16 var Event = Y.Event,
  17     Node = Y.Node;
  18
  19 var SWFURL = Y.Env.cdn + "uploader/assets/uploader.swf";
  20
  21 /**
  22  * The Uploader widget is a tool for uploading files to the server.
  23  * @module uploader
  24  * @title Uploader
  25  * @requires base, node, event, swf
  26  */
  27
  28 /**
  29  * Creates the Uploader instance and keeps the initialization data
  30  *
  31  * @class Uploader
  32  * @extends Y.Base
  33  * @constructor
  34  * @param {Object} config (optional) Configuration parameters for the Uploader. The following parameters are available:
  35  *        <dl>
  36  *          <dt>boundingBox : String|Node (required)</dt>
  37  *          <dd></dd>
  38  *          <dt>buttonSkin : String (optional)</dt>
  39  *          <dd></dd>
  40  *          <dt>transparent : String (optional)</dt>
  41  *          <dd></dd>
  42  *          <dt>swfURL : String (optional)</dt>
  43  *          <dd></dd>
  44  *        </dl>
  45  */
  46
  47 function Uploader (config /*Object*/) {
  48
  49         Uploader.superclass.constructor.apply(this, arguments);
  50
  51         if (config.hasOwnProperty("boundingBox")) {
  52                 this.set("boundingBox", config.boundingBox);
  53         };
  54
  55         if (config.hasOwnProperty("buttonSkin")) {
  56                 this.set("buttonSkin", config.buttonSkin);
  57         };
  58         if (config.hasOwnProperty("transparent")) {
  59                 this.set("transparent", config.transparent);
  60         };
  61         if (config.hasOwnProperty("swfURL")) {
  62                 this.set("swfURL", config.swfURL);
  63         };
  64 };
  65
  66
  67 Y.extend(Uploader, Y.Base, {
  68
  69    /**
  70     * The reference to the instance of Y.SWF that encapsulates the instance of the Flash player with uploader logic.
  71     *
  72     * @private
  73     * @property uploaderswf
  74     * @type {SWF}
  75     * @default null
  76     */
  77         uploaderswf:null,
  78
  79    /**
  80     * The id of this instance of uploader.
  81     *
  82     * @private
  83     * @property _id
  84     * @type {String}
  85     */
  86         _id:"",
  87
  88    /**
  89     * Construction logic executed during Uploader instantiation.
  90     *
  91     * @method initializer
  92     * @protected
  93     */
  94         initializer : function () {
  95
  96         this._id = Y.guid("uploader");
  97     var oElement = Node.one(this.get("boundingBox"));
  98
  99         var params = {version: "10.0.45",
 100                           fixedAttributes: {allowScriptAccess:"always", allowNetworking:"all", scale: "noscale"},
 101                       flashVars: {}};
 102
 103         if (this.get("buttonSkin") != "") {
 104                 params.flashVars["buttonSkin"] = this.get("buttonSkin");
 105         }
 106         if (this.get("transparent")) {
 107                 params.fixedAttributes["wmode"] = "transparent";
 108         }
 109
 110     this.uploaderswf = new Y.SWF(oElement, this.get("swfURL"), params);
 111
 112         var upswf = this.uploaderswf;
 113         var relEvent = Y.bind(this._relayEvent, this);
 114
 115         /**
 116         * Announces that the uploader is ready and available for calling methods
 117         * and setting properties
 118         *
 119         * @event uploaderReady
 120         * @param event {Event} The event object for the uploaderReady.
 121     */
 122         upswf.on ("swfReady", Y.bind(this._initializeUploader, this));
 123
 124         /**
 125         * Fired when the mouse button is clicked on the Uploader's 'Browse' button.
 126         *
 127         * @event click
 128         * @param event {Event} The event object for the click.
 129     */
 130         upswf.on ("click", relEvent);
 131
 132         /**
 133         * Fires when the user has finished selecting a set of files to be uploaded.
 134         *
 135         * @event fileselect
 136         * @param event {Event} The event object for the fileSelect.
 137         *  <dl>
 138         *      <dt>fileList</dt>
 139         *          <dd>The file list Object with entries in the following format:
 140                        fileList[fileID] = {id: fileID, name: fileName, cDate: fileCDate, mDate: fileMDate, size: fileSize}</dd>
 141         *  </dl>
 142     */
 143         upswf.on ("fileselect", relEvent);
 144
 145         /**
 146         * Fired when the mouse button is pressed on the Uploader's 'Browse' button.
 147         *
 148         * @event mousedown
 149         * @param event {Event} The event object for the mousedown.
 150     */
 151         upswf.on ("mousedown", relEvent);
 152
 153         /**
 154         * Fired when the mouse button is raised on the Uploader's 'Browse' button.
 155         *
 156         * @event mouseup
 157         * @param event {Event} The event object for the mouseup.
 158     */
 159         upswf.on ("mouseup", relEvent);
 160
 161         /**
 162         * Fired when the mouse leaves the Uploader's 'Browse' button.
 163         *
 164         * @event mouseleave
 165         * @param event {Event} The event object for the mouseleave.
 166     */
 167         upswf.on ("mouseleave", relEvent);
 168
 169         /**
 170         * Fired when the mouse enters the Uploader's 'Browse' button.
 171         *
 172         * @event mouseenter
 173         * @param event {Event} The event object for the mouseenter.
 174     */
 175         upswf.on ("mouseenter", relEvent);
 176
 177         /**
 178         * Announces that the uploader is ready and available for calling methods
 179         * and setting properties
 180         *
 181         * @event uploadcancel
 182         * @param event {Event} The event object for the uploaderReady.
 183         *  <dl>
 184         *      <dt>ddEvent</dt>
 185         *          <dd><code>drag:start</code> event from the thumb</dd>
 186         *  </dl>
 187     */
 188         upswf.on ("uploadcancel", relEvent);
 189
 190         /**
 191         * Fires when a specific file's upload is cancelled.
 192         *
 193         * @event uploadcomplete
 194         * @param event {Event} The event object for the uploadcancel.
 195         *  <dl>
 196         *      <dt>id</dt>
 197         *          <dd>The id of the file whose upload has been cancelled.</dd>
 198         *  </dl>
 199     */
 200         upswf.on ("uploadcomplete", relEvent);
 201
 202         /**
 203         * If the server has sent a response to the file upload, this event is
 204         * fired and the response is added to its payload.
 205         *
 206         * @event uploadcompletedata
 207         * @param event {Event} The event object for the uploadcompletedata.
 208         *  <dl>
 209         *      <dt>id</dt>
 210         *          <dd>The id of the file for which the response is being provided.</dd>
 211         *      <dt>data</dt>
 212         *          <dd>The content of the server response.</dd>
 213         *  </dl>
 214     */
 215         upswf.on ("uploadcompletedata", relEvent);
 216
 217         /**
 218         * Provides error information if an error has occurred during the upload.
 219         *
 220         * @event uploaderror
 221         * @param event {Event} The event object for the uploadeerror.
 222         *  <dl>
 223         *      <dt>id</dt>
 224         *          <dd>The id of the file for which the upload error has occurred.</dd>
 225         *      <dt>status</dt>
 226         *          <dd>Relevant error information.</dd>
 227         *  </dl>
 228     */
 229         upswf.on ("uploaderror", relEvent);
 230
 231         /**
 232         * Provides progress information on a specific file upload.
 233         *
 234         * @event uploadprogress
 235         * @param event {Event} The event object for the uploadprogress.
 236         *  <dl>
 237         *      <dt>id</dt>
 238         *          <dd>The id of the file for which the progress information is being provided.</dd>
 239         *      <dt>bytesLoaded</dt>
 240         *          <dd>The number of bytes of the file that has been uploaded.</dd>
 241         *      <dt>bytesTotal</dt>
 242         *          <dd>The total number of bytes in the file that is being uploaded.</dd>
 243         *  </dl>
 244     */
 245         upswf.on ("uploadprogress", relEvent);
 246
 247         /**
 248         * Announces that the upload has been started for a specific file.
 249         *
 250         * @event uploadstart
 251         * @param event {Event} The event object for the uploadstart.
 252         *  <dl>
 253         *      <dt>id</dt>
 254         *          <dd>The id of the file whose upload has been started.</dd>
 255         *  </dl>
 256     */
 257         upswf.on ("uploadstart", relEvent);
 258         },
 259
 260    /**
 261     * Removes a specific file from the upload queue.
 262     *
 263     * @method removeFile
 264     * @param fileID {String} The ID of the file to be removed
 265     * @return {Object} The updated file list, which is an object of the format:
 266     * fileList[fileID] = {id: fileID, name: fileName, cDate: fileCDate, mDate: fileMDate, size: fileSize}
 267     */
 268         removeFile : function (fileID /*String*/) {
 269                 return this.uploaderswf.callSWF("removeFile", [fileID]);
 270         },
 271
 272    /**
 273     * Clears the upload queue.
 274     *
 275     * @method clearFileList
 276     * @return {Boolean} This method always returns true.
 277     */
 278         clearFileList : function () {
 279                 return this.uploaderswf.callSWF("clearFileList", []);
 280         },
 281
 282    /**
 283     * Starts the upload of a specific file.
 284     *
 285     * @method upload
 286     * @param fileID {String} The ID of the file to be uploaded.
 287     * @param url {String} The URL to upload the file to.
 288     * @param method {String} (optional) The HTTP method to use for sending additional variables, either 'GET' or 'POST' ('GET' by default)
 289         * @param postVars {Object} (optional) A set of key-value pairs to send as variables along with the file upload HTTP request.
 290         * @param postFileVarName {String} (optional) The name of the POST variable that should contain the uploaded file ('Filedata' by default)
 291     * @return {Boolean} This method always returns true.
 292     */
 293         upload : function (fileID /*String*/, url /*String*/, method /*String*/, postVars /*Object*/, postFileVarName /*String*/) {
 294             if (Y.Lang.isArray(fileID)) {
 295                         return this.uploaderswf.callSWF("uploadThese", [fileID, url, method, postVars, postFileVarName]);
 296                 }
 297                 else if (Y.Lang.isString(fileID)) {
 298                         return this.uploaderswf.callSWF("upload", [fileID, url, method, postVars, postFileVarName]);
 299
 300                 }
 301         },
 302
 303    /**
 304     * Starts the upload of a set of files, as specified in the first argument.
 305     * The upload queue is managed automatically.
 306     *
 307     * @method uploadThese
 308     * @param fileIDs {Array} The array of IDs of the files to be uploaded.
 309     * @param url {String} The URL to upload the files to.
 310     * @param method {String} (optional) The HTTP method to use for sending additional variables, either 'GET' or 'POST' ('GET' by default)
 311         * @param postVars {Object} (optional) A set of key-value pairs to send as variables along with the file upload HTTP request.
 312         * @param postFileVarName {String} (optional) The name of the POST variable that should contain the uploaded file ('Filedata' by default)
 313     */
 314         uploadThese : function (fileIDs /*Array*/, url /*String*/, method /*String*/, postVars /*Object*/, postFileVarName /*String*/) {
 315                 return this.uploaderswf.callSWF("uploadThese", [fileIDs, url, method, postVars, postFileVarName]);
 316         },
 317
 318    /**
 319     * Starts the upload of the files in the upload queue.
 320     * The upload queue is managed automatically.
 321     *
 322     * @method uploadAll
 323     * @param url {String} The URL to upload the files to.
 324     * @param method {String} (optional) The HTTP method to use for sending additional variables, either 'GET' or 'POST' ('GET' by default)
 325         * @param postVars {Object} (optional) A set of key-value pairs to send as variables along with the file upload HTTP request.
 326         * @param postFileVarName {String} (optional) The name of the POST variable that should contain the uploaded file ('Filedata' by default).
 327     */
 328         uploadAll : function (url /*String*/, method /*String*/, postVars /*Object*/, postFileVarName /*String*/) {
 329                 return this.uploaderswf.callSWF("uploadAll", [url, method, postVars,postFileVarName]);
 330         },
 331
 332    /**
 333     * Cancels the upload of a specific file, if currently in progress.
 334     *
 335     * @method cancel
 336     * @param fileID {String} (optional) The ID of the file whose upload should be cancelled. If no ID is specified, all uploads are cancelled.
 337     */
 338         cancel : function (fileID /*String*/) {
 339                 return this.uploaderswf.callSWF("cancel", [fileID]);
 340         },
 341
 342         /**
 343          * @private
 344          * Setter for the 'log' property.
 345          * @method setAllowLogging
 346          * @param value {Boolean} The value for the 'log' property.
 347          */
 348         setAllowLogging : function (value /*Boolean*/) {
 349                 this.uploaderswf.callSWF("setAllowLogging", [value]);
 350         },
 351
 352         /**
 353          * @private
 354          * Setter for the 'multiFiles' property.
 355          * @method setAllowMultipleFiles
 356          * @param value {Boolean} The value for the 'multiFiles' property.
 357          */
 358         setAllowMultipleFiles : function (value /*Boolean*/) {
 359                 this.uploaderswf.callSWF("setAllowMultipleFiles", [value]);
 360         },
 361
 362         /**
 363          * @private
 364          * Setter for the 'simLimit' property.
 365          * @method setSimUploadLimit
 366          * @param value {Boolean} The value for the 'simLimit' property.
 367          */
 368         setSimUploadLimit : function (value /*int*/) {
 369                 this.uploaderswf.callSWF("setSimUploadLimit", [value]);
 370         },
 371
 372         /**
 373          * @private
 374          * Setter for the 'fileFilters' property.
 375          * @method setFileFilters
 376          * @param value {Boolean} The value for the 'fileFilters' property.
 377          */
 378         setFileFilters : function (fileFilters /*Array*/) {
 379                 this.uploaderswf.callSWF("setFileFilters", [fileFilters]);
 380         },
 381
 382    /**
 383     * Enables the uploader user input (mouse clicks on the 'Browse' button). If the button skin
 384     * is applied, the sprite is reset from the "disabled" state.
 385     *
 386     * @method enable
 387     */
 388         enable : function () {
 389                 this.uploaderswf.callSWF("enable");
 390         },
 391
 392    /**
 393     * Disables the uploader user input (mouse clicks on the 'Browse' button). If the button skin
 394     * is applied, the sprite is set to the 'disabled' state.
 395     *
 396     * @method enable
 397     */
 398         disable : function () {
 399                 this.uploaderswf.callSWF("disable");
 400         },
 401
 402         /**
 403          * @private
 404          * Called when the uploader SWF is initialized
 405          * @method _initializeUploader
 406          * @param event {Object} The event to be propagated from Flash.
 407          */
 408         _initializeUploader: function (event) {
 409                         this.publish("uploaderReady", {fireOnce:true});
 410                 this.fire("uploaderReady", {});
 411         },
 412
 413         /**
 414          * @private
 415          * Called when an event is dispatched from Uploader
 416          * @method _relayEvent
 417          * @param event {Object} The event to be propagated from Flash.
 418          */
 419         _relayEvent: function (event) {
 420                     this.fire(event.type, event);
 421         },
 422
 423         toString: function()
 424         {
 425                 return "Uploader " + this._id;
 426         }
 427
 428 },
 429 {
 430         ATTRS: {
 431         /**
 432          * The flag that allows Flash player to
 433          * output debug messages to its trace stack
 434          * (if the Flash debug player is used).
 435          *
 436          * @attribute log
 437          * @type {Boolean}
 438          * @default false
 439          */
 440                 log: {
 441                         value: false,
 442                         setter : "setAllowLogging"
 443                 },
 444
 445         /**
 446          * The flag that allows the user to select
 447          * more than one files during the 'Browse'
 448          * dialog (using 'Shift' or 'Ctrl' keys).
 449          *
 450          * @attribute multiFiles
 451          * @type {Boolean}
 452          * @default false
 453          */
 454                 multiFiles : {
 455                         value: false,
 456                         setter : "setAllowMultipleFiles"
 457                 },
 458
 459         /**
 460          * The number of files that can be uploaded
 461          * simultaneously if the automatic queue management
 462          * is used. This value can be in the range between 2
 463          * and 5.
 464          *
 465          * @attribute simLimit
 466          * @type {Number}
 467          * @default 2
 468          */
 469                 simLimit : {
 470                         value: 2,
 471                         setter : "setSimUploadLimit"
 472                 },
 473
 474         /**
 475          * The array of filters on file extensions for
 476          * the 'Browse' dialog. These filters only provide
 477          * convenience for the user and do not strictly
 478          * limit the selection to certain file extensions.
 479          * Each item in the array must contain a 'description'
 480          * property, and an 'extensions' property that must be
 481          * in the form "*.ext;*.ext;*.ext;..."
 482          *
 483          * @attribute fileFilters
 484          * @type {Array}
 485          * @default []
 486          */
 487                 fileFilters : {
 488                         value: [],
 489                         setter : "setFileFilters"
 490                 },
 491
 492         /**
 493          * The Node containing the uploader's 'Browse' button.
 494          *
 495          * @attribute boundingBox
 496          * @type {Node}
 497          * @default null
 498          * @writeOnce
 499          */
 500                 boundingBox : {
 501                         value: null,
 502                         writeOnce: 'initOnly'
 503                 },
 504
 505         /**
 506          * The URL of the image sprite for skinning the uploader's 'Browse' button.
 507          *
 508          * @attribute buttonSkin
 509          * @type {String}
 510          * @default null
 511          * @writeOnce
 512          */
 513                 buttonSkin : {
 514                         value: null,
 515                         writeOnce: 'initOnly'
 516                 },
 517
 518         /**
 519          * The flag indicating whether the uploader is rendered
 520          * with a transparent background.
 521          *
 522          * @attribute transparent
 523          * @type {Boolean}
 524          * @default true
 525          * @writeOnce
 526          */
 527                 transparent : {
 528                         value: true,
 529                         writeOnce: 'initOnly'
 530                 },
 531
 532         /**
 533          * The URL of the uploader's SWF.
 534          *
 535          * @attribute swfURL
 536          * @type {String}
 537          * @default "assets/uploader.swf"
 538          * @writeOnce
 539          */
 540                 swfURL : {
 541                         value : SWFURL,
 542                         writeOnce: 'initOnly'
 543                 }
 544
 545         }
 546 }
 547 );
 548 Y.Uploader = Uploader;
 549
 550
 551 }, '3.3.0' ,{requires:['swf', 'base', 'node', 'event']});