resources/src/mediawiki/mediawiki.Upload.BookletLayout.js

   1 ( function ( $, mw ) {
   2
   3         /**
   4          * mw.Upload.BookletLayout encapsulates the process of uploading a file
   5          * to MediaWiki using the {@link mw.Upload upload model}.
   6          * The booklet emits events that can be used to get the stashed
   7          * upload and the final file. It can be extended to accept
   8          * additional fields from the user for specific scenarios like
   9          * for Commons, or campaigns.
  10          *
  11          * ## Structure
  12          *
  13          * The {@link OO.ui.BookletLayout booklet layout} has three steps:
  14          *
  15          *  - **Upload**: Has a {@link OO.ui.SelectFileWidget field} to get the file object.
  16          *
  17          * - **Information**: Has a {@link OO.ui.FormLayout form} to collect metadata. This can be
  18          *   extended.
  19          *
  20          * - **Insert**: Has details on how to use the file that was uploaded.
  21          *
  22          * Each step has a form associated with it defined in
  23          * {@link #renderUploadForm renderUploadForm},
  24          * {@link #renderInfoForm renderInfoForm}, and
  25          * {@link #renderInsertForm renderInfoForm}. The
  26          * {@link #getFile getFile},
  27          * {@link #getFilename getFilename}, and
  28          * {@link #getText getText} methods are used to get
  29          * the information filled in these forms, required to call
  30          * {@link mw.Upload mw.Upload}.
  31          *
  32          * ## Usage
  33          *
  34          * See the {@link mw.Upload.Dialog upload dialog}.
  35          *
  36          * The {@link #event-fileUploaded fileUploaded},
  37          * and {@link #event-fileSaved fileSaved} events can
  38          * be used to get details of the upload.
  39          *
  40          * ## Extending
  41          *
  42          * To extend using {@link mw.Upload mw.Upload}, override
  43          * {@link #renderInfoForm renderInfoForm} to render
  44          * the form required for the specific use-case. Update the
  45          * {@link #getFilename getFilename}, and
  46          * {@link #getText getText} methods to return data
  47          * from your newly created form. If you added new fields you'll also have
  48          * to update the {@link #clear} method.
  49          *
  50          * If you plan to use a different upload model, apart from what is mentioned
  51          * above, you'll also have to override the
  52          * {@link #createUpload createUpload} method to
  53          * return the new model. The {@link #saveFile saveFile}, and
  54          * the {@link #uploadFile uploadFile} methods need to be
  55          * overriden to use the new model and data returned from the forms.
  56          *
  57          * @class
  58          * @extends OO.ui.BookletLayout
  59          *
  60          * @constructor
  61          * @param {Object} config Configuration options
  62          * @cfg {jQuery} [$overlay] Overlay to use for widgets in the booklet
  63          */
  64         mw.Upload.BookletLayout = function ( config ) {
  65                 // Parent constructor
  66                 mw.Upload.BookletLayout.parent.call( this, config );
  67
  68                 this.$overlay = config.$overlay;
  69
  70                 this.renderUploadForm();
  71                 this.renderInfoForm();
  72                 this.renderInsertForm();
  73
  74                 this.addPages( [
  75                         new OO.ui.PageLayout( 'upload', {
  76                                 scrollable: true,
  77                                 padded: true,
  78                                 content: [ this.uploadForm ]
  79                         } ),
  80                         new OO.ui.PageLayout( 'info', {
  81                                 scrollable: true,
  82                                 padded: true,
  83                                 content: [ this.infoForm ]
  84                         } ),
  85                         new OO.ui.PageLayout( 'insert', {
  86                                 scrollable: true,
  87                                 padded: true,
  88                                 content: [ this.insertForm ]
  89                         } )
  90                 ] );
  91         };
  92
  93         /* Setup */
  94
  95         OO.inheritClass( mw.Upload.BookletLayout, OO.ui.BookletLayout );
  96
  97         /* Events */
  98
  99         /**
 100          * The file has finished uploading
 101          *
 102          * @event fileUploaded
 103          */
 104
 105         /**
 106          * The file has been saved to the database
 107          *
 108          * @event fileSaved
 109          */
 110
 111         /**
 112          * The upload form has changed
 113          *
 114          * @event uploadValid
 115          * @param {boolean} isValid The form is valid
 116          */
 117
 118         /**
 119          * The info form has changed
 120          *
 121          * @event infoValid
 122          * @param {boolean} isValid The form is valid
 123          */
 124
 125         /* Properties */
 126
 127         /**
 128          * @property {OO.ui.FormLayout} uploadForm
 129          * The form rendered in the first step to get the file object.
 130          * Rendered in {@link #renderUploadForm renderUploadForm}.
 131          */
 132
 133         /**
 134          * @property {OO.ui.FormLayout} infoForm
 135          * The form rendered in the second step to get metadata.
 136          * Rendered in {@link #renderInfoForm renderInfoForm}
 137          */
 138
 139         /**
 140          * @property {OO.ui.FormLayout} insertForm
 141          * The form rendered in the third step to show usage
 142          * Rendered in {@link #renderInsertForm renderInsertForm}
 143          */
 144
 145         /* Methods */
 146
 147         /**
 148          * Initialize for a new upload
 149          */
 150         mw.Upload.BookletLayout.prototype.initialize = function () {
 151                 this.clear();
 152                 this.upload = this.createUpload();
 153                 this.setPage( 'upload' );
 154         };
 155
 156         /**
 157          * Create a new upload model
 158          *
 159          * @protected
 160          * @return {mw.Upload} Upload model
 161          */
 162         mw.Upload.BookletLayout.prototype.createUpload = function () {
 163                 return new mw.Upload();
 164         };
 165
 166         /* Uploading */
 167
 168         /**
 169          * Uploads the file that was added in the upload form. Uses
 170          * {@link #getFile getFile} to get the HTML5
 171          * file object.
 172          *
 173          * @protected
 174          * @fires fileUploaded
 175          * @return {jQuery.Promise}
 176          */
 177         mw.Upload.BookletLayout.prototype.uploadFile = function () {
 178                 var deferred = $.Deferred(),
 179                         layout = this,
 180                         file = this.getFile();
 181
 182                 this.filenameWidget.setValue( file.name );
 183                 this.setPage( 'info' );
 184
 185                 this.upload.setFile( file );
 186                 // Explicitly set the filename so that the old filename isn't used in case of retry
 187                 this.upload.setFilenameFromFile();
 188
 189                 this.uploadPromise = this.upload.uploadToStash();
 190                 this.uploadPromise.then( function () {
 191                         deferred.resolve();
 192                         layout.emit( 'fileUploaded' );
 193                 }, function () {
 194                         // These errors will be thrown while the user is on the info page
 195                         if ( layout.upload.getState() === mw.Upload.State.ERROR ) {
 196                                 deferred.reject( new OO.ui.Error( layout.upload.getStateDetails(), {
 197                                         recoverable: false
 198                                 } ) );
 199                                 return false;
 200                         }
 201                         if ( layout.upload.getState() === mw.Upload.State.WARNING ) {
 202                                 deferred.reject( new OO.ui.Error( layout.upload.getStateDetails(), {
 203                                         recoverable: false
 204                                 } ) );
 205                                 return false;
 206                         }
 207                 } );
 208
 209                 // If there is an error in uploading, come back to the upload page
 210                 deferred.fail( function () {
 211                         layout.setPage( 'upload' );
 212                 } );
 213
 214                 return deferred;
 215         };
 216
 217         /**
 218          * Saves the stash finalizes upload. Uses
 219          * {@link #getFilename getFilename}, and
 220          * {@link #getText getText} to get details from
 221          * the form.
 222          *
 223          * @protected
 224          * @fires fileSaved
 225          * @returns {jQuery.Promise} Rejects the promise with an
 226          * {@link OO.ui.Error error}, or resolves if the upload was successful.
 227          */
 228         mw.Upload.BookletLayout.prototype.saveFile = function () {
 229                 var layout = this,
 230                         deferred = $.Deferred();
 231
 232                 this.upload.setFilename( this.getFilename() );
 233                 this.upload.setText( this.getText() );
 234
 235                 this.uploadPromise.then( function () {
 236                         layout.upload.finishStashUpload().then( function () {
 237                                 var name;
 238
 239                                 // Normalize page name and localise the 'File:' prefix
 240                                 name = new mw.Title( 'File:' + layout.upload.getFilename() ).toString();
 241                                 layout.filenameUsageWidget.setValue( '[[' + name + ']]' );
 242                                 layout.setPage( 'insert' );
 243
 244                                 deferred.resolve();
 245                                 layout.emit( 'fileSaved' );
 246                         }, function () {
 247                                 var stateDetails = layout.upload.getStateDetails();
 248
 249                                 if ( layout.upload.getState() === mw.Upload.State.ERROR ) {
 250                                         deferred.reject( new OO.ui.Error( stateDetails, {
 251                                                 recoverable: false
 252                                         } ) );
 253                                         return false;
 254                                 }
 255
 256                                 if ( layout.upload.getState() === mw.Upload.State.WARNING ) {
 257                                         // We could get more than one of these errors, these are in order
 258                                         // of importance. For example fixing the thumbnail like file name
 259                                         // won't help the fact that the file already exists.
 260                                         if ( stateDetails.exists !== undefined ) {
 261                                                 deferred.reject( new OO.ui.Error(
 262                                                         $( '<p>' ).html(
 263                                                                 mw.message( 'filepageexists', stateDetails.exists ).parse()
 264                                                         ),
 265                                                         { recoverable: false }
 266                                                 ) );
 267                                         } else if ( stateDetails.duplicate !== undefined ) {
 268                                                 deferred.reject( new OO.ui.Error(
 269                                                         $( '<p>' ).html(
 270                                                                 mw.message( 'fileexists', stateDetails.duplicate[ 0 ] ).parse()
 271                                                         ),
 272                                                         { recoverable: false }
 273                                                 ) );
 274                                         } else if ( stateDetails[ 'thumb-name' ] !== undefined ) {
 275                                                 deferred.reject( new OO.ui.Error(
 276                                                         $( '<p>' ).html(
 277                                                                 mw.message( 'filename-thumb-name' ).parse()
 278                                                         ),
 279                                                         { recoverable: false }
 280                                                 ) );
 281                                         } else if ( stateDetails[ 'bad-prefix' ] !== undefined ) {
 282                                                 deferred.reject( new OO.ui.Error(
 283                                                         $( '<p>' ).html(
 284                                                                 mw.message( 'filename-bad-prefix', stateDetails[ 'bad-prefix' ] ).parse()
 285                                                         ),
 286                                                         { recoverable: false }
 287                                                 ) );
 288                                         } else if ( stateDetails[ 'duplicate-archive' ] !== undefined ) {
 289                                                 deferred.reject( new OO.ui.Error(
 290                                                         $( '<p>' ).html(
 291                                                                 mw.message( 'api-error-duplicate-archive', stateDetails[ 'duplicate-archive' ] ).parse()
 292                                                         ),
 293                                                         { recoverable: false }
 294                                                 ) );
 295                                         } else if ( stateDetails.badfilename !== undefined ) {
 296                                                 // Change the name if the current name isn't acceptable
 297                                                 layout.filenameWidget.setValue( stateDetails.badfilename );
 298                                                 deferred.reject( new OO.ui.Error(
 299                                                         $( '<p>' ).html(
 300                                                                 mw.message( 'badfilename', stateDetails.badfilename ).parse()
 301                                                         )
 302                                                 ) );
 303                                         } else {
 304                                                 deferred.reject( new OO.ui.Error(
 305                                                         $( '<p>' ).html(
 306                                                                 // Let's get all the help we can if we can't pin point the error
 307                                                                 mw.message( 'api-error-unknown-warning', JSON.stringify( stateDetails ) ).parse()
 308                                                         ),
 309                                                         { recoverable: false }
 310                                                 ) );
 311                                         }
 312
 313                                         return false;
 314                                 }
 315                         } );
 316                 } );
 317
 318                 return deferred.promise();
 319         };
 320
 321         /* Form renderers */
 322
 323         /**
 324          * Renders and returns the upload form and sets the
 325          * {@link #uploadForm uploadForm} property.
 326          *
 327          * @protected
 328          * @fires selectFile
 329          * @returns {OO.ui.FormLayout}
 330          */
 331         mw.Upload.BookletLayout.prototype.renderUploadForm = function () {
 332                 var fieldset;
 333
 334                 this.selectFileWidget = new OO.ui.SelectFileWidget();
 335                 fieldset = new OO.ui.FieldsetLayout( { label: mw.msg( 'upload-form-label-select-file' ) } );
 336                 fieldset.addItems( [ this.selectFileWidget ] );
 337                 this.uploadForm = new OO.ui.FormLayout( { items: [ fieldset ] } );
 338
 339                 // Validation
 340                 this.selectFileWidget.on( 'change', this.onUploadFormChange.bind( this ) );
 341
 342                 return this.uploadForm;
 343         };
 344
 345         /**
 346          * Handle change events to the upload form
 347          *
 348          * @protected
 349          * @fires uploadValid
 350          */
 351         mw.Upload.BookletLayout.prototype.onUploadFormChange = function () {
 352                 this.emit( 'uploadValid', !!this.selectFileWidget.getValue() );
 353         };
 354
 355         /**
 356          * Renders and returns the information form for collecting
 357          * metadata and sets the {@link #infoForm infoForm}
 358          * property.
 359          *
 360          * @protected
 361          * @returns {OO.ui.FormLayout}
 362          */
 363         mw.Upload.BookletLayout.prototype.renderInfoForm = function () {
 364                 var fieldset;
 365
 366                 this.filenameWidget = new OO.ui.TextInputWidget( {
 367                         indicator: 'required',
 368                         required: true,
 369                         validate: /.+/
 370                 } );
 371                 this.descriptionWidget = new OO.ui.TextInputWidget( {
 372                         indicator: 'required',
 373                         required: true,
 374                         validate: /.+/,
 375                         multiline: true,
 376                         autosize: true
 377                 } );
 378
 379                 fieldset = new OO.ui.FieldsetLayout( {
 380                         label: mw.msg( 'upload-form-label-infoform-title' )
 381                 } );
 382                 fieldset.addItems( [
 383                         new OO.ui.FieldLayout( this.filenameWidget, {
 384                                 label: mw.msg( 'upload-form-label-infoform-name' ),
 385                                 align: 'top'
 386                         } ),
 387                         new OO.ui.FieldLayout( this.descriptionWidget, {
 388                                 label: mw.msg( 'upload-form-label-infoform-description' ),
 389                                 align: 'top'
 390                         } )
 391                 ] );
 392                 this.infoForm = new OO.ui.FormLayout( { items: [ fieldset ] } );
 393
 394                 this.filenameWidget.on( 'change', this.onInfoFormChange.bind( this ) );
 395                 this.descriptionWidget.on( 'change', this.onInfoFormChange.bind( this ) );
 396
 397                 return this.infoForm;
 398         };
 399
 400         /**
 401          * Handle change events to the info form
 402          *
 403          * @protected
 404          * @fires infoValid
 405          */
 406         mw.Upload.BookletLayout.prototype.onInfoFormChange = function () {
 407                 var layout = this;
 408                 $.when(
 409                         this.filenameWidget.getValidity(),
 410                         this.descriptionWidget.getValidity()
 411                 ).done( function () {
 412                         layout.emit( 'infoValid', true );
 413                 } ).fail( function () {
 414                         layout.emit( 'infoValid', false );
 415                 } );
 416         };
 417
 418         /**
 419          * Renders and returns the insert form to show file usage and
 420          * sets the {@link #insertForm insertForm} property.
 421          *
 422          * @protected
 423          * @returns {OO.ui.FormLayout}
 424          */
 425         mw.Upload.BookletLayout.prototype.renderInsertForm = function () {
 426                 var fieldset;
 427
 428                 this.filenameUsageWidget = new OO.ui.TextInputWidget();
 429                 fieldset = new OO.ui.FieldsetLayout( {
 430                         label: mw.msg( 'upload-form-label-usage-title' )
 431                 } );
 432                 fieldset.addItems( [
 433                         new OO.ui.FieldLayout( this.filenameUsageWidget, {
 434                                 label: mw.msg( 'upload-form-label-usage-filename' ),
 435                                 align: 'top'
 436                         } )
 437                 ] );
 438                 this.insertForm = new OO.ui.FormLayout( { items: [ fieldset ] } );
 439
 440                 return this.insertForm;
 441         };
 442
 443         /* Getters */
 444
 445         /**
 446          * Gets the file object from the
 447          * {@link #uploadForm upload form}.
 448          *
 449          * @protected
 450          * @returns {File|null}
 451          */
 452         mw.Upload.BookletLayout.prototype.getFile = function () {
 453                 return this.selectFileWidget.getValue();
 454         };
 455
 456         /**
 457          * Gets the file name from the
 458          * {@link #infoForm information form}.
 459          *
 460          * @protected
 461          * @returns {string}
 462          */
 463         mw.Upload.BookletLayout.prototype.getFilename = function () {
 464                 return this.filenameWidget.getValue();
 465         };
 466
 467         /**
 468          * Gets the page text from the
 469          * {@link #infoForm information form}.
 470          *
 471          * @protected
 472          * @returns {string}
 473          */
 474         mw.Upload.BookletLayout.prototype.getText = function () {
 475                 return this.descriptionWidget.getValue();
 476         };
 477
 478         /* Setters */
 479
 480         /**
 481          * Clear the values of all fields
 482          *
 483          * @protected
 484          */
 485         mw.Upload.BookletLayout.prototype.clear = function () {
 486                 this.selectFileWidget.setValue( null );
 487                 this.filenameWidget.setValue( null ).setValidityFlag( true );
 488                 this.descriptionWidget.setValue( null ).setValidityFlag( true );
 489                 this.filenameUsageWidget.setValue( null );
 490         };
 491
 492 }( jQuery, mediaWiki ) );