resources/src/mediawiki/mediawiki.Upload.js

   1 ( function ( mw, $ ) {
   2         var UP;
   3
   4         /**
   5          * @class mw.Upload
   6          *
   7          * Used to represent an upload in progress on the frontend.
   8          * Most of the functionality is implemented in mw.Api.plugin.upload,
   9          * but this model class will tie it together as well as let you perform
  10          * actions in a logical way.
  11          *
  12          * A simple example:
  13          *
  14          *     var file = new OO.ui.SelectFileWidget(),
  15          *       button = new OO.ui.ButtonWidget( { label: 'Save' } ),
  16          *       upload = new mw.Upload;
  17          *
  18          *     button.on( 'click', function () {
  19          *       upload.setFile( file.getValue() );
  20          *       upload.setFilename( file.getValue().name );
  21          *       upload.upload();
  22          *     } );
  23          *
  24          *     $( 'body' ).append( file.$element, button.$element );
  25          *
  26          * You can also choose to {@link #uploadToStash stash the upload} and
  27          * {@link #finishStashUpload finalize} it later:
  28          *
  29          *     var file, // Some file object
  30          *       upload = new mw.Upload,
  31          *       stashPromise = $.Deferred();
  32          *
  33          *     upload.setFile( file );
  34          *     upload.uploadToStash().then( function () {
  35          *       stashPromise.resolve();
  36          *     } );
  37          *
  38          *     stashPromise.then( function () {
  39          *       upload.setFilename( 'foo' );
  40          *       upload.setText( 'bar' );
  41          *       upload.finishStashUpload().then( function () {
  42          *         console.log( 'Done!' );
  43          *       } );
  44          *     } );
  45          *
  46          * @constructor
  47          * @param {Object|mw.Api} [apiconfig] A mw.Api object (or subclass), or configuration
  48          *     to pass to the constructor of mw.Api.
  49          */
  50         function Upload( apiconfig ) {
  51                 this.api = ( apiconfig instanceof mw.Api ) ? apiconfig : new mw.Api( apiconfig );
  52
  53                 this.watchlist = false;
  54                 this.text = '';
  55                 this.comment = '';
  56                 this.filename = null;
  57                 this.file = null;
  58                 this.state = Upload.State.NEW;
  59
  60                 this.imageinfo = undefined;
  61         }
  62
  63         UP = Upload.prototype;
  64
  65         /**
  66          * Set the text of the file page, to be created on file upload.
  67          *
  68          * @param {string} text
  69          */
  70         UP.setText = function ( text ) {
  71                 this.text = text;
  72         };
  73
  74         /**
  75          * Set the filename, to be finalized on upload.
  76          *
  77          * @param {string} filename
  78          */
  79         UP.setFilename = function ( filename ) {
  80                 this.filename = filename;
  81         };
  82
  83         /**
  84          * Sets the filename based on the filename as it was on the upload.
  85          */
  86         UP.setFilenameFromFile = function () {
  87                 var file = this.getFile();
  88                 if ( file.nodeType && file.nodeType === Node.ELEMENT_NODE ) {
  89                         // File input element, use getBasename to cut out the path
  90                         this.setFilename( this.getBasename( file.value ) );
  91                 } else if ( file.name && file.lastModified ) {
  92                         // HTML5 FileAPI File object, but use getBasename to be safe
  93                         this.setFilename( this.getBasename( file.name ) );
  94                 }
  95         };
  96
  97         /**
  98          * Set the file to be uploaded.
  99          *
 100          * @param {HTMLInputElement|File} file
 101          */
 102         UP.setFile = function ( file ) {
 103                 this.file = file;
 104         };
 105
 106         /**
 107          * Set whether the file should be watchlisted after upload.
 108          *
 109          * @param {boolean} watchlist
 110          */
 111         UP.setWatchlist = function ( watchlist ) {
 112                 this.watchlist = watchlist;
 113         };
 114
 115         /**
 116          * Set the edit comment for the upload.
 117          *
 118          * @param {string} comment
 119          */
 120         UP.setComment = function ( comment ) {
 121                 this.comment = comment;
 122         };
 123
 124         /**
 125          * Get the text of the file page, to be created on file upload.
 126          *
 127          * @return {string}
 128          */
 129         UP.getText = function () {
 130                 return this.text;
 131         };
 132
 133         /**
 134          * Get the filename, to be finalized on upload.
 135          *
 136          * @return {string}
 137          */
 138         UP.getFilename = function () {
 139                 return this.filename;
 140         };
 141
 142         /**
 143          * Get the file being uploaded.
 144          *
 145          * @return {HTMLInputElement|File}
 146          */
 147         UP.getFile = function () {
 148                 return this.file;
 149         };
 150
 151         /**
 152          * Get the boolean for whether the file will be watchlisted after upload.
 153          *
 154          * @return {boolean}
 155          */
 156         UP.getWatchlist = function () {
 157                 return this.watchlist;
 158         };
 159
 160         /**
 161          * Get the current value of the edit comment for the upload.
 162          *
 163          * @return {string}
 164          */
 165         UP.getComment = function () {
 166                 return this.comment;
 167         };
 168
 169         /**
 170          * Gets the base filename from a path name.
 171          *
 172          * @param {string} path
 173          * @return {string}
 174          */
 175         UP.getBasename = function ( path ) {
 176                 if ( path === undefined || path === null ) {
 177                         return '';
 178                 }
 179
 180                 // Find the index of the last path separator in the
 181                 // path, and add 1. Then, take the entire string after that.
 182                 return path.slice(
 183                         Math.max(
 184                                 path.lastIndexOf( '/' ),
 185                                 path.lastIndexOf( '\\' )
 186                         ) + 1
 187                 );
 188         };
 189
 190         /**
 191          * Gets the state of the upload.
 192          *
 193          * @return {mw.Upload.State}
 194          */
 195         UP.getState = function () {
 196                 return this.state;
 197         };
 198
 199         /**
 200          * Get the imageinfo object for the finished upload.
 201          * Only available once the upload is finished! Don't try to get it
 202          * beforehand.
 203          *
 204          * @return {Object|undefined}
 205          */
 206         UP.getImageInfo = function () {
 207                 return this.imageinfo;
 208         };
 209
 210         /**
 211          * Upload the file directly.
 212          *
 213          * @return {jQuery.Promise}
 214          */
 215         UP.upload = function () {
 216                 var upload = this;
 217
 218                 if ( !this.getFile() ) {
 219                         return $.Deferred().reject( 'No file to upload. Call setFile to add one.' );
 220                 }
 221
 222                 if ( !this.getFilename() ) {
 223                         return $.Deferred().reject( 'No filename set. Call setFilename to add one.' );
 224                 }
 225
 226                 this.state = Upload.State.UPLOADING;
 227
 228                 return this.api.upload( this.getFile(), {
 229                         watchlist: ( this.getWatchlist() ) ? 1 : undefined,
 230                         comment: this.getComment(),
 231                         filename: this.getFilename(),
 232                         text: this.getText()
 233                 } ).then( function ( result ) {
 234                         upload.state = Upload.State.UPLOADED;
 235                         upload.imageinfo = result.upload.imageinfo;
 236                         return result;
 237                 }, function () {
 238                         upload.state = Upload.State.ERROR;
 239                 } );
 240         };
 241
 242         /**
 243          * Upload the file to the stash to be completed later.
 244          *
 245          * @return {jQuery.Promise}
 246          */
 247         UP.uploadToStash = function () {
 248                 var upload = this;
 249
 250                 if ( !this.getFile() ) {
 251                         return $.Deferred().reject( 'No file to upload. Call setFile to add one.' );
 252                 }
 253
 254                 if ( !this.getFilename() ) {
 255                         this.setFilenameFromFile();
 256                 }
 257
 258                 this.state = Upload.State.UPLOADING;
 259
 260                 this.stashPromise = this.api.uploadToStash( this.getFile(), {
 261                         filename: this.getFilename()
 262                 } ).then( function ( finishStash ) {
 263                         upload.state = Upload.State.STASHED;
 264                         return finishStash;
 265                 }, function () {
 266                         upload.state = Upload.State.ERROR;
 267                 } );
 268
 269                 return this.stashPromise;
 270         };
 271
 272         /**
 273          * Finish a stash upload.
 274          *
 275          * @return {jQuery.Promise}
 276          */
 277         UP.finishStashUpload = function () {
 278                 var upload = this;
 279
 280                 if ( !this.stashPromise ) {
 281                         return $.Deferred().reject( 'This upload has not been stashed, please upload it to the stash first.' );
 282                 }
 283
 284                 return this.stashPromise.then( function ( finishStash ) {
 285                         upload.state = Upload.State.UPLOADING;
 286
 287                         return finishStash( {
 288                                 watchlist: ( upload.getWatchlist() ) ? 1 : undefined,
 289                                 comment: upload.getComment(),
 290                                 filename: upload.getFilename(),
 291                                 text: upload.getText()
 292                         } ).then( function () {
 293                                 upload.state = Upload.State.UPLOADED;
 294                         }, function () {
 295                                 upload.state = Upload.State.ERROR;
 296                         } );
 297                 } );
 298         };
 299
 300         /**
 301          * @enum mw.Upload.State
 302          * State of uploads represented in simple terms.
 303          */
 304         Upload.State = {
 305                 /** Upload not yet started */
 306                 NEW: 0,
 307
 308                 /** Upload finished, but there was a warning */
 309                 WARNING: 1,
 310
 311                 /** Upload finished, but there was an error */
 312                 ERROR: 2,
 313
 314                 /** Upload in progress */
 315                 UPLOADING: 3,
 316
 317                 /** Upload finished, but not published, call #finishStashUpload */
 318                 STASHED: 4,
 319
 320                 /** Upload finished and published */
 321                 UPLOADED: 5
 322         };
 323
 324         mw.Upload = Upload;
 325 }( mediaWiki, jQuery ) );