2 ( function ( $, mw
, moment
) {
5 * mw.Upload.BookletLayout encapsulates the process of uploading a file
6 * to MediaWiki using the {@link mw.Upload upload model}.
7 * The booklet emits events that can be used to get the stashed
8 * upload and the final file. It can be extended to accept
9 * additional fields from the user for specific scenarios like
10 * for Commons, or campaigns.
14 * The {@link OO.ui.BookletLayout booklet layout} has three steps:
16 * - **Upload**: Has a {@link OO.ui.SelectFileWidget field} to get the file object.
18 * - **Information**: Has a {@link OO.ui.FormLayout form} to collect metadata. This can be
21 * - **Insert**: Has details on how to use the file that was uploaded.
23 * Each step has a form associated with it defined in
24 * {@link #renderUploadForm renderUploadForm},
25 * {@link #renderInfoForm renderInfoForm}, and
26 * {@link #renderInsertForm renderInfoForm}. The
27 * {@link #getFile getFile},
28 * {@link #getFilename getFilename}, and
29 * {@link #getText getText} methods are used to get
30 * the information filled in these forms, required to call
31 * {@link mw.Upload mw.Upload}.
35 * See the {@link mw.Upload.Dialog upload dialog}.
37 * The {@link #event-fileUploaded fileUploaded},
38 * and {@link #event-fileSaved fileSaved} events can
39 * be used to get details of the upload.
43 * To extend using {@link mw.Upload mw.Upload}, override
44 * {@link #renderInfoForm renderInfoForm} to render
45 * the form required for the specific use-case. Update the
46 * {@link #getFilename getFilename}, and
47 * {@link #getText getText} methods to return data
48 * from your newly created form. If you added new fields you'll also have
49 * to update the {@link #clear} method.
51 * If you plan to use a different upload model, apart from what is mentioned
52 * above, you'll also have to override the
53 * {@link #createUpload createUpload} method to
54 * return the new model. The {@link #saveFile saveFile}, and
55 * the {@link #uploadFile uploadFile} methods need to be
56 * overridden to use the new model and data returned from the forms.
59 * @extends OO.ui.BookletLayout
62 * @param {Object} config Configuration options
63 * @cfg {jQuery} [$overlay] Overlay to use for widgets in the booklet
64 * @cfg {string} [filekey] Sets the stashed file to finish uploading. Overrides most of the file selection process, and fetches a thumbnail from the server.
66 mw
.Upload
.BookletLayout = function ( config
) {
68 mw
.Upload
.BookletLayout
.parent
.call( this, config
);
70 this.$overlay
= config
.$overlay
;
72 this.filekey
= config
.filekey
;
74 this.renderUploadForm();
75 this.renderInfoForm();
76 this.renderInsertForm();
79 new OO
.ui
.PageLayout( 'upload', {
82 content
: [ this.uploadForm
]
84 new OO
.ui
.PageLayout( 'info', {
87 content
: [ this.infoForm
]
89 new OO
.ui
.PageLayout( 'insert', {
92 content
: [ this.insertForm
]
99 OO
.inheritClass( mw
.Upload
.BookletLayout
, OO
.ui
.BookletLayout
);
104 * Progress events for the uploaded file
106 * @event fileUploadProgress
107 * @param {number} progress In percentage
108 * @param {Object} duration Duration object from `moment.duration()`
112 * The file has finished uploading
114 * @event fileUploaded
118 * The file has been saved to the database
121 * @param {Object} imageInfo See mw.Upload#getImageInfo
125 * The upload form has changed
128 * @param {boolean} isValid The form is valid
132 * The info form has changed
135 * @param {boolean} isValid The form is valid
141 * @property {OO.ui.FormLayout} uploadForm
142 * The form rendered in the first step to get the file object.
143 * Rendered in {@link #renderUploadForm renderUploadForm}.
147 * @property {OO.ui.FormLayout} infoForm
148 * The form rendered in the second step to get metadata.
149 * Rendered in {@link #renderInfoForm renderInfoForm}
153 * @property {OO.ui.FormLayout} insertForm
154 * The form rendered in the third step to show usage
155 * Rendered in {@link #renderInsertForm renderInsertForm}
161 * Initialize for a new upload
163 * @return {jQuery.Promise} Promise resolved when everything is initialized
165 mw
.Upload
.BookletLayout
.prototype.initialize = function () {
169 this.upload
= this.createUpload();
171 this.setPage( 'upload' );
173 if ( this.filekey
) {
174 this.setFilekey( this.filekey
);
177 return this.upload
.getApi().then(
180 booklet
.upload
.loadConfig().then(
182 function ( errorMsg
) {
183 booklet
.getPage( 'upload' ).$element
.msg( errorMsg
);
184 return $.Deferred().resolve();
187 // If the user can't upload anything, don't give them the option to.
188 api
.getUserInfo().then( function ( userInfo
) {
189 if ( userInfo
.rights
.indexOf( 'upload' ) === -1 ) {
190 if ( mw
.user
.isAnon() ) {
191 booklet
.getPage( 'upload' ).$element
.msg( 'api-error-mustbeloggedin' );
193 booklet
.getPage( 'upload' ).$element
.msg( 'api-error-badaccess-groups' );
196 return $.Deferred().resolve();
200 // Always resolve, never reject
201 function () { return $.Deferred().resolve(); }
204 function ( errorMsg
) {
205 booklet
.getPage( 'upload' ).$element
.msg( errorMsg
);
206 return $.Deferred().resolve();
212 * Create a new upload model
215 * @return {mw.Upload} Upload model
217 mw
.Upload
.BookletLayout
.prototype.createUpload = function () {
218 return new mw
.Upload();
224 * Uploads the file that was added in the upload form. Uses
225 * {@link #getFile getFile} to get the HTML5
229 * @fires fileUploadProgress
230 * @fires fileUploaded
231 * @return {jQuery.Promise}
233 mw
.Upload
.BookletLayout
.prototype.uploadFile = function () {
234 var deferred
= $.Deferred(),
235 startTime
= new Date(),
237 file
= this.getFile();
239 this.setPage( 'info' );
241 if ( this.filekey
) {
242 if ( file
=== null ) {
243 // Someone gonna get-a hurt real bad
244 throw new Error( 'filekey not passed into file select widget, which is impossible. Quitting while we\'re behind.' );
247 // Stashed file already uploaded.
249 this.uploadPromise
= deferred
;
250 this.emit( 'fileUploaded' );
254 this.setFilename( file
.name
);
256 this.upload
.setFile( file
);
257 // The original file name might contain invalid characters, so use our sanitized one
258 this.upload
.setFilename( this.getFilename() );
260 this.uploadPromise
= this.upload
.uploadToStash();
261 this.uploadPromise
.then( function () {
263 layout
.emit( 'fileUploaded' );
265 // These errors will be thrown while the user is on the info page.
266 layout
.getErrorMessageForStateDetails().then( function ( errorMessage
) {
267 deferred
.reject( errorMessage
);
269 }, function ( progress
) {
270 var elapsedTime
= new Date() - startTime
,
271 estimatedTotalTime
= ( 1 / progress
) * elapsedTime
,
272 estimatedRemainingTime
= moment
.duration( estimatedTotalTime
- elapsedTime
);
273 layout
.emit( 'fileUploadProgress', progress
, estimatedRemainingTime
);
276 // If there is an error in uploading, come back to the upload page
277 deferred
.fail( function () {
278 layout
.setPage( 'upload' );
285 * Saves the stash finalizes upload. Uses
286 * {@link #getFilename getFilename}, and
287 * {@link #getText getText} to get details from
292 * @return {jQuery.Promise} Rejects the promise with an
293 * {@link OO.ui.Error error}, or resolves if the upload was successful.
295 mw
.Upload
.BookletLayout
.prototype.saveFile = function () {
297 deferred
= $.Deferred();
299 this.upload
.setFilename( this.getFilename() );
300 this.upload
.setText( this.getText() );
302 this.uploadPromise
.then( function () {
303 layout
.upload
.finishStashUpload().then( function () {
306 // Normalize page name and localise the 'File:' prefix
307 name
= new mw
.Title( 'File:' + layout
.upload
.getFilename() ).toString();
308 layout
.filenameUsageWidget
.setValue( '[[' + name
+ ']]' );
309 layout
.setPage( 'insert' );
312 layout
.emit( 'fileSaved', layout
.upload
.getImageInfo() );
314 layout
.getErrorMessageForStateDetails().then( function ( errorMessage
) {
315 deferred
.reject( errorMessage
);
320 return deferred
.promise();
324 * Get an error message (as OO.ui.Error object) that should be displayed to the user for current
325 * state and state details.
328 * @return {jQuery.Promise} A Promise that will be resolved with an OO.ui.Error.
330 mw
.Upload
.BookletLayout
.prototype.getErrorMessageForStateDetails = function () {
332 state
= this.upload
.getState(),
333 stateDetails
= this.upload
.getStateDetails(),
334 error
= stateDetails
.error
,
335 warnings
= stateDetails
.upload
&& stateDetails
.upload
.warnings
;
337 if ( state
=== mw
.Upload
.State
.ERROR
) {
339 // If there's an 'exception' key, this might be a timeout, or other connection problem
340 return $.Deferred().resolve( new OO
.ui
.Error(
341 $( '<p>' ).msg( 'api-error-unknownerror', JSON
.stringify( stateDetails
) ),
342 { recoverable
: false }
346 // Errors in this format are produced by TitleBlacklist and AbuseFilter. Perhaps other
347 // extensions will follow this format in the future.
348 if ( error
.message
) {
349 return this.upload
.getApi()
350 .then( function ( api
) {
351 // 'amenableparser' will expand templates and parser functions server-side.
352 // We still do the rest of wikitext parsing here (through jqueryMsg).
353 return api
.loadMessagesIfMissing( [ error
.message
.key
], { amenableparser
: true } )
355 if ( !mw
.message( error
.message
.key
).exists() ) {
356 return $.Deferred().reject();
358 return new OO
.ui
.Error(
359 $( '<p>' ).msg( error
.message
.key
, error
.message
.params
|| [] ),
360 { recoverable
: false }
364 .then( null, function () {
365 // We failed when loading the error message, or it doesn't actually exist, fall back
366 return $.Deferred().resolve( new OO
.ui
.Error(
367 $( '<p>' ).msg( 'api-error-unknownerror', JSON
.stringify( stateDetails
) ),
368 { recoverable
: false }
373 if ( error
.code
=== 'protectedpage' ) {
374 message
= mw
.message( 'protectedpagetext' );
376 message
= mw
.message( 'api-error-' + error
.code
);
377 if ( !message
.exists() ) {
378 message
= mw
.message( 'api-error-unknownerror', JSON
.stringify( stateDetails
) );
381 return $.Deferred().resolve( new OO
.ui
.Error(
382 $( '<p>' ).append( message
.parseDom() ),
383 { recoverable
: false }
387 if ( state
=== mw
.Upload
.State
.WARNING
) {
388 // We could get more than one of these errors, these are in order
389 // of importance. For example fixing the thumbnail like file name
390 // won't help the fact that the file already exists.
391 if ( warnings
.stashfailed
!== undefined ) {
392 return $.Deferred().resolve( new OO
.ui
.Error(
393 $( '<p>' ).msg( 'api-error-stashfailed' ),
394 { recoverable
: false }
396 } else if ( warnings
.exists
!== undefined ) {
397 return $.Deferred().resolve( new OO
.ui
.Error(
398 $( '<p>' ).msg( 'fileexists', 'File:' + warnings
.exists
),
399 { recoverable
: false }
401 } else if ( warnings
[ 'exists-normalized' ] !== undefined ) {
402 return $.Deferred().resolve( new OO
.ui
.Error(
403 $( '<p>' ).msg( 'fileexists', 'File:' + warnings
[ 'exists-normalized' ] ),
404 { recoverable
: false }
406 } else if ( warnings
[ 'page-exists' ] !== undefined ) {
407 return $.Deferred().resolve( new OO
.ui
.Error(
408 $( '<p>' ).msg( 'filepageexists', 'File:' + warnings
[ 'page-exists' ] ),
409 { recoverable
: false }
411 } else if ( warnings
.duplicate
!== undefined ) {
412 return $.Deferred().resolve( new OO
.ui
.Error(
413 $( '<p>' ).msg( 'api-error-duplicate', warnings
.duplicate
.length
),
414 { recoverable
: false }
416 } else if ( warnings
[ 'thumb-name' ] !== undefined ) {
417 return $.Deferred().resolve( new OO
.ui
.Error(
418 $( '<p>' ).msg( 'filename-thumb-name' ),
419 { recoverable
: false }
421 } else if ( warnings
[ 'bad-prefix' ] !== undefined ) {
422 return $.Deferred().resolve( new OO
.ui
.Error(
423 $( '<p>' ).msg( 'filename-bad-prefix', warnings
[ 'bad-prefix' ] ),
424 { recoverable
: false }
426 } else if ( warnings
[ 'duplicate-archive' ] !== undefined ) {
427 return $.Deferred().resolve( new OO
.ui
.Error(
428 $( '<p>' ).msg( 'api-error-duplicate-archive', 1 ),
429 { recoverable
: false }
431 } else if ( warnings
[ 'was-deleted' ] !== undefined ) {
432 return $.Deferred().resolve( new OO
.ui
.Error(
433 $( '<p>' ).msg( 'api-error-was-deleted' ),
434 { recoverable
: false }
436 } else if ( warnings
.badfilename
!== undefined ) {
437 // Change the name if the current name isn't acceptable
438 // TODO This might not really be the best place to do this
439 this.setFilename( warnings
.badfilename
);
440 return $.Deferred().resolve( new OO
.ui
.Error(
441 $( '<p>' ).msg( 'badfilename', warnings
.badfilename
)
444 return $.Deferred().resolve( new OO
.ui
.Error(
445 // Let's get all the help we can if we can't pin point the error
446 $( '<p>' ).msg( 'api-error-unknown-warning', JSON
.stringify( stateDetails
) ),
447 { recoverable
: false }
456 * Renders and returns the upload form and sets the
457 * {@link #uploadForm uploadForm} property.
461 * @return {OO.ui.FormLayout}
463 mw
.Upload
.BookletLayout
.prototype.renderUploadForm = function () {
467 this.selectFileWidget
= this.getFileWidget();
468 fieldset
= new OO
.ui
.FieldsetLayout();
469 fieldset
.addItems( [ this.selectFileWidget
] );
470 this.uploadForm
= new OO
.ui
.FormLayout( { items
: [ fieldset
] } );
472 // Validation (if the SFW is for a stashed file, this never fires)
473 this.selectFileWidget
.on( 'change', this.onUploadFormChange
.bind( this ) );
475 this.selectFileWidget
.on( 'change', function () {
476 layout
.updateFilePreview();
479 return this.uploadForm
;
483 * Gets the widget for displaying or inputting the file to upload.
485 * @return {OO.ui.SelectFileWidget|mw.widgets.StashedFileWidget}
487 mw
.Upload
.BookletLayout
.prototype.getFileWidget = function () {
488 if ( this.filekey
) {
489 return new mw
.widgets
.StashedFileWidget( {
490 filekey
: this.filekey
494 return new OO
.ui
.SelectFileWidget( {
500 * Updates the file preview on the info form when a file is added.
504 mw
.Upload
.BookletLayout
.prototype.updateFilePreview = function () {
505 this.selectFileWidget
.loadAndGetImageUrl().done( function ( url
) {
506 this.filePreview
.$element
.find( 'p' ).remove();
507 this.filePreview
.$element
.css( 'background-image', 'url(' + url
+ ')' );
508 this.infoForm
.$element
.addClass( 'mw-upload-bookletLayout-hasThumbnail' );
509 }.bind( this ) ).fail( function () {
510 this.filePreview
.$element
.find( 'p' ).remove();
511 if ( this.selectFileWidget
.getValue() ) {
512 this.filePreview
.$element
.append(
513 $( '<p>' ).text( this.selectFileWidget
.getValue().name
)
516 this.filePreview
.$element
.css( 'background-image', '' );
517 this.infoForm
.$element
.removeClass( 'mw-upload-bookletLayout-hasThumbnail' );
522 * Handle change events to the upload form
527 mw
.Upload
.BookletLayout
.prototype.onUploadFormChange = function () {
528 this.emit( 'uploadValid', !!this.selectFileWidget
.getValue() );
532 * Renders and returns the information form for collecting
533 * metadata and sets the {@link #infoForm infoForm}
537 * @return {OO.ui.FormLayout}
539 mw
.Upload
.BookletLayout
.prototype.renderInfoForm = function () {
542 this.filePreview
= new OO
.ui
.Widget( {
543 classes
: [ 'mw-upload-bookletLayout-filePreview' ]
545 this.progressBarWidget
= new OO
.ui
.ProgressBarWidget( {
548 this.filePreview
.$element
.append( this.progressBarWidget
.$element
);
550 this.filenameWidget
= new OO
.ui
.TextInputWidget( {
551 indicator
: 'required',
555 this.descriptionWidget
= new OO
.ui
.TextInputWidget( {
556 indicator
: 'required',
563 fieldset
= new OO
.ui
.FieldsetLayout( {
564 label
: mw
.msg( 'upload-form-label-infoform-title' )
567 new OO
.ui
.FieldLayout( this.filenameWidget
, {
568 label
: mw
.msg( 'upload-form-label-infoform-name' ),
570 help
: mw
.msg( 'upload-form-label-infoform-name-tooltip' )
572 new OO
.ui
.FieldLayout( this.descriptionWidget
, {
573 label
: mw
.msg( 'upload-form-label-infoform-description' ),
575 help
: mw
.msg( 'upload-form-label-infoform-description-tooltip' )
578 this.infoForm
= new OO
.ui
.FormLayout( {
579 classes
: [ 'mw-upload-bookletLayout-infoForm' ],
580 items
: [ this.filePreview
, fieldset
]
583 this.on( 'fileUploadProgress', function ( progress
) {
584 this.progressBarWidget
.setProgress( progress
* 100 );
587 this.filenameWidget
.on( 'change', this.onInfoFormChange
.bind( this ) );
588 this.descriptionWidget
.on( 'change', this.onInfoFormChange
.bind( this ) );
590 return this.infoForm
;
594 * Handle change events to the info form
599 mw
.Upload
.BookletLayout
.prototype.onInfoFormChange = function () {
602 this.filenameWidget
.getValidity(),
603 this.descriptionWidget
.getValidity()
604 ).done( function () {
605 layout
.emit( 'infoValid', true );
606 } ).fail( function () {
607 layout
.emit( 'infoValid', false );
612 * Renders and returns the insert form to show file usage and
613 * sets the {@link #insertForm insertForm} property.
616 * @return {OO.ui.FormLayout}
618 mw
.Upload
.BookletLayout
.prototype.renderInsertForm = function () {
621 this.filenameUsageWidget
= new OO
.ui
.TextInputWidget();
622 fieldset
= new OO
.ui
.FieldsetLayout( {
623 label
: mw
.msg( 'upload-form-label-usage-title' )
626 new OO
.ui
.FieldLayout( this.filenameUsageWidget
, {
627 label
: mw
.msg( 'upload-form-label-usage-filename' ),
631 this.insertForm
= new OO
.ui
.FormLayout( { items
: [ fieldset
] } );
633 return this.insertForm
;
639 * Gets the file object from the
640 * {@link #uploadForm upload form}.
643 * @return {File|null}
645 mw
.Upload
.BookletLayout
.prototype.getFile = function () {
646 return this.selectFileWidget
.getValue();
650 * Gets the file name from the
651 * {@link #infoForm information form}.
656 mw
.Upload
.BookletLayout
.prototype.getFilename = function () {
657 var filename
= this.filenameWidget
.getValue();
658 if ( this.filenameExtension
) {
659 filename
+= '.' + this.filenameExtension
;
665 * Prefills the {@link #infoForm information form} with the given filename.
668 * @param {string} filename
670 mw
.Upload
.BookletLayout
.prototype.setFilename = function ( filename
) {
671 var title
= mw
.Title
.newFromFileName( filename
);
674 this.filenameWidget
.setValue( title
.getNameText() );
675 this.filenameExtension
= mw
.Title
.normalizeExtension( title
.getExtension() );
677 // Seems to happen for files with no extension, which should fail some checks anyway...
678 this.filenameWidget
.setValue( filename
);
679 this.filenameExtension
= null;
684 * Gets the page text from the
685 * {@link #infoForm information form}.
690 mw
.Upload
.BookletLayout
.prototype.getText = function () {
691 return this.descriptionWidget
.getValue();
697 * Sets the file object
700 * @param {File|null} file File to select
702 mw
.Upload
.BookletLayout
.prototype.setFile = function ( file
) {
703 this.selectFileWidget
.setValue( file
);
707 * Sets the filekey of a file already stashed on the server
708 * as the target of this upload operation.
711 * @param {string} filekey
713 mw
.Upload
.BookletLayout
.prototype.setFilekey = function ( filekey
) {
714 this.upload
.setFilekey( this.filekey
);
715 this.selectFileWidget
.setValue( filekey
);
717 this.onUploadFormChange();
721 * Clear the values of all fields
725 mw
.Upload
.BookletLayout
.prototype.clear = function () {
726 this.selectFileWidget
.setValue( null );
727 this.progressBarWidget
.setProgress( 0 );
728 this.filenameWidget
.setValue( null ).setValidityFlag( true );
729 this.descriptionWidget
.setValue( null ).setValidityFlag( true );
730 this.filenameUsageWidget
.setValue( null );
733 }( jQuery
, mediaWiki
, moment
) );