Jump to content

Upload dialog

From mediawiki.org
MediaWiki version:

The upload dialog (also known as foreign upload tool or cross-wiki upload tool) is available in VisualEditor and wikitext editor on Wikimedia wikis. It's not available for users who disabled "enhanced editing toolbar" or "wizards for inserting links, tables" in their preferences. It can also be used outside of these contexts, like in a Gadget or extension. See API documentation for instructions and details.

The dialog allows any registered user to upload a file to the wiki directly from the editor, guiding them through the process. On Wikimedia wikis, it is configured to only allow self-made files under the CC BY-SA license and upload them from any Wikimedia wiki to Wikimedia Commons. Its interface is inspired by UploadWizard , but much more limited (in particular, it only allows uploading one file at a time and only allows providing a simple description in one language).

While it's a part of MediaWiki core, the upload dialog is not currently available from the default wikitext editor. You need to install one of the editing interface extensions to use it: VisualEditor or WikiEditor .

Accessing the upload dialog[edit]

In visual editor[edit]

Insert → Media Upload

In wikitext editor[edit]

"Embedded file" icon Upload


Screenshot of the first page of media upload dialog in the visual editor. In the first step, the user is asked to select a file to upload and to confirm that the file complies with licensing policies of the wiki.

$wgUploadDialog can be used to configure more specific messages.

On Wikimedia wikis, the dialog is configured to ask the user to confirm that they're the file's author and are willing to release it under the CC BY-SA 4.0 license. The tool recommends UploadWizard as an alternative in more complicated cases.

Screenshot of the second page of media upload dialog in the visual editor. In the second and final step, the user is asked to fill in the details: the file name and, by default, the description.

If enabled in $wgUploadDialog , fields for categories (with autocompletion) and file creation date are also available.

On Wikimedia wikis all fields are enabled.

Afterwards the user returns back to the previous dialog, where they can fill in the thumbnail caption and other details.

Configuration (for wiki sysadmins)[edit]

The dialog should be available by default on any wiki using MediaWiki 1.27 or newer that has file uploads enabled . Note that the WikiEditor extension is required for the tool to be available from the wikitext editing toolbar (it is also available in VisualEditor ). Starting with MediaWiki 1.28 (but not 1.27), it can be disabled by setting $wgForeignUploadTargets to [].

Some aspects of the dialog (fields to display, the licensing options, special formatting for the file page and upload comment) can be configured using $wgUploadDialog .

By default the uploads go to the local wiki. To configure cross-wiki uploads, you'll need to configure $wgForeignFileRepos and $wgForeignUploadTargets on all of the "source" wikis and $wgCrossSiteAJAXdomains on the "target" wiki. Only the target wiki has to have uploads enabled. Note that the $wgUploadDialog configuration for the target wiki will be used, not the source wiki.


Wikimedia wikis are configured to perform cross-wiki uploads to Wikimedia Commons. Additionally, https://test2.wikipedia.org/ is configured to perform uploads to https://test.wikipedia.org/. See the configuration variables mentioned above in InitialiseSettings.php, CommonSettings.php, filebackend.php.

Some statistics on usage in 2017 from VisualEditor and WikiEditor are available (about 3000 uploads per day, of which some 25 % from WikiEditor).

API documentation[edit]

The upload dialog is implemented using mw.ForeignStructuredUpload and mw.ForeignStructuredUpload.BookletLayout, which build upon simpler components. See OOUI/Windows for documentation about OOUI dialogs.

Upload API handling Rendering the interface Displaying the dialog
Local uploads mw.Upload mw.Upload.BookletLayout mw.Upload.Dialog
Support for cross-wiki uploads mw.ForeignUpload
Structured fields with support for cross-wiki uploads mw.ForeignStructuredUpload mw.ForeignStructuredUpload.BookletLayout