Extension:UploadWizard

MediaWiki extensions manual

UploadWizard Release status: stable
Implementation	Media, Special page
Description	Multi-file, step-by-step upload wizard
Author(s)	Neil Kandalgaonkar, Jeroen De Dauw, Mark Holmquist, Ryan Kaldari, Ankur Anand, Yuvi Panda, Michael Dale
Latest version	1.4.0 (2014-03-29)
MediaWiki	1.21+
License	GPL
Download	Download snapshot (Git master) Git [?]: repo summary browse file tree commit history README
Example	Commons Prototype
Namespace	Campaign
Translate the UploadWizard extension if it is available at translatewiki.net
Check usage and version matrix; code metrics
Bugs: list open list all report

UploadWizard is an extension that allows a user to upload multiple files with a step-by-step JavaScript wizard. It was originally designed by Guillaume Paumier as part of the Multimedia usability project and developed by Neil Kandalgaonkar, and has evolved since then.

See also: Upload Wizard description page on Wikimedia Commons

Installation

Enabling uploads and thumbnails

Your MediaWiki will need to be capable of hosting media files and creating thumbnails (smaller previews of media files). If you can upload images and see smaller previews on their File page, you're already ready. If not, for full instructions, see the manual page on image administration, particularly image thumbnailing.

Quick start for GNU/Linux or Mac OS X users:

• Make sure that the images directory is writable by your web server.
• Install the ImageMagick libraries and binaries.
• Add the following configuration to LocalSettings.php:

$wgEnableUploads = true;
$wgUseImageMagick = true;
$wgImageMagickConvertCommand = <path to your convert command>;  # Only needs to be set if different from /usr/bin/convert

 
require_once( "$IP/extensions/UploadWizard/UploadWizard.php" );

You also need to change the following core configuration variable.

// Needed to make UploadWizard work in IE, see bug 39877
$wgApiFrameOptions = 'SAMEORIGIN';

You should also install the EventLogging extension. This is used only if you use the campaigns feature, and should be made a soft dependency at some point in the future.

Enabling Flickr uploads

You can also use UploadWizard to transfer files directly from Flickr. To enable this option, first you'll need to get an API key from Flickr:

1. Go to http://www.flickr.com/services/api/
2. Click on API Keys
3. Log in with your Yahoo/Flickr username and password
4. Sign up for a key

Once you have a key, add the following to your LocalSettings.php:

$wgAllowCopyUploads = true;
$wgGroupPermissions['user']['upload_by_url'] = true; // to allow for all registered users
 
$wgUploadWizardConfig = array(
    'flickrApiUrl' => 'https://secure.flickr.com/services/rest/?',
    'flickrApiKey' => 'XXXXXXXXXXXXXXX',
);

You may also want to limit the upload domains specifically to Flickr:

$wgCopyUploadsDomains = array( '*.flickr.com', '*.staticflickr.com' );

Updating from versions before 07/2013

The following is essentially important if you made use of the Campaign feature:

• Update MediaWiki core to version 1.22 or later
• Check your custom configuration (LocalSettings.php) against the new default config. Parameters like automatically added categories changed (autoCategories → autoAdd => array( categories ).
• Install Extension:EventLogging.
• Run

  $ php extensions/UploadWizard/maintenance/migrateCampaigns.php
  

Other configuration

• You need to have InstantCommons enabled in order to access the licensing tutorial. To enable InstantCommons add

  $wgUseInstantCommons = true;
  

  to LocalSettings.php.
• You may want to set

  $wgUploadNavigationUrl = '/wiki/Special:UploadWizard';
  

  in LocalSettings.php, where /wiki/ is the correct path for your wiki. A more general way of doing this that works for whatever path configuration you have, but that requires PHP 5.3 or later is:

$wgExtensionFunctions[] = function() {
	$GLOBALS['wgUploadNavigationUrl'] = SpecialPage::getTitleFor( 'UploadWizard' )->getLocalURL();
	return true;
};

This modifies the sidebar's "Upload file" link - probably in other places as well. More at Manual:$wgUploadNavigationUrl.

Several other options are available through a configuration array. For example:

 $wgUploadWizardConfig = array(
 	'debug' => false,
 	'autoCategory' => 'Uploaded with UploadWizard',
 	'feedbackPage' => 'FeedbackTest2',
 	'altUploadForm' => 'Special:Upload',
 	'fallbackToAltUploadForm' => false,
 	'enableFormData' => true,  # Should FileAPI uploads be used on supported browsers?
 	'enableMultipleFiles' => true,
 	'enableMultiFileSelect' => false,
 	'tutorial' => array('skip' => false)
        'fileExtensions' => $wgFileExtensions //omitting this can cause errors
 );

Usage

URL arguments

There are several url arguments that can be specified to alter the behaviour of the UploadWizard:

• campaign: Specifies which upload campaign to use.
• skiptutorial: Sets if the licensing tutorial should be skipped or not. The value should be "1" or "true" to skip.
• id: Sets the initial value for the id field.
• description: Sets the initial value for the description field.
• lat: Sets the initial value for the latitude field.
• lon: Sets the initial value for the longitude field.
• alt: Sets the initial value for the altitude field.
• categories: Sets the initial value for the categories field, multiple categories seperated by |.

These arguments can be specified as follows: if you have an argument named "campaign" and want to provide the value "foobar", then append campaign=foobar to the url. For example wiki/Special:UploadWizard?campaign=foobar or w/index.php?title=Special:UploadWizard&campaign=foobar.

Testing

If you're testing UploadWizard for whatever reason, and you've run out of "real" images to upload as test cases, you can always use the handy MediaWiki utility for creating test images. Open a terminal emulator, get into a directory where you want to store a bunch of test JPG files, and run

$ php path/to/mediawiki/tests/phpunit/includes/api/generateRandomImages.php

Here's a Bash script that should make it easier to do all of this without much trouble. It's a good idea to put this in your PATH and/or make a handy shortcut to it somewhere that will make it trivial to update your images with new ones.

#!/bin/bash
 
# Declare some paths (easier to configure)
PICPATH=/path/to/image/directory
MW_INSTALL_PATH=/path/to/mediawiki
 
# Get to the pic path, and remove old test images
cd $PICPATH
rm *.jpg
 
# Run the generate script three times to give us a bunch of images
php $MW_INSTALL_PATH/tests/phpunit/includes/api/generateRandomImages.php
php $MW_INSTALL_PATH/tests/phpunit/includes/api/generateRandomImages.php
php $MW_INSTALL_PATH/tests/phpunit/includes/api/generateRandomImages.php

Templates

Upload Wizard will insert a few templates into generated file description pages, which need to exist on the wiki in order for the description pages to be rendered correctly. The templates used include:

• the "Information" template
• Description language identifiers like Template:En, if none are defined, then only {{en}} is used.
• Various licensing tags (which are configurable)
• the Location template for geocoordinates
• (Optionally) a template to indicate that a file is uncategorized

Development status

While we feel that this is ready for others to use, so far, this extension has mostly been used only on Wikimedia wikis. We'd like to get reports from other MediaWiki installations as well.

See also

• Campaigns documentation
• Developer documentation
• Extension:UploadWizard/Error behavior
• Wikimedia ops notes
• Commons:Upload Wizard – the Upload Wizard info page in Wikimedia Commons
• Extension:MsUpload
• Etherpad for the UploadWizard sprint for August 2012
• Ankur Anand's work on Flickr & geolocation integration

Related specs

• Custom WikiText License Feature
• Location (entering gps coordinates / deriving them from EXIF)

Related extensions

• Extension:Add Media Wizard