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 * overriden to use the new model and data returned from the forms.
58 * @extends OO.ui.BookletLayout
61 * @param {Object} config Configuration options
63 mw
.Upload
.BookletLayout = function ( config
) {
65 mw
.Upload
.BookletLayout
.parent
.call( this, config
);
67 this.renderUploadForm();
68 this.renderInfoForm();
69 this.renderInsertForm();
72 new OO
.ui
.PageLayout( 'upload', {
75 content
: [ this.uploadForm
]
77 new OO
.ui
.PageLayout( 'info', {
80 content
: [ this.infoForm
]
82 new OO
.ui
.PageLayout( 'insert', {
85 content
: [ this.insertForm
]
92 OO
.inheritClass( mw
.Upload
.BookletLayout
, OO
.ui
.BookletLayout
);
97 * The file has finished uploading
103 * The file has been saved to the database
109 * The upload form has changed
112 * @param {boolean} isValid The form is valid
116 * The info form has changed
119 * @param {boolean} isValid The form is valid
125 * @property {OO.ui.FormLayout} uploadForm
126 * The form rendered in the first step to get the file object.
127 * Rendered in {@link #renderUploadForm renderUploadForm}.
131 * @property {OO.ui.FormLayout} infoForm
132 * The form rendered in the second step to get metadata.
133 * Rendered in {@link #renderInfoForm renderInfoForm}
137 * @property {OO.ui.FormLayout} insertForm
138 * The form rendered in the third step to show usage
139 * Rendered in {@link #renderInsertForm renderInsertForm}
145 * Initialize for a new upload
147 mw
.Upload
.BookletLayout
.prototype.initialize = function () {
149 this.upload
= this.createUpload();
150 this.setPage( 'upload' );
154 * Create a new upload model
157 * @return {mw.Upload} Upload model
159 mw
.Upload
.BookletLayout
.prototype.createUpload = function () {
160 return new mw
.Upload();
166 * Uploads the file that was added in the upload form. Uses
167 * {@link #getFile getFile} to get the HTML5
171 * @fires fileUploaded
172 * @return {jQuery.Promise}
174 mw
.Upload
.BookletLayout
.prototype.uploadFile = function () {
175 var file
= this.getFile();
177 this.filenameWidget
.setValue( file
.name
);
178 this.setPage( 'info' );
180 this.upload
.setFile( file
);
181 this.uploadPromise
= this.upload
.uploadToStash();
182 this.uploadPromise
.then( this.emit
.bind( this, 'fileUploaded' ) );
184 return this.uploadPromise
;
188 * Saves the stash finalizes upload. Uses
189 * {@link #getFilename getFilename}, and
190 * {@link #getText getText} to get details from
195 * @returns {jQuery.Promise} Rejects the promise with an
196 * {@link OO.ui.Error error}, or resolves if the upload was successful.
198 mw
.Upload
.BookletLayout
.prototype.saveFile = function () {
200 deferred
= $.Deferred();
202 this.upload
.setFilename( this.getFilename() );
203 this.upload
.setText( this.getText() );
205 this.uploadPromise
.always( function () {
207 if ( layout
.upload
.getState() === mw
.Upload
.State
.ERROR
) {
208 deferred
.reject( new OO
.ui
.Error( mw
.msg( 'upload-process-error' ) ) );
212 if ( layout
.upload
.getState() === mw
.Upload
.State
.WARNING
) {
213 deferred
.reject( new OO
.ui
.Error( mw
.msg( 'upload-process-error' ) ) );
217 layout
.upload
.finishStashUpload().always( function () {
220 if ( layout
.upload
.getState() === mw
.Upload
.State
.ERROR
) {
221 deferred
.reject( new OO
.ui
.Error( mw
.msg( 'upload-process-error' ) ) );
225 if ( layout
.upload
.getState() === mw
.Upload
.State
.WARNING
) {
226 deferred
.reject( new OO
.ui
.Error( mw
.msg( 'upload-process-warning' ) ) );
230 // Normalize page name and localise the 'File:' prefix
231 name
= new mw
.Title( 'File:' + layout
.upload
.getFilename() ).toString();
232 layout
.filenameUsageWidget
.setValue( '[[' + name
+ ']]' );
233 layout
.setPage( 'insert' );
236 layout
.emit( 'fileSaved' );
240 return deferred
.promise();
246 * Renders and returns the upload form and sets the
247 * {@link #uploadForm uploadForm} property.
251 * @returns {OO.ui.FormLayout}
253 mw
.Upload
.BookletLayout
.prototype.renderUploadForm = function () {
256 this.selectFileWidget
= new OO
.ui
.SelectFileWidget();
257 fieldset
= new OO
.ui
.FieldsetLayout( { label
: mw
.msg( 'upload-form-label-select-file' ) } );
258 fieldset
.addItems( [ this.selectFileWidget
] );
259 this.uploadForm
= new OO
.ui
.FormLayout( { items
: [ fieldset
] } );
262 this.selectFileWidget
.on( 'change', this.onUploadFormChange
.bind( this ) );
264 return this.uploadForm
;
268 * Handle change events to the upload form
273 mw
.Upload
.BookletLayout
.prototype.onUploadFormChange = function () {
274 this.emit( 'uploadValid', !!this.selectFileWidget
.getValue() );
278 * Renders and returns the information form for collecting
279 * metadata and sets the {@link #infoForm infoForm}
283 * @returns {OO.ui.FormLayout}
285 mw
.Upload
.BookletLayout
.prototype.renderInfoForm = function () {
288 this.filenameWidget
= new OO
.ui
.TextInputWidget( {
289 indicator
: 'required',
293 this.descriptionWidget
= new OO
.ui
.TextInputWidget( {
294 indicator
: 'required',
301 fieldset
= new OO
.ui
.FieldsetLayout( {
302 label
: mw
.msg( 'upload-form-label-infoform-title' )
305 new OO
.ui
.FieldLayout( this.filenameWidget
, {
306 label
: mw
.msg( 'upload-form-label-infoform-name' ),
309 new OO
.ui
.FieldLayout( this.descriptionWidget
, {
310 label
: mw
.msg( 'upload-form-label-infoform-description' ),
314 this.infoForm
= new OO
.ui
.FormLayout( { items
: [ fieldset
] } );
316 this.filenameWidget
.on( 'change', this.onInfoFormChange
.bind( this ) );
317 this.descriptionWidget
.on( 'change', this.onInfoFormChange
.bind( this ) );
319 return this.infoForm
;
323 * Handle change events to the info form
328 mw
.Upload
.BookletLayout
.prototype.onInfoFormChange = function () {
331 this.filenameWidget
.getValidity(),
332 this.descriptionWidget
.getValidity()
333 ).done( function () {
334 layout
.emit( 'infoValid', true );
335 } ).fail( function () {
336 layout
.emit( 'infoValid', false );
341 * Renders and returns the insert form to show file usage and
342 * sets the {@link #insertForm insertForm} property.
345 * @returns {OO.ui.FormLayout}
347 mw
.Upload
.BookletLayout
.prototype.renderInsertForm = function () {
350 this.filenameUsageWidget
= new OO
.ui
.TextInputWidget();
351 fieldset
= new OO
.ui
.FieldsetLayout( {
352 label
: mw
.msg( 'upload-form-label-usage-title' )
355 new OO
.ui
.FieldLayout( this.filenameUsageWidget
, {
356 label
: mw
.msg( 'upload-form-label-usage-filename' ),
360 this.insertForm
= new OO
.ui
.FormLayout( { items
: [ fieldset
] } );
362 return this.insertForm
;
368 * Gets the file object from the
369 * {@link #uploadForm upload form}.
372 * @returns {File|null}
374 mw
.Upload
.BookletLayout
.prototype.getFile = function () {
375 return this.selectFileWidget
.getValue();
379 * Gets the file name from the
380 * {@link #infoForm information form}.
385 mw
.Upload
.BookletLayout
.prototype.getFilename = function () {
386 return this.filenameWidget
.getValue();
390 * Gets the page text from the
391 * {@link #infoForm information form}.
396 mw
.Upload
.BookletLayout
.prototype.getText = function () {
397 return this.descriptionWidget
.getValue();
403 * Clear the values of all fields
407 mw
.Upload
.BookletLayout
.prototype.clear = function () {
408 this.selectFileWidget
.setValue( null );
409 this.filenameWidget
.setValue( null ).setValidityFlag( true );
410 this.descriptionWidget
.setValue( null ).setValidityFlag( true );
411 this.filenameUsageWidget
.setValue( null );
414 }( jQuery
, mediaWiki
) );