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.
13 * The {@link OO.ui.BookletLayout booklet layout} has three steps:
15 * - **Upload**: Has a {@link OO.ui.SelectFileWidget field} to get the file object.
17 * - **Information**: Has a {@link OO.ui.FormLayout form} to collect metadata. This can be
20 * - **Insert**: Has details on how to use the file that was uploaded.
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}.
34 * See the {@link mw.Upload.Dialog upload dialog}.
36 * The {@link #event-fileUploaded fileUploaded},
37 * and {@link #event-fileSaved fileSaved} events can
38 * be used to get details of the upload.
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.
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 * overridden to use the new model and data returned from the forms.
58 * @extends OO.ui.BookletLayout
61 * @param {Object} config Configuration options
62 * @cfg {jQuery} [$overlay] Overlay to use for widgets in the booklet
64 mw
.Upload
.BookletLayout = function ( config
) {
66 mw
.Upload
.BookletLayout
.parent
.call( this, config
);
68 this.$overlay
= config
.$overlay
;
70 this.renderUploadForm();
71 this.renderInfoForm();
72 this.renderInsertForm();
75 new OO
.ui
.PageLayout( 'upload', {
78 content
: [ this.uploadForm
]
80 new OO
.ui
.PageLayout( 'info', {
83 content
: [ this.infoForm
]
85 new OO
.ui
.PageLayout( 'insert', {
88 content
: [ this.insertForm
]
95 OO
.inheritClass( mw
.Upload
.BookletLayout
, OO
.ui
.BookletLayout
);
100 * The file has finished uploading
102 * @event fileUploaded
106 * The file has been saved to the database
109 * @param {Object} imageInfo See mw.Upload#getImageInfo
113 * The upload form has changed
116 * @param {boolean} isValid The form is valid
120 * The info form has changed
123 * @param {boolean} isValid The form is valid
129 * @property {OO.ui.FormLayout} uploadForm
130 * The form rendered in the first step to get the file object.
131 * Rendered in {@link #renderUploadForm renderUploadForm}.
135 * @property {OO.ui.FormLayout} infoForm
136 * The form rendered in the second step to get metadata.
137 * Rendered in {@link #renderInfoForm renderInfoForm}
141 * @property {OO.ui.FormLayout} insertForm
142 * The form rendered in the third step to show usage
143 * Rendered in {@link #renderInsertForm renderInsertForm}
149 * Initialize for a new upload
151 * @return {jQuery.Promise} Promise resolved when everything is initialized
153 mw
.Upload
.BookletLayout
.prototype.initialize = function () {
156 deferred
= $.Deferred();
159 this.upload
= this.createUpload();
160 this.setPage( 'upload' );
162 this.upload
.getApi().done( function ( api
) {
163 // If the user can't upload anything, don't give them the option to.
164 api
.getUserInfo().done( function ( userInfo
) {
165 if ( userInfo
.rights
.indexOf( 'upload' ) === -1 ) {
166 // TODO Use a better error message when not all logged-in users can upload
167 booklet
.getPage( 'upload' ).$element
.msg( 'api-error-mustbeloggedin' );
169 } ).always( function () {
172 } ).fail( function ( errorMsg
) {
173 booklet
.getPage( 'upload' ).$element
.msg( errorMsg
);
177 return deferred
.promise();
181 * Create a new upload model
184 * @return {mw.Upload} Upload model
186 mw
.Upload
.BookletLayout
.prototype.createUpload = function () {
187 return new mw
.Upload();
193 * Uploads the file that was added in the upload form. Uses
194 * {@link #getFile getFile} to get the HTML5
198 * @fires fileUploaded
199 * @return {jQuery.Promise}
201 mw
.Upload
.BookletLayout
.prototype.uploadFile = function () {
202 var deferred
= $.Deferred(),
204 file
= this.getFile();
206 this.setFilename( file
.name
);
208 this.setPage( 'info' );
210 if ( this.shouldRecordBucket
) {
211 this.upload
.bucket
= this.bucket
;
214 this.upload
.setFile( file
);
215 // The original file name might contain invalid characters, so use our sanitized one
216 this.upload
.setFilename( this.getFilename() );
218 this.uploadPromise
= this.upload
.uploadToStash();
219 this.uploadPromise
.then( function () {
221 layout
.emit( 'fileUploaded' );
223 // These errors will be thrown while the user is on the info page.
224 // Pretty sure it's impossible to get a warning other than 'stashfailed' here, which should
225 // really be an error...
226 var errorMessage
= layout
.getErrorMessageForStateDetails();
227 deferred
.reject( errorMessage
);
230 // If there is an error in uploading, come back to the upload page
231 deferred
.fail( function () {
232 layout
.setPage( 'upload' );
239 * Saves the stash finalizes upload. Uses
240 * {@link #getFilename getFilename}, and
241 * {@link #getText getText} to get details from
246 * @return {jQuery.Promise} Rejects the promise with an
247 * {@link OO.ui.Error error}, or resolves if the upload was successful.
249 mw
.Upload
.BookletLayout
.prototype.saveFile = function () {
251 deferred
= $.Deferred();
253 this.upload
.setFilename( this.getFilename() );
254 this.upload
.setText( this.getText() );
256 this.uploadPromise
.then( function () {
257 layout
.upload
.finishStashUpload().then( function () {
260 // Normalize page name and localise the 'File:' prefix
261 name
= new mw
.Title( 'File:' + layout
.upload
.getFilename() ).toString();
262 layout
.filenameUsageWidget
.setValue( '[[' + name
+ ']]' );
263 layout
.setPage( 'insert' );
266 layout
.emit( 'fileSaved', layout
.upload
.getImageInfo() );
268 var errorMessage
= layout
.getErrorMessageForStateDetails();
269 deferred
.reject( errorMessage
);
273 return deferred
.promise();
277 * Get an error message (as OO.ui.Error object) that should be displayed to the user for current
278 * state and state details.
281 * @return {OO.ui.Error} Error to display for given state and details.
283 mw
.Upload
.BookletLayout
.prototype.getErrorMessageForStateDetails = function () {
285 state
= this.upload
.getState(),
286 stateDetails
= this.upload
.getStateDetails(),
287 error
= stateDetails
.error
,
288 warnings
= stateDetails
.upload
&& stateDetails
.upload
.warnings
;
290 if ( state
=== mw
.Upload
.State
.ERROR
) {
292 // If there's an 'exception' key, this might be a timeout, or other connection problem
293 return new OO
.ui
.Error(
294 $( '<p>' ).msg( 'api-error-unknownerror', JSON
.stringify( stateDetails
) ),
295 { recoverable
: false }
299 // HACK We should either have a hook here to allow TitleBlacklist to handle this, or just have
300 // TitleBlacklist produce sane error messages that can be displayed without arcane knowledge
301 if ( error
.info
=== 'TitleBlacklist prevents this title from being created' ) {
302 // HACK Apparently the only reliable way to determine whether TitleBlacklist was involved
303 return new OO
.ui
.Error(
304 // HACK TitleBlacklist doesn't have a sensible message, this one is from UploadWizard
305 $( '<p>' ).msg( 'api-error-blacklisted' ),
306 { recoverable
: false }
310 message
= mw
.message( 'api-error-' + error
.code
);
311 if ( !message
.exists() ) {
312 message
= mw
.message( 'api-error-unknownerror', JSON
.stringify( stateDetails
) );
314 return new OO
.ui
.Error(
315 $( '<p>' ).append( message
.parseDom() ),
316 { recoverable
: false }
320 if ( state
=== mw
.Upload
.State
.WARNING
) {
321 // We could get more than one of these errors, these are in order
322 // of importance. For example fixing the thumbnail like file name
323 // won't help the fact that the file already exists.
324 if ( warnings
.stashfailed
!== undefined ) {
325 return new OO
.ui
.Error(
326 $( '<p>' ).msg( 'api-error-stashfailed' ),
327 { recoverable
: false }
329 } else if ( warnings
.exists
!== undefined ) {
330 return new OO
.ui
.Error(
331 $( '<p>' ).msg( 'fileexists', 'File:' + warnings
.exists
),
332 { recoverable
: false }
334 } else if ( warnings
[ 'page-exists' ] !== undefined ) {
335 return new OO
.ui
.Error(
336 $( '<p>' ).msg( 'filepageexists', 'File:' + warnings
[ 'page-exists' ] ),
337 { recoverable
: false }
339 } else if ( warnings
.duplicate
!== undefined ) {
340 return new OO
.ui
.Error(
341 $( '<p>' ).msg( 'api-error-duplicate', warnings
.duplicate
.length
),
342 { recoverable
: false }
344 } else if ( warnings
[ 'thumb-name' ] !== undefined ) {
345 return new OO
.ui
.Error(
346 $( '<p>' ).msg( 'filename-thumb-name' ),
347 { recoverable
: false }
349 } else if ( warnings
[ 'bad-prefix' ] !== undefined ) {
350 return new OO
.ui
.Error(
351 $( '<p>' ).msg( 'filename-bad-prefix', warnings
[ 'bad-prefix' ] ),
352 { recoverable
: false }
354 } else if ( warnings
[ 'duplicate-archive' ] !== undefined ) {
355 return new OO
.ui
.Error(
356 $( '<p>' ).msg( 'api-error-duplicate-archive', 1 ),
357 { recoverable
: false }
359 } else if ( warnings
.badfilename
!== undefined ) {
360 // Change the name if the current name isn't acceptable
361 // TODO This might not really be the best place to do this
362 this.setFilename( warnings
.badfilename
);
363 return new OO
.ui
.Error(
364 $( '<p>' ).msg( 'badfilename', warnings
.badfilename
)
367 return new OO
.ui
.Error(
368 // Let's get all the help we can if we can't pin point the error
369 $( '<p>' ).msg( 'api-error-unknown-warning', JSON
.stringify( stateDetails
) ),
370 { recoverable
: false }
379 * Renders and returns the upload form and sets the
380 * {@link #uploadForm uploadForm} property.
384 * @return {OO.ui.FormLayout}
386 mw
.Upload
.BookletLayout
.prototype.renderUploadForm = function () {
389 this.selectFileWidget
= new OO
.ui
.SelectFileWidget();
390 fieldset
= new OO
.ui
.FieldsetLayout( { label
: mw
.msg( 'upload-form-label-select-file' ) } );
391 fieldset
.addItems( [ this.selectFileWidget
] );
392 this.uploadForm
= new OO
.ui
.FormLayout( { items
: [ fieldset
] } );
395 this.selectFileWidget
.on( 'change', this.onUploadFormChange
.bind( this ) );
397 return this.uploadForm
;
401 * Handle change events to the upload form
406 mw
.Upload
.BookletLayout
.prototype.onUploadFormChange = function () {
407 this.emit( 'uploadValid', !!this.selectFileWidget
.getValue() );
411 * Renders and returns the information form for collecting
412 * metadata and sets the {@link #infoForm infoForm}
416 * @return {OO.ui.FormLayout}
418 mw
.Upload
.BookletLayout
.prototype.renderInfoForm = function () {
421 this.filenameWidget
= new OO
.ui
.TextInputWidget( {
422 indicator
: 'required',
426 this.descriptionWidget
= new OO
.ui
.TextInputWidget( {
427 indicator
: 'required',
434 fieldset
= new OO
.ui
.FieldsetLayout( {
435 label
: mw
.msg( 'upload-form-label-infoform-title' )
438 new OO
.ui
.FieldLayout( this.filenameWidget
, {
439 label
: mw
.msg( 'upload-form-label-infoform-name' ),
441 help
: mw
.msg( 'upload-form-label-infoform-name-tooltip' )
443 new OO
.ui
.FieldLayout( this.descriptionWidget
, {
444 label
: mw
.msg( 'upload-form-label-infoform-description' ),
446 help
: mw
.msg( 'upload-form-label-infoform-description-tooltip' )
449 this.infoForm
= new OO
.ui
.FormLayout( { items
: [ fieldset
] } );
451 this.filenameWidget
.on( 'change', this.onInfoFormChange
.bind( this ) );
452 this.descriptionWidget
.on( 'change', this.onInfoFormChange
.bind( this ) );
454 return this.infoForm
;
458 * Handle change events to the info form
463 mw
.Upload
.BookletLayout
.prototype.onInfoFormChange = function () {
466 this.filenameWidget
.getValidity(),
467 this.descriptionWidget
.getValidity()
468 ).done( function () {
469 layout
.emit( 'infoValid', true );
470 } ).fail( function () {
471 layout
.emit( 'infoValid', false );
476 * Renders and returns the insert form to show file usage and
477 * sets the {@link #insertForm insertForm} property.
480 * @return {OO.ui.FormLayout}
482 mw
.Upload
.BookletLayout
.prototype.renderInsertForm = function () {
485 this.filenameUsageWidget
= new OO
.ui
.TextInputWidget();
486 fieldset
= new OO
.ui
.FieldsetLayout( {
487 label
: mw
.msg( 'upload-form-label-usage-title' )
490 new OO
.ui
.FieldLayout( this.filenameUsageWidget
, {
491 label
: mw
.msg( 'upload-form-label-usage-filename' ),
495 this.insertForm
= new OO
.ui
.FormLayout( { items
: [ fieldset
] } );
497 return this.insertForm
;
503 * Gets the file object from the
504 * {@link #uploadForm upload form}.
507 * @return {File|null}
509 mw
.Upload
.BookletLayout
.prototype.getFile = function () {
510 return this.selectFileWidget
.getValue();
514 * Gets the file name from the
515 * {@link #infoForm information form}.
520 mw
.Upload
.BookletLayout
.prototype.getFilename = function () {
521 var filename
= this.filenameWidget
.getValue();
522 if ( this.filenameExtension
) {
523 filename
+= '.' + this.filenameExtension
;
529 * Prefills the {@link #infoForm information form} with the given filename.
532 * @param {string} filename
534 mw
.Upload
.BookletLayout
.prototype.setFilename = function ( filename
) {
535 var title
= mw
.Title
.newFromFileName( filename
);
538 this.filenameWidget
.setValue( title
.getNameText() );
539 this.filenameExtension
= mw
.Title
.normalizeExtension( title
.getExtension() );
541 // Seems to happen for files with no extension, which should fail some checks anyway...
542 this.filenameWidget
.setValue( filename
);
543 this.filenameExtension
= null;
548 * Gets the page text from the
549 * {@link #infoForm information form}.
554 mw
.Upload
.BookletLayout
.prototype.getText = function () {
555 return this.descriptionWidget
.getValue();
561 * Sets the file object
564 * @param {File|null} file File to select
566 mw
.Upload
.BookletLayout
.prototype.setFile = function ( file
) {
567 this.selectFileWidget
.setValue( file
);
571 * Clear the values of all fields
575 mw
.Upload
.BookletLayout
.prototype.clear = function () {
576 this.selectFileWidget
.setValue( null );
577 this.filenameWidget
.setValue( null ).setValidityFlag( true );
578 this.descriptionWidget
.setValue( null ).setValidityFlag( true );
579 this.filenameUsageWidget
.setValue( null );
582 }( jQuery
, mediaWiki
) );