UploadWizard/Software design

Some documentation for developers and reviewers interested in how UploadWizard works.

PHP (server side files)


 * New
 * includes/upload/UploadFromFileToStash.php
 * includes/upload/UploadBase.php
 * includes/upload/SessionStash.php
 * includes/specials/SpecialSessionStash.php
 * extensions/UploadWizard/SpecialUploadWizard.php
 * extensions/UploadWizard/UploadWizard.alias.php
 * extensions/UploadWizard/UploadWizard.i18n.php
 * extensions/UploadWizard/UploadWizardMessages.php (DEPRECATED in favor of Resource Loader)
 * extensions/UploadWizard/UploadWizardPage.php (Mostly DEPRECATED in favor of Resource


 * Modified
 * includes/upload/UploadFromFile.php
 * includes/api/ApiUpload.php
 * includes/filerepo/File.php


 * Changed config
 * includes/AutoLoader.php
 * includes/SpecialPage.php
 * languages/messages/MessagesEn.php

Javascript files -- to be documented --

Overview
UploadWizard is:
 * a multiple file uploader, with some "batch" capabilities
 * with a "wizard", step-by-step interface
 * with improved metadata and licensing entry
 * Designed to be deployed on Wikimedia Commons, although it should be useful for many other wikis

To achieve this, we've changed a lot about how uploads are accomplished.

The standard Mediawiki way


This is the how media uploads have worked for a long time with MediaWiki -- very simply.

The file is uploaded with an HTML form, along with wikitext for the File: page that will surround the image.

Each wiki page could be very different; there's little standard formatting.

However, we still use the base operation here -- to upload a media file with accompanying wikitext.

The Commons way


This is how Wikimedia Commons works in late 2010.

Nothing fundamental has changed here -- they are still uploading a media file with some associated wikitext. But it's being done just a little differently. There is more bureaucracy up front to try to categorize various media types. (At left we see only one example of many.) The user fills out a form, and some Javascript on the page creates equivalent wikitext, and sends that with the media file to the server.

There is much more preamble, as they feel they need to warn uploaders about Commons' licensing and interface requirements in very scary text.

The form page is very complicated, and has more structure and required fields, but ultimately it's just creating wikitext.

While an improvement over the previous version, the usability is now very poor. The page spends half its time warning you about bad things that can happen.


 * This is largely because they are still tied to an interaction model where it all comes down to just one click, which will add all the information to the database and publish the file almost immediately. Over time, Commons administrators have become very fed up with people who publish files which need to be taken down, and have piled on warning after warning.


 * Also, the page cannot provide sensible defaults for many of the fields since it has no way of analyzing the file itself.


 * The page doesn't have any structure flow to it -- it's just trying to amass as much information as possible in one go.


 * The page is just generally poorly organized, with questions about authorship and licensing scattered all over the page.


 * Mistakes or errors usually cause the user to lose work, and it's possible to make *many* mistakes since the form fields all inter-relate.


 * The interface elements can be somewhat bizarre and non-standard


 * Much screen real estate is given over to rarely-needed UI.

The UploadWizard way


UploadWizard at heart uses the same system -- associate a media file with wikitext. But it adds two new layers to the entire interaction.

The most obvious change is that we are shepherding multiple files through this process, at the same time.

On the client side, in the user's browser, we now have a "wizard" style interface flow. Information that is related is gathered at the same time, and then the user proceeds to the next step. For example, there's exactly one screen about licensing, and for the most part everything is handled there.

On the server side, we have a new way of storing data and media files that stops just short of publishing them to the Wiki.

This is important for us mostly due to a quirk of how web browsers have traditionally worked. Web browsers cannot analyze the files they are uploading or provide any information about them, not even a thumbnail -- they need help. The Firefogg extension is one kind of help, but the one that works with all browsers is to upload the file to the server and then ask it for what it can determine about these files. So UploadWizard first uploads the files to the server, and then it gets:
 * Thumbnails for each image (helpful for identifying multiple files!)
 * An analysis of the metadata in each file. For instance, many photos have information hidden within them that tells us when they were taken. We can use that information to prefill many form fields. (The user can still change them).

This new area is called the "Session Stash" because it is tied to the user's browsing session. If the user fails to complete all the steps of the process, the files will simply be deleted.

So the user can complete filling out all this information in relative peace, focusing on one thing at a time, not worrying if they've accidentally released an unlicensed file into the public sphere.

And then when they're ready, they can publish it to the wiki.