Wikipedia:File upload wizard/doc

This page provides documentation for the experimental Wikipedia:File Upload Wizard, which is currently in testing stage.


The wizard consists of one normal wiki page, currently located at Wikipedia:File Upload Wizard, a page of client-side Javascript code, currently at MediaWiki:FileUploadWizard.js, and a corresponding .css page, currently at MediaWiki:FileUploadWizard.css. Almost all of the text content used by the wizard (forms, prompts, warnings etc.) is contained as standard wikitext in the main page, inside hidden <div>-elements and nested tables. Interactive elements that cannot be created by normal wiki text (<form> elements, buttons, input text fields, dropdowns boxes etc.) are created by the Javascript when the page loads. Empty <span id="placeholderXYZ"/> elements in the wikitext mark the positions where they will be inserted. To activate the Javascript, the wikipage must be loaded with a withJS= parameter.

The Javascript code has been tested with the Firefox 10.0 browser so far. It makes some use of the jQuery library, which is commonly used in Wikipedia scripts. Data used during the input and upload process are stored in a Javascript object named window.fuw. A representation of the input data present at any given time during the input process is cached in window.fuw.opts, and data representing the current status of various warning conditions (e.g. bad filenames, missing target articles etc.) are stored in window.fuw.warn.

The most important functions of the script are:

The constructor function of the global window.fuw object, executed once when the page loads. It creates the interactive form elements (buttons, text fields etc.) and sets the initial visibility of the main form area.
The onChange event handler shared by most of the input elements. It collects the input from all currently active input fields, updates the cached contents of the window.fuw.opts object from it, and switches visibility and enabled/disabled status for the various subsections of the questionnaire in response to the current status of the option radio-buttons. It also shows and hides various warning messages in response to the result of previous validation routines stored in window.fuw.warn.
Called at the end of each fuwUpdateOptions(), this function determines whether the current state of input data is complete and sufficient for uploading. The fuwUpdateOptions() function will enable or disable the submit button in response to this validation. (Possible alternative: keep the submit button always enabled and run validateInput() only when it's clicked, showing a warning message if false. Which is more user-friendly?)
This function collects the input data from the window.fuw.opts object and assembles a set of window.fuw.descFields from them, representing the strings that are to be written into the fields of the description template.
Called immediately after collectInput(), before uploading. This function assembles the code of the actual description page from the window.fuw.descFields object and the license tags, and prepares it for upload, either in local upload mode or in Commons upload mode. For local upload, it writes the resulting values into the hidden <input type="hidden"/> elements of the TargetForm, from where they are submitted to the API. In Commons mode, the description wikitext is assembled into a parameter string to be appended to the URL for the Commons Special:Upload page, pre-loading the value into the standard Commons upload form.

In the current testing version, this function is also called at the end of each fuwUpdateOptions() call, in order to maintain a constant preview of the output for testing purposes. In the final version, it will be sufficient to have it called only once, from the onClick event of the submit button (after validateInput() has returned true).

Server interaction[]

The questionnaire page currently contains three separate <form> elements. The first, <form id="fuwTargetForm">, is the one that is actually used for uploading. The only overt element contained in it is the file selection box. All other upload parameters are present in the form of <input type="hidden"/> elements, whose values are filled in prior to uploading by the fuw.collectInput() function.

The upload is done via a standard form.submit() from this target form, with the form's action set to the // interface. The API's return message is diverted into a hidden <iframe> element, whose onLoad event then triggers the function that displays the success message and hides the main questionnaire (thus "faking" an asynchronous AJAX call – this is necessary because a normal AJAX call cannot access file upload data).

The second <form> element, <form id="fuwScriptForm">, contains all the other visible controls of the input questionnaire.

In the testing version, there is a third <form> element, <form id="fuwTestForm">, which contains the preview fields at the bottom of the page.

Apart from the main upload action, the script sends additional server requests in the following situations. All of these are submitted via asynchronous AJAX requests to the api.php interface, using the jQuery ajax wrapper $.ajax([...]).

The questionnaire[]

The questionnaire currently has twelve sub-sections designed for twelve different types of files, five of them free and seven non-free.

Free file options
Non-free file options

User experience levels[]

The script attempts to recognize the following status levels of the current user, based on information taken partly from the standard mw.config variables and partly from a call to the API:


The script will stop and only display a notification message if run by a logged-out user, since logged-out users can't upload files.


The script will display a notification that users who are not yet autoconfirmed can't upload files locally. However, the rest of the script will run normally for them, with only the "local upload" submit button greyed out but the "upload to Commons" button active.

The following distinctions can also be made but do not currently lead to any actual differences in behaviour of the script:


Status set if the user has fewer than 100 s. Such users might be offered a somewhat more gentle and detailed set of instructions in the future.

"Problem user"

Status set if the user has had more than 3 image-related standard warnings on their talkpage among the latest 30 talkpage s. Such users might be offered a somewhat more urgently worded set of copyright-related instructions in the future.


All other users; these users might be offered a somewhat shorter and less wordy set of instructions in the future.


The wizard produces image description pages following the standard format:

== Summary ==
{{... [description template with parameters] ...}}
== Licensing ==
{{... [license tag] ...}}

For free files, it uses the standard {{Information}} template. For non-free files, it uses a new {{Non-free use rationale 2}} template, differing from the more common {{Non-free use rationale}} in a few details. Its parameters are designed to correspond to the individual NFCCs more closely than the old template, and also to be compatible with those of the free {{Information}} template wherever possible.

Fair use rationales[]

The fair use rationale template uses the following parameters:

{{Non-free use rationale 2
| Description       = 
| Author            =
| Publication       = (optional)
| Source            = 
| Article           = 
| Purpose           =
| Replaceability    =
| Replaceability_text = (optional)
| Minimality        =
| Commercial        =
| Other information = (optional)

The different sub-options described above are chosen in such a way that each of them corresponds to a typical situation where certain FUR fields are either important or trivial/predictable. The wizard will automatically provide brief pre-filled standard statements (sometimes as short as "n.a.") for the predictable parameters in each case. The combination of pre-filled and user-provided parts is as follows ("minimality" always requires manual input):

"Subject of commentary", in dedicated article
| Purpose = For visual identification of the object of the article. The article as a whole is dedicated specifically to a discussion of this work.
| Replaceability    = n.a.
| Commercial        = n.a.
"Subject of commentary", not in dedicated article
| Purpose = To support encyclopedic discussion of this work in this article. The illustration is specifically needed to support the following point(s): [user input]
| Replaceability = n.a.
| Commercial = n.a.
| Purpose = [user input]
| Replaceability = n.a.
| Replaceability_text = [user input]
| Commercial = n.a.
"Cover art"
| Purpose = to serve as the primary means of visual identification at the top of the article dedicated to the work in question.
| Replaceability = n.a.
| Commercial = n.a.
| Purpose = to serve as the primary means of visual identification at the top of the article dedicated to the entity in question.
| Replaceability = n.a.
| Commercial = n.a.
| Purpose = for visual identification of the person in question, at the top of his/her biographical article
| Replaceability = [user input]
| Commercial = [user input]
| Other information = The subject of the photograph has been deceased since: [user input] 
| Purpose = [user input]
| Replaceability = [user input]
| Replaceability_text = [user input]
| Commercial = [user input]