UploadWizard/Software design/front-end

Developers' guide to UploadWizard
The main overview: a simple PHP script is invoked via Special:UploadWizard.

For older/incompatible browsers, this simply shows the basic upload form. For most / modern browsers, this loads a funky Javascript application which under normal circumstances does not reload the page, but shows a multi-step wizard with Javascript techniques. It manages most interactions via the API and dynamic HTML construction.

We have also written a lot of stuff related to stashed uploads that lives in includes/filerepo and includes/upload.

The usual boilerplate

 * UploadWizard.alias.php -- page name in various languages
 * UploadWizard.i18n.php -- message strings
 * UploadWizardHooks.php -- Resource Loader package definition
 * UploadWizard.php -- the usual boilerplate, simply includes all the files needed, and registers Special:UploadWizard
 * SpecialUploadWizard.php -- where the special page starts! Basic HTML is laid down here, which is enhanced by UploadWizard.js.
 * UploadWizard.config.php -- a configuration file in PHP. Can be overridden by similar config in LocalSettings, in $wgUploadWizardConfig.
 * UploadWizardPage.js -- kicks off the javascript on the page, creates an mw.UploadWizard object and populates it.

Loading resources
We are using ResourceLoader.

Javascript and resources
All of the main meat of this extension is in the JavaScript, and ancillary files, which are located in UploadWizard/resources.

Objects are usually placed into the mediaWiki namespace, which is usually aliased to mw. Some jQuery extensions go into the jQuery namespace. Typically $j is used for Javascript, rather than $.

Each file is usually wrapped with the formula:

( function( mw, $j ) {  ... code here ... } ( mediaWiki, jQuery ) );

which aliases the global mediaWiki and jQuery objects into some local abbreviations.


 * mw.UploadWizard.js -- contains two main objects.
 * mw.UploadWizard -- the object that represents the entire UploadWizard. It is responsible for:
 * setting up the different "steps" -- which are just divs that are hidden and shown -- and the buttons to to the next step (or retry the current step)
 * transitioning between "steps"
 * keeping track of all the uploads, in an uploads property
 * handling simultaneous uploads, and having the interface respond instantly to changes in the state of each upload, and detecting when all the uploads are in a state where it's good to procceed.
 * running the progress bar
 * mw.UploadWizardUpload -- object that represents an Upload
 * contains all data extracted locally about the file, or from API calls -- includes thumbnails, imageinfo, filename, title, etc.
 * handles the actual upload (via other libraries; it is possible to swap its upload method with a mock uploader, for instance, when testing.)
 * has a ui property which points to an "UploadWizardUploadInterface" object.
 * mw.UploadWizardUploadInterface.js
 * mw.UploadWizardUploadInterface -- represents the interface of an Upload (only on page 1, where we are actually uploading the data).
 * each upload has a ui property, this is an mw.UploadWizardUploadInterface.
 * responsible for showing appropriate interface as the upload proceeds, showing errors, etc.