Wikipedia:File upload wizard/doc

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

Architecture

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:

fuwGlobal()

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.

fuwUpdateOptions()

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.

fuw.validateInput()

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?)

fuw.collectInput()

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.

fuw.formatOutput()

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 //en.wiki.x.io/w/api.php 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([...]).

• On loading, the script retrieves the current user's edit count and the edit summaries of the latest 30 edits to their user talk page. The edit summaries are then scanned for signs of image-related warnings, such as those left by ImageTaggingBot. From this information, the script attempts to make a rough estimation of the user's experience level. This information is not currently used in practice, but may be used in future to choose between different versions of some of the instructions (see below).
• When the user enters the intended Wikipedia filename, the script retrieves image information to determine whether a file of this name already exists, either locally or on Commons, in order to prevent the user from unintentionally overwriting a file.
• For non-free files, when the user enters the intended article name, the script retrieves page information to determine whether that page exists, whether it is a disambiguation page, or whether it is a redirect (in which case it will automatically correct it to the redirect target). This is done to enforce WP:NFCC#10c compliance.
• After a successful upload, the script retrieves image information about it once more. This is needed in order to get the url and size information about a thumbnail of the new image, which is then displayed in the success message.
• If the user has chosen to overwrite an existing file and has also added new data for the description page, the page content is sent off as a separate API edit request, because the standard upload action will not modify the textual contents of the page.

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

• Own work: contains the standard parameters (license, date) as well as a question about "how did you make this?" (trying to discourage uploaders from making false blanket "own work" claims), and an option for naming a source if the item was previously published elsewhere
• Third party: designed for the frequent "somebody gave this to me" scenario. Asks for details about how the uploader acquired the permission, and prepares them for the need to provide evidence.
• Free website: designed for Flickr and similar external sources. Asks for separate sourcing for the file itself and the licensing.
• PD-old: contains detailed questions about the original publication history of the item (when and where published, lifetime of creator etc.). Options for three standard PD scenarios: published before 1929; published abroad and PD in the home country before URAA date (i.e. typically 70 years p.m.a. before 1996); and published in US without copyright notice and/or registration
• Other PD: options for PD-USGov, PD-ineligible and others.

Non-free file options

• Subject of commentary: designed for {{Non-free 2D art}}, historic photographs and other items, in those cases where the non-free item is the object of explicit commentary. Asks the uploader either to confirm that the whole article is dedicated to this particular work, or to name and describe the specific passage where it's discussed. Under these conditions it produces a standard FUR with everything else except the "minimality" argument pre-filled.
• 3D art: mostly like the foregoing, but with additional input fields describing the copyright status of the photograph as opposed to the non-free 3D work depicted. Will insist that the 2D depiction be either freely licensed (e.g. self-made), or provided by the author of the underlying 3D work (as is frequently the case e.g. with computer renderings of projected buildings)
• Excerpt: designed for TV and movie screenshots, audio samples etc. Places a lot of emphasis on the "purpose" and "replaceability with text" FUR arguments. Other FUR parts will be filled with standard values.
• Cover art: designed for book covers etc. Asks for confirmation that the item is going to be used in the canonical way ("primary visual identification" at top of dedicated article). Will produce a standard rationale only for this case.
• Logo: similar to the foregoing, produces standard pre-filled rationale but insists on confirmation of canonical usage scenario.
• Historic portrait: designed for the frequent case of historic photographs used in biography articles, allowing for the standard FUR argument about non-replaceability with deceased persons. Asks for detailed source info and insists on explicit replaceability argument (uploader should demonstrate possible alternatives have actually been considered), as well as "commercial opportunities" argument.
• Miscellaneous: generic non-free use, designed for everything, including any of the standard types of items (historic photographs, artworks etc.) when used in any except the standard usage scenarios treated above. Asks for FUR input for each of the major NFCCs, without standard prefilled values.

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:

Logged-out

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.

Unconfirmed

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:

"Newbie"

Status set if the user has fewer than 100 edits. 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 edits. Such users might be offered a somewhat more urgently worded set of copyright-related instructions in the future.

"Regular"/"Admin"

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

Output

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.

"Excerpt"

| 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.

"Logo"

| 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.

"Portrait"

| 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] 

"Miscellaneous"

| Purpose = [user input]
| Replaceability = [user input]
| Replaceability_text = [user input]
| Commercial = [user input]