MediaWiki:UploadForm.js/Documentation

From Wikimedia Commons, the free media repository
Jump to: navigation, search

MediaWiki:UploadForm.js is a script that enhances the standard upload form on Commons, adding several new input fields and input validation. The script automatically constructs a {{information}} template from the inputs. It makes use of HotCat for the input of categories for the media file to be uploaded.

The new upload form offers separate input fields, automatic generation of an {{information}} template, input validation, page preview, integrated help in popups, license preview in a popup, per-language descriptions in any number, and category input using HotCat.

Browser compatibility

MediaWiki:UploadForm.js has been tested and is known to work on the following browsers:

Firefox 3 ✓OK FF 3b4 on Win XP Pro, SP2
Firefox 2 ✓OK FF 2.0.0.11/12 on Win XP Pro, SP2
Internet Explorer 8 Symbol question.svg unknown
Internet Explorer 7 ✓OK confirmed 2008-02-24
Internet Explorer 6 ✓OK Win XP Pro, SP2
Konqueror ✓OK
Opera ✓OK Opera 9.26 and Opera 9.50b on Win XP, SP2
Safari 3/Mac ✓OK Safari 3.0.4 on OSX (10.4.11)
Safari 3/Win ✓OK Safari 3.0.4 & 3.1.1 on Win XP Pro, SP2
Safari 2/Mac X mark.svg Not OK The script will not be loaded for WebKits version <420.
Users should upgrade their browsers to Safari 3.
Safari 2/Win Symbol neutral vote.svg don't care Early Safari versions for Windows are known to be buggy.
We don't cater to broken browsers (well, except IE :-)
Users should upgrade their browsers to Safari 3.
Firefox 1.5 Symbol question.svg unknown needed?
IE/Mac Symbol question.svg unknown needed?
IE 5.5 Symbol question.svg unknown needed?

Additionally, the script has been tested on all skins using Firefox 2.

Like for many other scripts at Wikimedia projects, a DOM Level 2 compatible browser is a prerequisite. Ajax is used for the license preview, the page preview, and the category suggestions in HotCat.

If Javascript is disabled, the script will of course not modify the upload form. If Javascript is enabled, but Ajax is disabled, the script will still change the upload form, but the license preview and the page preview won't work, and HotCat won't be able to propose suggestions for categories.

How does this script work?

By default, this script takes the standard upload form and modifies it to have separate input fields for all the fields of {{information}}: source, author, date, description, permission, and other versions. (For an exception, see "From Wikimedia" uploads below.) Additionally, this script also forces the loading of MediaWiki:Gadget-HotCat.js, which adds a user-friendly input mechanism for defining categories. When the user clicks on the "upload" button, the script intercepts the form submission and then checks the values entered. The upload is allowed to proceed only if this input validation is successful, otherwise, the user is shown an error message explaining what should be corrected. Input fields where a problem is detected are highlighted.

In particular, the script checks that:

  • The destination file name (the name of the file after it has been uploaded to the Wiki) makes sense: it mustn't be empty; non-descript names are forbidden (names not containing alphanumeric characters, or only digits, or common simple names like "Test.jpg" or also "DSC00065.jpg"); it must have exactly one file extension, which moreover must be one of the allowed file types; it must not be a URL, and it must not contain slashes ("/").
  • The author, the source, and a license must be specified. If no license has been selected in the drop down menu, the script also checks whether there's a license template in the description fields, the permission field, or in the field for additional info: it can recognize the various PD, CC, GFDL, GPL, LGPL, Attribution, Copyrighted free use, and user-defined templates (if those are subpages of the user's user page). Note that user-defined license templates must be subst'ed. Writing "{{User:Foo/my_license}}" is not recognized as a license, but "{{subst:User:Foo/my_license}}" is.
  • A description must be given.

If the input validation succeeds, the script put together an {{information}} template automatically from the various input fields and sends the upload to the servers.

