Expand all

mw.Upload.BookletLayout

Encapsulates the process of uploading a file to MediaWiki using the upload model. The booklet emits events that can be used to get the stashed upload and the final file. It can be extended to accept additional fields from the user for specific scenarios like for Commons, or campaigns.

Structure

The booklet layout has three steps:

  • Upload: Has a field to get the file object.

  • Information: Has a form to collect metadata. This can be extended.

  • Insert: Has details on how to use the file that was uploaded.

Each step has a form associated with it defined in renderUploadForm, renderInfoForm, and renderInfoForm. The getFile, getFilename, and getText methods are used to get the information filled in these forms, required to call mw.Upload.

Usage

See the upload dialog.

The fileUploaded, and fileSaved events can be used to get details of the upload.

Extending

To extend using mw.Upload, override renderInfoForm to render the form required for the specific use-case. Update the getFilename, and getText methods to return data from your newly created form. If you added new fields you'll also have to update the mw.Upload.BookletLayout#clear method.

If you plan to use a different upload model, apart from what is mentioned above, you'll also have to override the createUpload method to return the new model. The saveFile, and the uploadFile methods need to be overridden to use the new model and data returned from the forms.

Extends

Constructor

new mw.Upload.BookletLayout(config) #

Create an instance of mw.Upload.BookletLayout.

Parameters:

Name Type Description
config Object

Configuration options; see also the config parameter for the mw.Upload.BookletLayout constructor.

Properties:
Name Type Attributes Description
$overlay jQuery optional

Overlay to use for widgets in the booklet
filekey string optional

Sets the stashed file to finish uploading. Overrides most of the file selection process, and fetches a thumbnail from the server.
Source:

Properties

infoForm :OO.ui.FormLayout #

The form rendered in the second step to get metadata. Rendered in renderInfoForm.

Type:

Source:
The form rendered in the second step to get metadata.

insertForm :OO.ui.FormLayout #

The form rendered in the third step to show usage. Rendered in renderInsertForm.

Type:

Source:
The form rendered in the third step to show usage.

uploadForm :OO.ui.FormLayout #

The form rendered in the first step to get the file object. Rendered in renderUploadForm.

Type:

Source:
The form rendered in the first step to get the file object.

Methods

clear()protected #

Clear the values of all fields.

Source:
Clear the values of all fields.

createUpload() → {mw.Upload}protected #

Create a new upload model.

Source:

Returns:

Upload model

Type
mw.Upload
Create a new upload model.

getErrorMessageForStateDetails() → {jQuery.Promise|undefined}protected #

Get an error message (as OO.ui.Error object) that should be displayed to the user for current state and state details.

Source:

Returns:

A Promise that will be resolved with an OO.ui.Error.

Type
jQuery.Promise | undefined

Get an error message (as OO.ui.Error object) that should be displayed to the user for current state and state details.

getFile() → {File|null}protected #

Gets the file object from the upload form.

Source:

Returns:

Type
File | null

Gets the file object from the upload form.

getFileWidget() → {OO.ui.SelectFileInputWidget|mw.widgets.StashedFileWidget} #

Gets the widget for displaying or inputting the file to upload.

Source:

Returns:

Type
OO.ui.SelectFileInputWidget | mw.widgets.StashedFileWidget
Gets the widget for displaying or inputting the file to upload.

getFilename() → {string}protected #

Gets the file name from the information form.

Source:

Returns:

Type
string

Gets the file name from the information form.

getText() → {string}protected #

Gets the page text from the information form.

Source:

Returns:

Type
string

Gets the page text from the information form.

initialize() → {jQuery.Promise} #

Initialize for a new upload.

Source:

Returns:

Promise resolved when everything is initialized

Type
jQuery.Promise
Initialize for a new upload.

onInfoFormChange()protected #

Handle change events to the info form.

Source:

Fires:

Handle change events to the info form.

onUploadFormChange()protected #

Handle change events to the upload form.

Source:

Fires:

Handle change events to the upload form.

renderInfoForm() → {OO.ui.FormLayout}protected #

Renders and returns the information form for collecting metadata and sets the infoForm property.

Source:

Returns:

Type
OO.ui.FormLayout

Renders and returns the information form for collecting metadata and sets the infoForm property.

renderInsertForm() → {OO.ui.FormLayout}protected #

Renders and returns the insert form to show file usage and sets the insertForm property.

Source:

Returns:

Type
OO.ui.FormLayout

Renders and returns the insert form to show file usage and sets the insertForm property.

renderUploadForm() → {OO.ui.FormLayout}protected #

Renders and returns the upload form and sets the uploadForm property.

Source:

Returns:

Type
OO.ui.FormLayout

Renders and returns the upload form and sets the uploadForm property.

saveFile() → {jQuery.Promise}protected #

Saves the stash finalizes upload. Uses getFilename, and getText to get details from the form.

Source:

Returns:

Rejects the promise with an error, or resolves if the upload was successful.

Type
jQuery.Promise

Fires:

Saves the stash finalizes upload.

setFile(file)protected #

Sets the file object.

Parameters:

Name Type Description
file File | null

File to select
Source:
Sets the file object.

setFilekey(filekey)protected #

Sets the filekey of a file already stashed on the server as the target of this upload operation.

Parameters:

Name Type Description
filekey string
Source:

Sets the filekey of a file already stashed on the server as the target of this upload operation.

setFilename(filename)protected #

Prefills the information form with the given filename.

Parameters:

Name Type Description
filename string
Source:
Prefills the information form with the given filename.

updateFilePreview()protected #

Updates the file preview on the info form when a file is added.

Source:
Updates the file preview on the info form when a file is added.

uploadFile() → {jQuery.Promise}protected #

Uploads the file that was added in the upload form. Uses getFile to get the HTML5 file object.

Source:

Returns:

Type
jQuery.Promise

Fires:

Uploads the file that was added in the upload form.

Events

fileSaved(imageInfo) #

The file has been saved to the database.

Parameters:

Name Type Description
imageInfo Object

See mw.Upload#getImageInfo
Source:
The file has been saved to the database.

fileUploadProgress(progress, duration) #

Progress events for the uploaded file.

Parameters:

Name Type Description
progress number

In percentage
duration Object

Duration object from moment.duration()
Source:
Progress events for the uploaded file.

fileUploaded() #

The file has finished uploading.

Source:
The file has finished uploading.

infoValid(isValid) #

The info form has changed.

Parameters:

Name Type Description
isValid boolean

The form is valid
Source:
The info form has changed.

uploadValid(isValid) #

The upload form has changed.

Parameters:

Name Type Description
isValid boolean

The form is valid
Source:
The upload form has changed.