resources/src/mediawiki.api/mediawiki.api.upload.js

   1 /**
   2  * Provides an interface for uploading files to MediaWiki.
   3  * @class mw.Api.plugin.upload
   4  * @singleton
   5  */
   6 ( function ( mw, $ ) {
   7         var nonce = 0,
   8                 fieldsAllowed = {
   9                         stash: true,
  10                         filekey: true,
  11                         filename: true,
  12                         comment: true,
  13                         text: true,
  14                         watchlist: true,
  15                         ignorewarnings: true
  16                 };
  17
  18         /**
  19          * @private
  20          * Get nonce for iframe IDs on the page.
  21          * @return {number}
  22          */
  23         function getNonce() {
  24                 return nonce++;
  25         }
  26
  27         /**
  28          * @private
  29          * Get new iframe object for an upload.
  30          * @return {HTMLIframeElement}
  31          */
  32         function getNewIframe( id ) {
  33                 var frame = document.createElement( 'iframe' );
  34                 frame.id = id;
  35                 frame.name = id;
  36                 return frame;
  37         }
  38
  39         /**
  40          * @private
  41          * Shortcut for getting hidden inputs
  42          * @return {jQuery}
  43          */
  44         function getHiddenInput( name, val ) {
  45                 return $( '<input type="hidden" />')
  46                         .attr( 'name', name )
  47                         .val( val );
  48         }
  49
  50         /**
  51          * Parse response from an XHR to the server.
  52          * @private
  53          * @param {Event} e
  54          * @return {Object}
  55          */
  56         function parseXHRResponse( e ) {
  57                 var response;
  58
  59                 try {
  60                         response = $.parseJSON( e.target.responseText );
  61                 } catch ( error ) {
  62                         response = {
  63                                 error: {
  64                                         code: e.target.code,
  65                                         info: e.target.responseText
  66                                 }
  67                         };
  68                 }
  69
  70                 return response;
  71         }
  72
  73         /**
  74          * Process the result of the form submission, returned to an iframe.
  75          * This is the iframe's onload event.
  76          *
  77          * @param {HTMLIframeElement} iframe Iframe to extract result from
  78          * @return {Object} Response from the server. The return value may or may
  79          *   not be an XMLDocument, this code was copied from elsewhere, so if you
  80          *   see an unexpected return type, please file a bug.
  81          */
  82         function processIframeResult( iframe ) {
  83                 var json,
  84                         doc = iframe.contentDocument || frames[iframe.id].document;
  85
  86                 if ( doc.XMLDocument ) {
  87                         // The response is a document property in IE
  88                         return doc.XMLDocument;
  89                 }
  90
  91                 if ( doc.body ) {
  92                         // Get the json string
  93                         // We're actually searching through an HTML doc here --
  94                         // according to mdale we need to do this
  95                         // because IE does not load JSON properly in an iframe
  96                         json = $( doc.body ).find( 'pre' ).text();
  97
  98                         return JSON.parse( json );
  99                 }
 100
 101                 // Response is a xml document
 102                 return doc;
 103         }
 104
 105         function formDataAvailable() {
 106                 return window.FormData !== undefined &&
 107                         window.File !== undefined &&
 108                         window.File.prototype.slice !== undefined;
 109         }
 110
 111         $.extend( mw.Api.prototype, {
 112                 /**
 113                  * Upload a file to MediaWiki.
 114                  * @param {HTMLInputElement|File} file HTML input type=file element with a file already inside of it, or a File object.
 115                  * @param {Object} data Other upload options, see action=upload API docs for more
 116                  * @return {jQuery.Promise}
 117                  */
 118                 upload: function ( file, data ) {
 119                         var iframe, formData;
 120
 121                         if ( !file ) {
 122                                 return $.Deferred().reject( 'No file' );
 123                         }
 124
 125                         iframe = file.nodeType && file.nodeType === Node.ELEMENT_NODE;
 126                         formData = formDataAvailable() && file instanceof window.File;
 127
 128                         if ( !iframe && !formData ) {
 129                                 return $.Deferred().reject( 'Unsupported argument type passed to mw.Api.upload' );
 130                         }
 131
 132                         if ( formData ) {
 133                                 return this.uploadWithFormData( file, data );
 134                         }
 135
 136                         return this.uploadWithIframe( file, data );
 137                 },
 138
 139                 /**
 140                  * Upload a file to MediaWiki with an iframe and a form.
 141                  *
 142                  * This method is necessary for browsers without the File/FormData
 143                  * APIs, and continues to work in browsers with those APIs.
 144                  *
 145                  * The rough sketch of how this method works is as follows:
 146                  * * An iframe is loaded with no content.
 147                  * * A form is submitted with the passed-in file input and some extras.
 148                  * * The MediaWiki API receives that form data, and sends back a response.
 149                  * * The response is sent to the iframe, because we set target=(iframe id)
 150                  * * The response is parsed out of the iframe's document, and passed back
 151                  *   through the promise.
 152                  * @param {HTMLInputElement} file The file input with a file in it.
 153                  * @param {Object} data Other upload options, see action=upload API docs for more
 154                  * @return {jQuery.Promise}
 155                  */
 156                 uploadWithIframe: function ( file, data ) {
 157                         var key,
 158                                 tokenPromise = $.Deferred(),
 159                                 api = this,
 160                                 deferred = $.Deferred(),
 161                                 nonce = getNonce(),
 162                                 id = 'uploadframe-' + nonce,
 163                                 $form = $( '<form>' ),
 164                                 iframe = getNewIframe( id ),
 165                                 $iframe = $( iframe );
 166
 167                         for ( key in data ) {
 168                                 if ( !fieldsAllowed[key] ) {
 169                                         delete data[key];
 170                                 }
 171                         }
 172
 173                         data = $.extend( {}, this.defaults.parameters, { action: 'upload' }, data );
 174                         $form.addClass( 'mw-api-upload-form' );
 175
 176                         $form.css( 'display', 'none' )
 177                                 .attr( {
 178                                         action: this.defaults.ajax.url,
 179                                         method: 'POST',
 180                                         target: id,
 181                                         enctype: 'multipart/form-data'
 182                                 } );
 183
 184                         $iframe.one( 'load', function () {
 185                                 $iframe.one( 'load', function () {
 186                                         var result = processIframeResult( iframe );
 187
 188                                         if ( !result ) {
 189                                                 deferred.reject( 'No response from API on upload attempt.' );
 190                                         } else if ( result.error || result.warnings ) {
 191                                                 if ( result.error && result.error.code === 'badtoken' ) {
 192                                                         api.badToken( 'edit' );
 193                                                 }
 194
 195                                                 deferred.reject( result.error || result.warnings );
 196                                         } else {
 197                                                 deferred.notify( 1 );
 198                                                 deferred.resolve( result );
 199                                         }
 200                                 } );
 201                                 tokenPromise.done( function () {
 202                                         $form.submit();
 203                                 } );
 204                         } );
 205
 206                         $iframe.error( function ( error ) {
 207                                 deferred.reject( 'iframe failed to load: ' + error );
 208                         } );
 209
 210                         $iframe.prop( 'src', 'about:blank' ).hide();
 211
 212                         file.name = 'file';
 213
 214                         $.each( data, function ( key, val ) {
 215                                 $form.append( getHiddenInput( key, val ) );
 216                         } );
 217
 218                         if ( !data.filename && !data.stash ) {
 219                                 return $.Deferred().reject( 'Filename not included in file data.' );
 220                         }
 221
 222                         if ( this.needToken() ) {
 223                                 this.getEditToken().then( function ( token ) {
 224                                         $form.append( getHiddenInput( 'token', token ) );
 225                                         tokenPromise.resolve();
 226                                 }, tokenPromise.reject );
 227                         } else {
 228                                 tokenPromise.resolve();
 229                         }
 230
 231                         $( 'body' ).append( $form, $iframe );
 232
 233                         deferred.always( function () {
 234                                 $form.remove();
 235                                 $iframe.remove();
 236                         } );
 237
 238                         return deferred.promise();
 239                 },
 240
 241                 /**
 242                  * Uploads a file using the FormData API.
 243                  * @param {File} file
 244                  * @param {Object} data
 245                  */
 246                 uploadWithFormData: function ( file, data ) {
 247                         var key, xhr,
 248                                 api = this,
 249                                 formData = new FormData(),
 250                                 deferred = $.Deferred();
 251
 252                         for ( key in data ) {
 253                                 if ( !fieldsAllowed[key] ) {
 254                                         delete data[key];
 255                                 }
 256                         }
 257
 258                         data = $.extend( {}, this.defaults.parameters, { action: 'upload' }, data );
 259
 260                         $.each( data, function ( key, val ) {
 261                                 formData.append( key, val );
 262                         } );
 263
 264                         if ( !data.filename && !data.stash ) {
 265                                 return $.Deferred().reject( 'Filename not included in file data.' );
 266                         }
 267
 268                         formData.append( 'file', file );
 269
 270                         xhr = new XMLHttpRequest();
 271
 272                         xhr.upload.addEventListener( 'progress', function ( e ) {
 273                                 if ( e.lengthComputable ) {
 274                                         deferred.notify( e.loaded / e.total );
 275                                 }
 276                         }, false );
 277
 278                         xhr.addEventListener( 'abort', function ( e ) {
 279                                 deferred.reject( parseXHRResponse( e ) );
 280                         }, false );
 281
 282                         xhr.addEventListener( 'load', function ( e ) {
 283                                 var result = parseXHRResponse( e );
 284
 285                                 if ( result.error || result.warnings ) {
 286                                         if ( result.error && result.error.code === 'badtoken' ) {
 287                                                 api.badToken( 'edit' );
 288                                         }
 289
 290                                         deferred.reject( result.error || result.warnings );
 291                                 } else {
 292                                         deferred.notify( 1 );
 293                                         deferred.resolve( result );
 294                                 }
 295                         }, false );
 296
 297                         xhr.addEventListener( 'error', function ( e ) {
 298                                 deferred.reject( parseXHRResponse( e ) );
 299                         }, false );
 300
 301                         xhr.open( 'POST', this.defaults.ajax.url, true );
 302
 303                         if ( this.needToken() ) {
 304                                 this.getEditToken().then( function ( token ) {
 305                                         formData.append( 'token', token );
 306                                         xhr.send( formData );
 307                                 } );
 308                         } else {
 309                                 xhr.send( formData );
 310                         }
 311
 312                         return deferred.promise();
 313                 },
 314
 315                 /**
 316                  * Upload a file to the stash.
 317                  *
 318                  * This function will return a promise, which when resolved, will pass back a function
 319                  * to finish the stash upload. You can call that function with an argument containing
 320                  * more, or conflicting, data to pass to the server. For example:
 321                  *     // upload a file to the stash with a placeholder filename
 322                  *     api.uploadToStash( file, { filename: 'testing.png' } ).done( function ( finish ) {
 323                  *         // finish is now the function we can use to finalize the upload
 324                  *         // pass it a new filename from user input to override the initial value
 325                  *         finish( { filename: getFilenameFromUser() } ).done( function ( data ) {
 326                  *             // the upload is complete, data holds the API response
 327                  *         } );
 328                  *     } );
 329                  * @param {File|HTMLInputElement} file
 330                  * @param {Object} [data]
 331                  * @return {jQuery.Promise}
 332                  * @return {Function} return.finishStashUpload Call this function to finish the upload.
 333                  * @return {Object} return.finishStashUpload.data Additional data for the upload.
 334                  * @return {jQuery.Promise} return.finishStashUpload.return API promise for the final upload
 335                  * @return {Object} return.finishStashUpload.return.data API return value for the final upload
 336                  */
 337                 uploadToStash: function ( file, data ) {
 338                         var filekey,
 339                                 api = this;
 340
 341                         if ( !data.filename ) {
 342                                 return $.Deferred().reject( 'Filename not included in file data.' );
 343                         }
 344
 345                         function finishUpload( moreData ) {
 346                                 data = $.extend( data, moreData );
 347                                 data.filekey = filekey;
 348                                 data.action = 'upload';
 349                                 data.format = 'json';
 350
 351                                 if ( !data.filename ) {
 352                                         return $.Deferred().reject( 'Filename not included in file data.' );
 353                                 }
 354
 355                                 return api.postWithEditToken( data );
 356                         }
 357
 358                         return this.upload( file, { stash: true, filename: data.filename } ).then( function ( result ) {
 359                                 if ( result && result.upload && result.upload.filekey ) {
 360                                         filekey = result.upload.filekey;
 361                                 } else if ( result && ( result.error || result.warning ) ) {
 362                                         return $.Deferred().reject( result );
 363                                 }
 364
 365                                 return finishUpload;
 366                         } );
 367                 },
 368
 369                 needToken: function () {
 370                         return true;
 371                 }
 372         } );
 373
 374         /**
 375          * @class mw.Api
 376          * @mixins mw.Api.plugin.upload
 377          */
 378 }( mediaWiki, jQuery ) );