API Docs for: 3.8.0
Show:

File: file/js/file-html5.js

  1.     /**
  2.      * The FileHTML5 class provides a wrapper for a file pointer in an HTML5 The File wrapper 
  3.      * also implements the mechanics for uploading a file and tracking its progress.
  4.      * @module file-html5
  5.      */     
  6.      
  7.     /**
  8.      * The class provides a wrapper for a file pointer.
  9.      * @class FileHTML5
  10.      * @extends Base
  11.      * @constructor
  12.      * @param {Object} config Configuration object.
  13.      */
  14.     var Lang = Y.Lang,
  15.         Bind = Y.bind,
  16.         Win = Y.config.win;

  18.     var FileHTML5 = function(o) {
  19.         
  20.         var file = null;

  22.         if (FileHTML5.isValidFile(o)) {
  23.             file = o;
  24.         }
  25.         else if (FileHTML5.isValidFile(o.file)) {
  26.             file = o.file;
  27.         }
  28.         else {
  29.             file = false;
  30.         }

  32.         FileHTML5.superclass.constructor.apply(this, arguments);      
  33.         
  34.         if (file && FileHTML5.canUpload()) {
  35.            if (!this.get("file")) {
  36.                this._set("file", file);
  37.            }

  39.            if (!this.get("name")) {
  40.            this._set("name", file.name || file.fileName);
  41.            }

  43.            if (this.get("size") != (file.size || file.fileSize)) {
  44.            this._set("size", file.size || file.fileSize);
  45.            }

  47.            if (!this.get("type")) {
  48.            this._set("type", file.type);
  49.            }

  51.            if (file.hasOwnProperty("lastModifiedDate") && !this.get("dateModified")) {
  52.                this._set("dateModified", file.lastModifiedDate);
  53.            }
  54.         }
  55.     };


  58.     Y.extend(FileHTML5, Y.Base, {

  60.        /**
  61.         * Construction logic executed during FileHTML5 instantiation.
  62.         *
  63.         * @method initializer
  64.         * @protected
  65.         */
  66.         initializer : function (cfg) {
  67.             if (!this.get("id")) {
  68.                 this._set("id", Y.guid("file"));
  69.             }
  70.         },

  72.        /**
  73.         * Handler of events dispatched by the XMLHTTPRequest.
  74.         *
  75.         * @method _uploadEventHandler
  76.         * @param {Event} event The event object received from the XMLHTTPRequest.
  77.         * @protected
  78.         */      
  79.         _uploadEventHandler: function (event) {
  80.             var xhr = this.get("xhr");

  82.             switch (event.type) {
  83.                 case "progress":
  84.                   /**
  85.                    * Signals that progress has been made on the upload of this file. 
  86.                    *
  87.                    * @event uploadprogress
  88.                    * @param event {Event} The event object for the `uploadprogress` with the
  89.                    *                      following payload:
  90.                    *  <dl>
  91.                    *      <dt>originEvent</dt>
  92.                    *          <dd>The original event fired by the XMLHttpRequest instance.</dd>
  93.                    *      <dt>bytesLoaded</dt>
  94.                    *          <dd>The number of bytes of the file that has been uploaded.</dd>
  95.                    *      <dt>bytesTotal</dt>
  96.                    *          <dd>The total number of bytes in the file (the file size)</dd>
  97.                    *      <dt>percentLoaded</dt>
  98.                    *          <dd>The fraction of the file that has been uploaded, out of 100.</dd>
  99.                    *  </dl>
  100.                    */
  101.                    this.fire("uploadprogress", {originEvent: event,
  102.                                                bytesLoaded: event.loaded, 
  103.                                                bytesTotal: this.get("size"), 
  104.                                                percentLoaded: Math.min(100, Math.round(10000*event.loaded/this.get("size"))/100)
  105.                                                });
  106.                    this._set("bytesUploaded", event.loaded);
  107.                    break;

  109.                 case "load":
  110.                   /**
  111.                    * Signals that this file's upload has completed and data has been received from the server.
  112.                    *
  113.                    * @event uploadcomplete
  114.                    * @param event {Event} The event object for the `uploadcomplete` with the
  115.                    *                      following payload:
  116.                    *  <dl>
  117.                    *      <dt>originEvent</dt>
  118.                    *          <dd>The original event fired by the XMLHttpRequest instance.</dd>
  119.                    *      <dt>data</dt>
  120.                    *          <dd>The data returned by the server.</dd>
  121.                    *  </dl>
  122.                    */

  124.                    if (xhr.status >= 200 && xhr.status <= 299) {
  125.                         this.fire("uploadcomplete", {originEvent: event,
  126.                                                      data: event.target.responseText});
  127.                         var xhrupload = xhr.upload,
  128.                             boundEventHandler = this.get("boundEventHandler");
  129.     
  130.                         xhrupload.removeEventListener ("progress", boundEventHandler);
  131.                         xhrupload.removeEventListener ("error", boundEventHandler);
  132.                         xhrupload.removeEventListener ("abort", boundEventHandler);
  133.                         xhr.removeEventListener ("load", boundEventHandler); 
  134.                         xhr.removeEventListener ("error", boundEventHandler);
  135.                         xhr.removeEventListener ("readystatechange", boundEventHandler);
  136.                         
  137.                         this._set("xhr", null);
  138.                    }
  139.                    else {
  140.                         this.fire("uploaderror", {originEvent: event,
  141.                                                   status: xhr.status,
  142.                                                   statusText: xhr.statusText,
  143.                                                   source: "http"});
  144.                    }                   
  145.                    break;

  147.                 case "error":
  148.                   /**
  149.                    * Signals that this file's upload has encountered an error. 
  150.                    *
  151.                    * @event uploaderror
  152.                    * @param event {Event} The event object for the `uploaderror` with the
  153.                    *                      following payload:
  154.                    *  <dl>
  155.                    *      <dt>originEvent</dt>
  156.                    *          <dd>The original event fired by the XMLHttpRequest instance.</dd>
  157.                    *      <dt>status</dt>
  158.                    *          <dd>The status code reported by the XMLHttpRequest. If it's an HTTP error,
  159.                                   then this corresponds to the HTTP status code received by the uploader.</dd>
  160.                    *      <dt>statusText</dt>
  161.                    *          <dd>The text of the error event reported by the XMLHttpRequest instance</dd>
  162.                    *      <dt>source</dt>
  163.                    *          <dd>Either "http" (if it's an HTTP error), or "io" (if it's a network transmission 
  164.                    *              error.)</dd>
  165.                    *
  166.                    *  </dl>
  167.                    */
  168.                    this.fire("uploaderror", {originEvent: event,
  169.                                                   status: xhr.status,
  170.                                                   statusText: xhr.statusText,
  171.                                                   source: "io"});
  172.                    break;

  174.                 case "abort":

  176.                   /**
  177.                    * Signals that this file's upload has been cancelled. 
  178.                    *
  179.                    * @event uploadcancel
  180.                    * @param event {Event} The event object for the `uploadcancel` with the
  181.                    *                      following payload:
  182.                    *  <dl>
  183.                    *      <dt>originEvent</dt>
  184.                    *          <dd>The original event fired by the XMLHttpRequest instance.</dd>
  185.                    *  </dl>
  186.                    */
  187.                    this.fire("uploadcancel", {originEvent: event});
  188.                    break;

  190.                 case "readystatechange":

  192.                   /**
  193.                    * Signals that XMLHttpRequest has fired a readystatechange event. 
  194.                    *
  195.                    * @event readystatechange
  196.                    * @param event {Event} The event object for the `readystatechange` with the
  197.                    *                      following payload:
  198.                    *  <dl>
  199.                    *      <dt>readyState</dt>
  200.                    *          <dd>The readyState code reported by the XMLHttpRequest instance.</dd>
  201.                    *      <dt>originEvent</dt>
  202.                    *          <dd>The original event fired by the XMLHttpRequest instance.</dd>
  203.                    *  </dl>
  204.                    */
  205.                    this.fire("readystatechange", {readyState: event.target.readyState,
  206.                                                   originEvent: event});
  207.                    break;
  208.             }
  209.         },

  211.        /**
  212.         * Starts the upload of a specific file.
  213.         *
  214.         * @method startUpload
  215.         * @param url {String} The URL to upload the file to.
  216.         * @param parameters {Object} (optional) A set of key-value pairs to send as variables along with the file upload HTTP request.
  217.         * @param fileFieldName {String} (optional) The name of the POST variable that should contain the uploaded file ('Filedata' by default)
  218.         */
  219.         startUpload: function(url, parameters, fileFieldName) {
  220.          
  221.             this._set("bytesUploaded", 0);
  222.             
  223.             this._set("xhr", new XMLHttpRequest());
  224.             this._set("boundEventHandler", Bind(this._uploadEventHandler, this));
  225.                          
  226.             var uploadData = new FormData(),
  227.                 fileField = fileFieldName || "Filedata",
  228.                 xhr = this.get("xhr"),
  229.                 xhrupload = this.get("xhr").upload,
  230.                 boundEventHandler = this.get("boundEventHandler");

  232.             Y.each(parameters, function (value, key) {uploadData.append(key, value);});
  233.             uploadData.append(fileField, this.get("file"));




  238.             xhr.addEventListener ("loadstart", boundEventHandler, false);
  239.             xhrupload.addEventListener ("progress", boundEventHandler, false);
  240.             xhr.addEventListener ("load", boundEventHandler, false);
  241.             xhr.addEventListener ("error", boundEventHandler, false);
  242.             xhrupload.addEventListener ("error", boundEventHandler, false);
  243.             xhrupload.addEventListener ("abort", boundEventHandler, false);
  244.             xhr.addEventListener ("abort", boundEventHandler, false);
  245.             xhr.addEventListener ("loadend", boundEventHandler, false); 
  246.             xhr.addEventListener ("readystatechange", boundEventHandler, false);

  248.             xhr.open("POST", url, true);

  250.             xhr.withCredentials = this.get("xhrWithCredentials");

  252.             Y.each(this.get("xhrHeaders"), function (value, key) {
  253.                  xhr.setRequestHeader(key, value);
  254.             });

  256.             xhr.send(uploadData);
  257.       
  258.             /**
  259.              * Signals that this file's upload has started. 
  260.              *
  261.              * @event uploadstart
  262.              * @param event {Event} The event object for the `uploadstart` with the
  263.              *                      following payload:
  264.              *  <dl>
  265.              *      <dt>xhr</dt>
  266.              *          <dd>The XMLHttpRequest instance handling the file upload.</dd>
  267.              *  </dl>
  268.              */
  269.              this.fire("uploadstart", {xhr: xhr});

  271.         },

  273.        /**
  274.         * Cancels the upload of a specific file, if currently in progress.
  275.         *
  276.         * @method cancelUpload
  277.         */    
  278.         cancelUpload: function () {
  279.             this.get('xhr').abort();
  280.         }


  283.     }, {

  285.        /**
  286.         * The identity of the class.
  287.         *
  288.         * @property NAME
  289.         * @type String
  290.         * @default 'file'
  291.         * @readOnly
  292.         * @protected
  293.         * @static
  294.         */
  295.         NAME: 'file',

  297.        /**
  298.         * The type of transport.
  299.         *
  300.         * @property TYPE
  301.         * @type String
  302.         * @default 'html5'
  303.         * @readOnly
  304.         * @protected
  305.         * @static
  306.         */
  307.         TYPE: 'html5',

  309.        /**
  310.         * Static property used to define the default attribute configuration of
  311.         * the File.
  312.         *
  313.         * @property ATTRS
  314.         * @type {Object}
  315.         * @protected
  316.         * @static
  317.         */
  318.         ATTRS: {

  320.        /**
  321.         * A String containing the unique id of the file wrapped by the FileFlash instance.
  322.         * The id is supplied by the Flash player uploader.
  323.         *
  324.         * @attribute id
  325.         * @type {String}
  326.         * @initOnly
  327.         */
  328.         id: {
  329.             writeOnce: "initOnly",
  330.             value: null
  331.         },

  333.        /**
  334.         * The size of the file wrapped by FileHTML5. This value is supplied by the instance of File().
  335.         *
  336.         * @attribute size
  337.         * @type {Number}
  338.         * @initOnly
  339.         */
  340.         size: {
  341.             writeOnce: "initOnly",
  342.             value: 0
  343.         },

  345.        /**
  346.         * The name of the file wrapped by FileHTML5. This value is supplied by the instance of File().
  347.         *
  348.         * @attribute name
  349.         * @type {String}
  350.         * @initOnly
  351.         */
  352.         name: {
  353.             writeOnce: "initOnly",
  354.             value: null
  355.         },

  357.        /**
  358.         * The date that the file wrapped by FileHTML5 was created on. This value is supplied by the instance of File().
  359.         *
  360.         * @attribute dateCreated
  361.         * @type {Date}
  362.         * @initOnly
  363.         * @default null
  364.         */
  365.         dateCreated: {
  366.             writeOnce: "initOnly",
  367.             value: null
  368.         },

  370.        /**
  371.         * The date that the file wrapped by FileHTML5 was last modified on. This value is supplied by the instance of File().
  372.         *
  373.         * @attribute dateModified
  374.         * @type {Date}
  375.         * @initOnly
  376.         */
  377.         dateModified: {
  378.             writeOnce: "initOnly",
  379.             value: null
  380.         },

  382.        /**
  383.         * The number of bytes of the file that has been uploaded to the server. This value is
  384.         * non-zero only while a file is being uploaded.
  385.         *
  386.         * @attribute bytesUploaded
  387.         * @type {Date}
  388.         * @readOnly
  389.         */
  390.         bytesUploaded: {
  391.             readOnly: true,
  392.             value: 0
  393.         },

  395.        /**
  396.         * The type of the file wrapped by FileHTML. This value is provided by the instance of File()
  397.         *
  398.         * @attribute type
  399.         * @type {String}
  400.         * @initOnly
  401.         */
  402.         type: {
  403.             writeOnce: "initOnly",
  404.             value: null
  405.         },

  407.        /**
  408.         * The pointer to the instance of File() wrapped by FileHTML5.
  409.         *
  410.         * @attribute file
  411.         * @type {File}
  412.         * @initOnly
  413.         */
  414.         file: {
  415.             writeOnce: "initOnly",
  416.             value: null
  417.         },

  419.        /**
  420.         * The pointer to the instance of XMLHttpRequest used by FileHTML5 to upload the file.
  421.         *
  422.         * @attribute xhr
  423.         * @type {XMLHttpRequest}
  424.         * @initOnly
  425.         */
  426.         xhr: {
  427.             readOnly: true,
  428.             value: null
  429.         },

  431.        /**
  432.         * The dictionary of headers that should be set on the XMLHttpRequest object before
  433.         * sending it.
  434.         *
  435.         * @attribute xhrHeaders
  436.         * @type {Object}
  437.         * @initOnly
  438.         */
  439.         xhrHeaders: {
  440.             value: {}
  441.         },

  443.        /**
  444.         * A Boolean indicating whether the XMLHttpRequest should be sent with user credentials.
  445.         * This does not affect same-site requests. 
  446.         *
  447.         * @attribute xhrWithCredentials
  448.         * @type {Boolean}
  449.         * @initOnly
  450.         */
  451.         xhrWithCredentials: {
  452.             value: true
  453.         },

  455.        /**
  456.         * The bound event handler used to handle events from XMLHttpRequest.
  457.         *
  458.         * @attribute boundEventHandler
  459.         * @type {Function}
  460.         * @initOnly
  461.         */
  462.         boundEventHandler: {
  463.             readOnly: true,
  464.             value: null
  465.         }
  466.         },

  468.        /**
  469.         * Checks whether a specific native file instance is valid
  470.         *
  471.         * @method isValidFile
  472.         * @param file {File} A native File() instance.
  473.         * @static
  474.         */
  475.         isValidFile: function (file) {
  476.             return (Win && Win.File && file instanceof File);
  477.         },

  479.        /**
  480.         * Checks whether the browser has a native upload capability
  481.         * via XMLHttpRequest Level 2.
  482.         *
  483.         * @method canUpload
  484.         * @static
  485.         */
  486.         canUpload: function () {
  487.             return (Win && Win.FormData && Win.XMLHttpRequest);
  488.         }
  489.     });

  491.     Y.FileHTML5 = FileHTML5;
  492.