If Ajax is enabled, the script also adds a "preview" button next to the upload button. If clicked, the script tries to display above the upload form a preview of the image description page as it will look after the upload (minus categories and also without the image thumbnail, as the image hasn't yet been uploaded). The preview button is added in both full and basic mode.

For the technically inclined: the preview uses the standard API functionality for parsing Wikitext into XHTML, which is available as of MediaWiki 1.12.

Text sanitation

The script tries to guard against malformed user input in the various fields. If these contain erroneous wikitext, it is possible that the final {{information}} template is not displayed correctly on the image page. (That could also happen in the old upload form that didn't use this script. An example of such erroneous input are unclosed templates or links in a field of the {{information}} template.) In particular, the script tries to prevent and correct:

  • Mismatched template ({{ and }}), table ({| and |} at the beginning of a line) or link ([ or ], or [[ and ]]) delimiters. Extra closing delimiters found are replaced by their literal characters, using numeric HTML character entities. If there are missing closing delimiters, they are inserted.
  • Image links (Beginning with "[[Image:") that either are not thumbnails or have no size or a size larger than 299 pixels given are transformed into plain links beginning with "[[:Image:".

The transformations done by text sanitation will in general leave correct wikitext intact. However, the text is cleaned up without expanding templates. In pathological rare cases involving templates it is thus possible that even sanitized text breaks the final display of the {{information}} template. But on "normal" input, that shouldn't happen.

Working together with other scripts

MediaWiki:UploadForm.js uses the following other scripts:

Script Purpose Type of
dependency
Effect if not present
MediaWiki:UIElements.js Support for reading the help texts and other elements of the user interface from the DOM. required, but can work in degraded mode without The form will be presented with English labels and error messages, and there won't be any help texts nor any fancy buttons.
MediaWiki:Gadget-HotCat.js Input of categories optional No enhanced category input. Categories must be added to the description field manually.
MediaWiki:TextCleaner.js Sanitation of user input optional Erroneous user input (such as an unclosed {{en}} template) may break the display of the final {{information}} template.
MediaWiki:LanguageHandler.js Support for the language dropdown to the left of the description fields optional The form uses only one description field. Users must type the language templates themselves (such as {{en}} and so on).
MediaWiki:Tooltips.js Pop-up elements optional Help texts will be displayed below the fields instead. Page preview is above the form, and license preview remains unchanged below the license selector.
MediaWiki:FormRestorer.js Support for properly restoring previous values in full mode optional The dynamically modified form fields in full mode cannot be restored in some cases to the values the user last entered when the form is navigated to through the browser's back button.
MediaWiki:Edittools.js Edit toolbar with buttons for inserting special characters or tags in text fields none If there's no edit bar, the upload form continues to work normally. Otherwise, if there is an edit bar, the UploadForm script makes sure that the edittools work in all fields.
MediaWiki:Upload.js Adds a license checker and pre-fills the description. none Pre-filling the description is overwritten by MediaWiki:UploadForm.js anyway, and the license checker from MediaWiki:Upload.js is completely orthogonal to the functionality of MediaWiki:UploadForm.js.
/skins-1.5/common/upload.js Adds an overwrite warning with preview and a license preview none The overwrite warning with preview functionality is completely orthogonal to the functionality of MediaWiki:UploadForm.js. For the license preview, see below. The preview button added by MediaWiki:UploadForm.js does not depend on this script.

If any other scripts have installed event handlers on the components of the upload form, MediaWiki:UploadForm.js takes care not to break or remove those already installed handlers. It adds its own event handlers in a way that ensures that possibly already installed event handlers are still called at the appropriate moments.

The upload form is also modified by a site-wide script of the MediaWiki software that lives at /skins-1.5/common/upload.js. This script is not editable through a Wiki page. It adds a license preview and an "overwrite warning" if someone tries to upload a file over an already existing file. The overwrite warning is completely orthogonal to the functionality of MediaWiki:UploadForm.js. The license preview is changed by MediaWiki:UploadForm.js to ensure it does not collide with its own warning messages. (For the technically inclined: if wgUploadLicenseObj.showPreview is defined, MediaWiki:UploadForm.js replaces it with its own function.)

Basic mode

In some cases, changing the upload form to have separate input fields instead of a single description field is cumbersome for the user. This is true especially if a user already has a {{information}} template ready and just wants to copy/paste that. Experienced users often work like that, and some tools (such as e.g. Flinfo for Flickr uploads) also produce full templates ready for copying.

For such cases, the script offers a "basic" mode with reduced functionality. In this basic mode, it does not change the input fields of the upload form at all, but it still does some checks:

  • The filename checks are still done.
  • It tries to verify that the the description does indeed contain a description, a source, and an author. (This only works if the description uses a known template. Currently, the script can handle the {{information}}, {{painting}}, and {{flickr}} templates. If the description does not contain one of these templates, or if the script fails to extract the fields for source, author, and description, the only check made is that the description field isn't empty. If {{painting}} is used, the description in the "Notes" field is actually not enforced.)
  • If no license has been selected, the script also checks whether there's a license template in the description. However, since the basic mode is likely to be used by more experienced contributors, who are more likely to use very specialized license templates (and sometimes even meta-templates that include a license only when evaluated), the script just checks whether there is any template inclusion at all. Otherwise, it would reject too many uploads, because it has no way of knowing that some template "{{foo}}" will ultimately include a valid license template.

This basic mode can be triggered in several ways:

  1. by adding the parameter "uploadformstyle=basic" to the URL, or
  2. by clicking here or going to your preferences page, clicking on the "Gadgets" tab and then disabling the entry "ImprovedUploadFormd On Special:Upload, show an easier form and help. [documentation / talk] "
  3. DEPRECATED and not recommended: by a user adding the following code to his (or her) common.js file (or other skin-specific user script file):
var UploadForm_forcebasic = true;

The latter two options forces the basic mode for that user in all cases, while the first has an effect only on that particular invocation of the URL. See also user configurations below.

Additionally, the script uses the basic form if the interface language is set to '*fromwikimedia' or '*experienced'. See Customized upload forms. UploadForm_forcebasic and the uselang=experienced URL parameter only have an effect for autoconfirmed accounts. If the account in not autoconfirmed, the script uses the full mode.

Furthermore, the script uses the basic mode if the description initially contained a value when the server sent the form. This is normally the case when the server detects an error upon the first upload attempt, and re-sends the form for a re-upload attempt. In this case, all the information should already be in the description, and we don't want to split it apart and fill in separate fields since this would be too error-prone. Note that this also means that the basic mode can be forced if the upload form is invoked through a URL with an extra wpUploadDescription parameter, like here. If the description was initially empty but was set later by some other script, MediaWiki:UploadForm.js does not use the basic mode unless one of the other triggers is present.

Bypassing this script

MediaWiki:UploadForm.js can be bypassed completely to get the standard upload form as augmented only by the older script at MediaWiki:Upload.js, and by the site-wide script /skins-1.5/common/upload.js. To do so, the parameter uploadformstyle=plain must be added to the URL of the upload form, as here (English upload form, plain, all enhancements disabled).

The script also does not modify the upload form if any error occurs. If an error occurs after it has already begun changing the form, the script forces an automatic reload of the upload form, with enhancements disabled (i.e., with this uploadformstyle=plain parameter added). In this way, it should be ensured that the user always gets a usable upload form, even if something goes wrong in MediaWiki:UploadForm.js.

Multiple inclusions of the script

Since this script lives on-wiki, inexperienced users might end up including it several times (for instance, once from MediaWiki:Common.js, and a second time from their own monobook.js). The script guards against this and ensures that the upload form will be changed only exactly once. This also means that all those test links mentioned here will continue working properly even once the script has been enabled in MediaWiki:Common.js for all users.

User configurations

Users may configure the script a little though their own JavaScript at monobook.js (or other skin-specific user script). Make sure that you force a reload to clear your browser's cache after any change to your user script: use shift-reload on Firefox, or ctrl-reload on Internet Explorer.

The following things can be configured:

Make the form always use basic mode

Users on an "autoconfirmed" account may force the script to always use its basic mode, which has the old form layout. To do so, go to preferences page, click on the "Gadgets" tab and then disable the entry "ImprovedUploadFormd On Special:Upload, show an easier form and help. [documentation / talk] ".

Set the field heights

The number of rows of the description field and of the "additional info" field can also be configured in monobook.js:

var UploadForm_description_height = 4;
var UploadForm_additional_info_height = 2;

The script limits the number of rows to sensible values. The minimum height is two rows (to which Firefox adds the height of a horizontal scrollbar because of a longstanding bug; other browsers indeed only display two rows), the maximum height is 12 rows.

Additionally, the number of rows of the source and of the author field can be configured. By default, the form uses single-line input fields for the source and the author and adds buttons to switch those to multi-line inputs. Users can configure these two fields to always be multi-line inputs by setting

var UploadForm_source_field_size = 4; // or some other number of rows
var UploadForm_author_field_size = 2; // or some other number of rows

The maximum number of rows for these fields is four.

Set the author field for "own work" uploads

By default, the script uses a simple link to the uploader's user page for the "author" field. To change that (e.g. to a link that shows your real name), add the following to your monobook.js:

var UploadForm_ownwork_author = "\[\[User:" + wgUserName + "|your real name\]\]";

Or, if you want to use the {{user}} template instead,

var UploadForm_ownwork_author = "\{\{User|" + wgUserName + "\}\}";

To make the script use your signature, use

var UploadForm_ownwork_author = "\~\~\~";

If the variable UploadForm_ownwork_author is null, not a string, or an empty string, or a string containing only whitespace, the script will ignore your definition and will revert to its default behavior.

Set the date field for "own work" uploads

By default, the script does not pre-fill the date field. If you want to have it set automatically to some value, define the variable UploadForm_ownwork_date in your monobook.js:

var UploadForm_ownwork_date = "See upload date below.";

Or, if you want it to be set to the current date, you could add the following bit of code to your monobook.js:

var UploadForm_ownwork_date = '\~\~\~\~\~';

(The MediaWiki software translates five tildes in a row ("~~~~~") into a timestamp when the page is saved.)

Note: in general, the "date" field should be the date you created the work, not the date you uploaded it. The upload date is known anyway.

If the variable UploadForm_ownwork_date is null, not defined, an empty string, or a string containing only whitespace, the script will ignore the definition and not set the date field.

Don't prefill the description field in basic mode

Some users have their own Javascript to prefill the description field of the basic form. By default, MediaWiki:UploadForm.js writes an {{information}}-template (partially prefilled for "ownwork" uploads) into this field, which would overwrite contents filled in by such user scripts. As a remedy, users can tell MediaWiki:UploadForm.js to leave the description field alone in basic mode:

var UploadForm_autofill = false;

If this variable is set to false, MediaWiki:UploadForm.js will not modify the contents of the description field, which should preserve any content placed there by other scripts.

The script will also not overwrite the description field in basic mode if it was set initially. See "Basic mode" above.

Initial languages for descriptions

Users can configure the languages for the description fields initially displayed. By default the script displays a description field for English, plus another field set to the user's interface language, if that is not English.

There are two ways to configure these description languages. To have the English description field below the one for your interface language, use

var UploadForm_own_language_first = true;

Alternatively, you can define exactly for which languages you want description fields. The definition

var UploadForm_description_languages = ['fr', 'en', 'de', 'qwerty', 'de-als'];

will result in an upload form with five description fields in the order given: French, English, German, Unknown language (because "qwerty" is not a valid language code), and German again (because "de-als" is not recognized as a language code either, but the part before the dash is).

UploadForm_description_languages must be defined as a array of strings. Always write the "[" and "]", even if you only give one string in between! Defining UploadForm_description_languages overrides any setting of UploadForm_own_language_first.

Page preview as a pop-up

By default, the page preview is displayed above the upload form, after the lead-in text. This mimics the behaviour of the normal page preview on edit pages. However, this means that it may be necessary to scroll up to see the page preview. As an alternative, you can turn the page preview into a pop-up by setting

var UploadForm_page_preview_in_tooltip = true;

The pop-up will appear above the "preview" button, covering parts of the upload form, so you will have to click it away before making further changes in your inputs.

Localization

The various labels and warning messages this script uses can be localized, such that the script displays the labels in the interface language of the user. (User's can define their preferred interface language in their preferences.) Localization (aka "internationalisation") of this script is done via MediaWiki messages. A "MediaWiki message" is a page in the "MediaWiki" namespace that is used by the server software. The user interface elements introduced by this script are unknown to the server software, but the script uses the same mechanism for localization.

The new upload form uses a lot of messages. There is one for each field label, one for each error message, and one for each help text. Additionally, the buttons added by this script also can be configured using MediaWiki messages.

Labels

The following MediaWiki messages contain the field labels for the new fields (shown are the current settings for English):

MediaWiki:UploadFormPreviewLicenseLabel is actually not a field label but a button text. It is used in degraded mode as the button text for the license preview button. MediaWiki:UploadFormOwnWorkLabel is used to pre-fill the "source" field for "own work" uploads. And MediaWiki:UploadFormUnknownLanguageLabel is used in the language drop-down menu to the left of the description fields.

These three messages must be simple strings; they must not contain Wikitext markup. The other messages may contain Wikitext markup such as links or even inline images. The only limitation is that the content of these messages must contain only inline XHTML elements (i.e., anything that may appear inside a <span>). Do not place complex things like tables, image thumbnails, or <p> or <div> tags in these messages!

Corresponding labels for other languages are defined on subpages of these MediaWiki messages. For instance, the labels in French are defined at these pages:

Hints

In full mode, the script displays short hints underneath some of the fields. These are very brief explanations of the most important things that should be entered there. More extended help is available through the pop-up help.

These hints may contain only inline XHTML elements. They all may contain wikilinks and other links, or small inline images, but no image thumbnails, tables, or other more advanced stuff. The script uses the following hints:


Again, translations for these hints are placed at subpages:

Error messages

If the input validation fails, the script displays some error messages to the user. These error messages are defined in the following MediaWiki messages:

Again, these messages may contain Wikitext markup, but they must contain only inline XHTML elements. They should be brief one-liners. Longer explanations can be put into the help texts.

Again, subpages identified by ISO 639 language codes are used to define the error messages for other interface languages. The French error messages are the following:

(Some translations may still be missing. Feel free to provide them!)

Buttons

Even the buttons used by this script can be localized using MediaWiki messages:

Click here to get help
Close this message

Button hover.svg

Button active.svg
+Add another description in another language
More lines
More lines
PreviewPreview the final image page. Does not upload yet!
Preview the chosen license

The first two buttons (MediaWiki:UploadFormHelpOpenButton for the "help" indicator, and MediaWiki:UploadFormHelpCloseButton for the "pop-up close button") are a bit special because they appear in special places. Both can be defined by including in the MediaWiki message up to three images for the normal, hover, and active states of the button. The image for the "hover" state is used when the mouse pointer is moved over the button, and the "active" image is used when the button is clicked. If only one image is given, there will be no visual effects on hover/click.

All three images should of course have the same size. The caption of the first image is used as the button's tooltip (the browser-generated little pop-up showing some alternate text). To clarify, the two buttons could be defined as follows:

  • MediaWiki:UploadFormHelpOpenButton:
    [[Image:Nuvola actions help.svg|14px|Help]]
    This will generate a help button like this: Help. There will be no visual effects when the mouse moves over the button or when the button is clicked.
  • MediaWiki:UploadFormHelpCloseButton:
    [[Image:Button normal.svg|14px|Close this message]]
    [[Image:Button hover.svg|14px]]
    [[Image:Button active.svg|14px]]
    This defines the pop-up close button to have visual effects. The tooltip will be "Close this message".

If these two buttons are not defined with images, the script uses alternate default behavior: if the "help open" button is not defined, a text link [?] is used instead. If the "help close" button is not defined, the pop-ups will not have a close button. They will close when the user clicks with the mouse anywhere inside the pop-up. (Pop-ups can always also be closed by clicking again on the button that opened them.)

The other buttons can be defined in exactly the same way, but they also support alternate text definitions. Their definition can be one of the following:

  • Up to three images. See above.
  • Two <span>s: the first span defines the button text, the second its tooltip text.
  • A single <span>: The span's content defines the button text, and there will be no browser-generated tooltip.
  • A simple text string: the string defines the button text, and there will be no browser-generated tooltip.

If you define a button graphically using images, please also add the template {{User script file}} to the image description pages:

{{User script file|MediaWiki:UploadForm.js}}

This marks the image as being used by a MediaWiki user interface extension and places it into Category:User script graphics.

Buttons can be localized like any other user interface element in subpages. The localized versions for French are these:

Aide
Fermer ce message

Button hover.svg

Button active.svg
+Ajouter une autre description dans une autre langue
Agrandir le champ
Agrandir le champ
PrévisualisationPrévisualiser la page du fichier. Le fichier ne sera pas encore enregistré!
Prévisualiser la licence choisie

Help texts

For each input field, there is at least one help text. For some fields, there may be even several help texts. A full list of all the English help texts is available at MediaWiki:UploadFormHelpTexts. Do not edit that page directly! Each of these help texts is defined in its own MediaWiki message:

Help texts in other languages can be defined at subpages again; for instance, the help text for the license selector in french should be at MediaWiki:UploadFormLicenseHelp/fr.

Help texts may use the full range of Wikitext markup, including multiple paragraphs, lists, images, tables, floats, or anything else. (Anything that may occur inside a <div> is allowed.)

Enabling a localization

Translating messages is only the first step in localizing the upload form. To make the translated texts known to the script, they need to be enabled. To enable localized messages (we'll use French as an example), do the following if you are an administrator:

This will enable all the French messages.

If any of the above messages have not been translated, but an English variant of the text exists, the script uses the English text and adds a translation plea. If a translation has been enabled in the appropriate subpage of MediaWiki:Uploadfooter, future changes to the MediaWiki messages for the texts become available automatically to the Script the next time the upload form is opened.

To enable a translation for some other language, proceed as for French, but replace "fr" by the appropriate ISO 639 language code, both in the choice of the subpage of MediaWiki:Uploadfooter and in the template parameter lang=.

Specializing a localization

For our customized upload forms, all these texts and buttons can even be specialized in appropriate subpages. For instance, if the help text for the "source" field for "own work" uploads should be different from the general help text for that field, redefine it at MediaWiki:UploadFormSourceHelp/ownwork and enable the messages at MediaWiki:Uploadfooter/ownwork. Attention: for customized upload forms, set the upload footer to the following:

{{MediaWiki:UploadFormTexts|live=1|useform=ownwork}}

To specialize texts for customized forms in other languages, use e.g. the "/frownwork" subpages (i.e., MediaWiki:UploadFormSourceHelp/frownwork and MediaWiki:Uploadfooter/frownwork), and set the upload footer to

{{MediaWiki:UploadFormTexts|live=1|lang=fr|useform=ownwork}}

For other customized forms, replace the useform parameter as appropriate, and set the lang parameter as desired.

Precedence of texts

The script looks for help texts in the following order:

  1. Specialized texts for the particular form in the user's interface language (e.g., "frownwork")
  2. Texts in the user's interface language (e.g., "fr")
  3. Specialized texts for the particular form in English (e.g., "ownwork")
  4. Texts in English

It uses the first text it finds. Whenever it doesn't find a text in the user's interface language, a translation plea link is added to the message text.

Translation pleas

If the script does not find any text in the user's interface language for a particular label, warning message, or help text, it uses the English texts as a fallback. In this case, it adds a small link "translate" (in the user's interface language!) to the label, warning message, or help text. If the user clicks that, he or she is taken to MediaWiki talk:UploadFormLabels/UploadFormTranslations, open for editing. (It's a talk page on purpose, so that anyone can edit it. The main MediaWiki namespace is editable only for administrators, but the MediaWiki-talk namespace is open for everyone.) There is another small script, MediaWiki:UploadFormTranslator.js, that is run when those translation links are clicked. This script pre-fills the edit box with the English default texts that should be translated. The user may then enter the translation in his or her language there. Administrators should have this page on their Watchlist and incorporate proposed translations into the appropriate MediaWiki messages (and, if necessary, should enable the messages for this language in the upload footer for that language).

Other labels

The script only supports localization of its own warning texts, and of the labels of the new fields it adds. Other labels (such as the one of the licensing drop-down, or of the target filename input field) are localized using the standard MediaWiki mechanism as described at Commons:Redesigning the upload form. The only exception to this is HotCat's "Categories" label. HotCat itself does not include localization support, and therefore MediaWiki:UploadForm.js takes care of it through its MediaWiki:UploadFormCategoriesLabel label.

Note: The label for the file on the user's computer that is to be uploaded currently says in many languages "Original file". Please make sure that this is changed to "Local file". The term "original file" can too easily be mistaken to mean the filename at the original source, or as the URL to the source. However, we do not allow direct uploads from other websites. Since MediaWiki:UploadForm.js adds a new input field for the source, the potential for confusion is even greater.

Configuring the introductory text

The upload form contains some lead-in text that is configured at MediaWiki:Uploadtext and subpages thereof. It may be necessary to adapt this text, because text that makes sense for the basic form may not be needed with the full new upload form. For instance, this text usually explains how to fill in an {{information}} template: because there is no such template to be filled in manually in the full version, that text is just not needed or may even be confusing as it instructs the user to put an {{information}} template into the description, but in the full version, that's precisely what the user should not do.

It is therefore necessary to mark up the texts at MediaWiki:Uploadtext in a way that allows the script to selectively hide or show parts of it. This can be done by wrapping the part that shall be visible only on the basic form in a <div id="wpUploadFormLongText">, and the part that is intended only for the full version in <div id="wpUploadFormShortText">. There are three possibilities:

<div id="wpUploadFormLongText">
  Default text
</div>
<div id="wpUploadFormShortText"
     style="display:none;">
  Alternate text
</div>
Completely independent texts. If the full version is used, only the alternate text is shown. The script hides wpUploadFormLongText and then shows wpUploadFormShortText. In basic mode, nothing is changed.

The style="display:none;" is important, otherwise, both texts would be shown by default.

<div id="wpUploadFormLongText">
  Default text
  <div id="wpUploadFormShortText">
    Alternate text
  </div>
  More default text
</div>
The default text contains the short text for the full form. In the full version, only the alternate text will be shown. The script hides wpUploadFormLongText and then extracts wpUploadFormShortText and shows only that. In basic mode, nothing is changed.
<div id="wpUploadFormShortText">
  Default text
  <div id="wpUploadFormLongText">
    Text only for the basic form
  </div>
  More default text
</div>
There is some part in the default text that isn't needed for the full form. The script will hide wpUploadFormLongText if the full mode is used. In basic mode, nothing is changed.
{{Information
|Description=
|Source=
|Date=
|Author=
|Permission=
|other_versions=
}}

Additionally, there is a similar legacy mechanism. Many of these introductory texts contain a rendering of the {{information}} template as shown on the right. If this is wrapped in a <div id="Uploadtext-template-box">, the script will hide it even in basic mode, since the description field is already pre-filled with such a template in basic mode.

Customized upload forms

The Commons has subverted MediaWiki's mechanism for user interface language customization to implement special-purpose upload forms. See Commons:Redesigning the upload form, and Manual:Uselang hack. Currently, there are five such special upload forms:

  • one for uploads of own works (uselang=*ownwork),
  • one for uploads from Flickr (uselang=*fromflickr),
  • one for experienced users (uselang=experienced),
  • one for uploads of works of the U.S. government (uselang=*fromgov), and
  • one for uploads from other Wikimedia projects (uselang=*fromwikimedia).

MediaWiki:UploadForm.js also works with these specialized upload forms.

Localization

See "specializing a localization" above.

"Own work" uploads

On "own work" upload forms, the source field will be prefilled with the localized text from MediaWiki:UploadFormOwnWorkLabel, and the author field will be prefilled with the user's account name.

"From Flickr" uploads

On "Flickr" upload forms, the script will require that the source be a URL pointing to the image at Flickr at http://www.flickr.com.

In basic mode, this URL check is not done.

"Experienced" upload form

The main difference between this and other upload forms is a minimal introductory text. For autoconfirmed users, the script will use its basic mode on these forms, but for new accounts, it will use the full mode.

"From Wikimedia" uploads

On the "fromwikimedia" forms, MediaWiki:UploadForm.js always uses its basic mode. These forms are designed to take all relevant information from the output of the CommonsHelper tool; people should run CommonsHelper and then either not use our form altogether and have CommonsHelper upload the file directly, or copy the whole {{information}} template it generates into the description field.

Making changes to this script

Please be extremely careful when you change MediaWiki:UploadForm.js or also MediaWiki:Gadget-HotCat.js. Since these two scripts are used on our upload form, any error may potentially affect a large number of users! If you want to make a larger change, copy the contents of the script to some other place in the MediaWiki namespace (for instance, to MediaWiki:UploadFormTest.js), make your changes there (test them by using a link like this: test link for upload form, German, "from Flickr" upload). Once it works perfectly on a variety of browsers (test it at least on Firefox and IE6), copy the contents of your test file to MediaWiki:UploadForm.js.

Please make sure that any change you make is DOM Level 2 compatible. Do not use DOM Level 3 functions! (For instance, document.adoptNode is DOM3. Use document.importNode (DOM2) instead.) DOM Level 2 is supported on a wider range of browsers.

If you add new labels, please also make sure to update the translation plea script MediaWiki:UploadFormTranslator.js to ask for a translation of the new label.

Reporting bugs

Bugs can be reported at MediaWiki talk:UploadForm.js. Mention what exactly went wrong (maybe even include a screenshot), and tell us what browser on what operating system you use, and also when the problem occurred. (The time in UTC may be important to determine whether a problem might have been caused by the servers having been slow.) If you're using Firefox, open the error log (in menu "Tools→Error Console") and check if there are any errors reported. If so, tell us what those error messages were. Thank you.

External links