Extension:MediaUploader/Configuration/Details

MediaUploader has two very powerful features that allow you to build almost arbitrary forms for users and translate them into wikitext:

The ability to freely configure and reorder the fields in the Describe step (configured in the fields section).
Setting up transformations from user input into wikitext (configured in the content section).

`fields` section

G C P

This section configures the fields shown in the Describe step. All fields shown there by default can be reordered or removed, and new ones can be added. Each field must have a unique key, such as categories. This key is later used for referring to the field's value when building the wikitext of the page (see the content section).

This section is simply a mapping from field key to field descriptor object. What settings can be configured for each field depends on the field type (see subsections below the example).

Default value – first two fields

$wgMediaUploader['fields'] => [
  'title' => [
    'order' => 0,
    'type' => 'title',
    'label' => '{{MediaWiki:mediauploader-title}}',
    'help' => '{{MediaWiki:mediauploader-tooltip-title}}',
    'required' => 'required',
    'autoFill' => true,
    'minLength' => 5,
    'maxLength' => 240,
  ],
  'description' => [
    'order' => 1,
    'type' => 'textarea',
    'label' => '{{MediaWiki:mediauploader-description}}',
    'help' => '{{MediaWiki:mediauploader-tooltip-description}}',
    'required' => 'required',
    'autoFill' => true,
    'minLength' => 5,
    'maxLength' => 10000,
  ],
];

Restricted field keys (names)

You can choose any field key as you like, except for those that are pre-defined and used in other steps of the uploader:

source
author

All other names are fine.

Common field settings

These settings can be used on any field type.

type (string) – required. Must be one of the available types listed below.
order (integer) – required. Integer number indicating the order in which the fields should appear in the form, lowest to highest. The numbers don't have to be sequential (so you can have missing values in between).
label (string, parsed) – required. The main label of the field, shown in bold. The value of this setting is parsed.
help (string, parsed) – optional. Help text displayed above the field, explaining the user how to use it. The value of this setting is parsed.
required (string) – optional. This sets whether the user is forced to fill the field, is recommended to do that, or is completely free to decide. This field has three possible values:
- required – the user cannot progress without filling out this field.
- recommended – if the user hasn't filled out this field, they will be prompted before progressing further. The user can dismiss the prompt.
- optional (default) – the user is not forced or prompted to fill out the field.
hidden (boolean) – optional. Whether the field is visible to the user or not. The default is false.
enabled (boolean) – optional. Whether the field can be edited by the user or not. The default is true.
auxiliary (boolean) – optional. Whether the field should be moved to the bottom collapsible section titled by default Add location and more information... Use this for less important fields that you don't expect the users to use often. The default is false.
default – default value for the field. If the field is enabled and not hidden, the user can modify this default value. The type of this setting depends on the field type (see below).

Field types

`text`

Simple one-line text field.

Additional settings:

default (string) – default content of the field
minLength (integer) – minimum length in characters for user's input in this field
maxLength (integer) – maximum length in characters for user's input in this field
autoFill (boolean) – whether to try to automatically fill this field with the image's description extracted from metadata.

Example

$wgMediaUploader['fields']['textInput'] => [
  'order' => 1,
  'type' => 'text',
  'label' => 'Short caption',
  'autoFill' => true,
  'minLength' => 5,
  'maxLength' => 500,
];

`textarea`

Same as text, but appears as a multi-line text field. Has the same settings.

`singlelang`

Multi-line textbox with a language dropdown.

Additional settings:

default (map) – map specifying the default language and the default text.
- Fields: language, text. Both fields are mandatory.
- The language should be a valid ISO 646 language code.
minLength (integer) – same as in the text field type
maxLength (integer) – same as in the text field type
autoFill (boolean) – same as in the text field type

Example

$wgMediaUploader['fields']['someLangInput'] = [
  'type' => 'singlelang',
  'order' => 3,
  'label' => 'Single language input',
  'default' => ['language' => 'en', 'text' => 'Default value'],
  'minLength' => 3,
  'maxLength' => 1000,
];

See also: defining available languages and corresponding templates – languages and languageTemplateFixups settings.

`multilang`

Multiple-valued, multi-line textbox. For each value, a different language can be selected. This is useful in multilingual wikis (such as Wikimedia Commons), where you want to allow users to describe the file in multiple languages.

Additional settings:

default (array of maps) – an integer-indexed array, where each items corresponds to one language-text pair in the input. Each item in the array is configured just as the default value for the singlelang field.
minLength (integer) – same as in the text field type
maxLength (integer) – same as in the text field type
autoFill (boolean) – same as in the text field type

Example

$wgMediaUploader['fields']['someMultiInput'] = [
  'type' => 'multilang',
  'order' => 3,
  'label' => 'Multiple language input',
  'default' => [
    ['language' => 'en', 'text' => 'Default value'],
    ['language' => 'pl', 'text' => 'Wartość domyślna'],
  ],
  'minLength' => 3,
  'maxLength' => 1000,
];

See also: defining available languages and corresponding templates – languages and languageTemplateFixups settings.

`title`

Special field type used for inputting the title of the uploaded file. The input does not display the file's extension. There is additional validation in place to make sure the title can be used as the name of a page. There should only be one field of this type in the form.

Additional settings:

default (string) – default value for the field
minLength (integer) – same as in the text field type. 5 by default. It is not recommended to change this setting.
maxLength (integer) – same as in the text field type. 240 by default. It is not recommended to change this setting.
autoFill (boolean) – whether to automatically pre-fill the field based on the uploaded file's name

Example

$wgMediaUploader['fields']['titleField'] => [
  'order' => 0,
  'type' => 'title',
  'label' => '{{MediaWiki:mediauploader-title}}',
  'help' => '{{MediaWiki:mediauploader-tooltip-title}}',
  'required' => 'required',
  'autoFill' => true,
];

`select`

Dropdown selection from a pre-defined list.

Additional settings:

options (map) – list of available options. Maps the option's value to its displayed text (see example below).
default (string) – default value for the field, must be one of the keys from the options setting.

Example

$wgMediaUploader['fields']['selectInput'] = [
  'type' => 'select',
  'order' => 5,
  'label' => 'Please select your favorite color',
  'options' => [
    // The user will only see the human-readable descriptions of colors
    // The value passed on to wikitext will be the key ('#fff' etc.)
    '#fff' => 'White',
    '#f00' => 'Red!',
    '#0ff' => 'Turquoise, I think?',
  ],
  'default' => '#fff',
];

`date`

Combined popup calendar and free-form date input.

Additional settings:

default (string) – default value for the field. The arbitrary input mode will be used.
autoFill (boolean) – whether to attempt to automatically pre-fill the field, based on the information in the image's EXIF.

Example

$wgMediaUploader['fields']['dateInput'] = [
  'type' => 'date',
  'order' => 6,
  'label' => 'When was this image taken?',
  'autoFill' => true,
];

`categories`

Special input for adding MediaWiki categories to the upload. Multiple categories can be selected by the user. The input suggests categories when the user types in it.

Additional settings:

missingWikitext (string) – if the user didn't add categories, or removed the default categories, add this wikitext. Use this to indicate that some human should categorize this file. Does not consider hiddenDefault categories, which are hidden.
hiddenDefault (array of strings) – categories to automatically (and silently) add all uploaded images into. Category names here should not include the Category: prefix.
default (array of strings) – categories to add to the category selection field by default (the user can remove them). Category names here should not include the Category: prefix.

Example

$wgMediaUploader['fields']['categoryInput'] = [
  'type' => 'categories',
  'order' => 8,
  'label' => 'Add categories to the file',
  'missingWikitext' => 'Please add a category!\n[[Category:Uncategorized files]]',
  'hiddenDefault' => ['Files uploaded with MediaUploader'],
  'default' => ['Nice-looking files', 'Fantastic-looking files'],
];

`location`

Compound field allowing the user to specify a geographic location: latitude, longitude, altitude, and heading. Each of the four parts of the field can be individually disabled.

Additional settings:

fields (array of strings) – which subfields to enable (show to the user).
- Possible values: latitude, longitude, altitude, heading
- The default is latitude and longitude.
default (map) – default value for each subfield. Subfields:
- latitude (float) – must be a number between -90 and 90.
- longitude (float) – must be a number between -180 and 180.
- heading (float) – must be a number between 0 and 360.
- altitude (float) – any real number. Assumed to correspond to elevation above sea level in meters, although any other unit or reference point can also be used (it's a matter of UI labels).
autoFill (boolean) – whether to attempt to automatically pre-fill the field, based on the information in the image's EXIF.

Example

$wgMediaUploader['fields']['dateInput'] = [
  'type' => 'location',
  'order' => 9,
  'label' => 'Where was this image taken?',
  'fields' => ['latitude', 'longitude', 'altitude'],
  'default' => [
    'latitude' => 51.776667, 
    'longitude' => 19.454722,
    'altitude' => 223,
  ],
];

`license`

Special field type shown only when the user uploads several files at once, and in the Release rights step chooses the option to specify the license for each file separately. In such a case, in the Describe step, for each file a license choice must be displayed. You cannot configure the behavior of this field here (see: licensing configuration), but you can customize its label and position in the form.

There must be exactly one field of type license in the form. Otherwise, multi-file uploads may not work correctly.

All settings besides order, label, and help will be ignored for this field type.

Example

$wgMediaUploader['fields']['licenseInput'] = [
  'type' => 'license',
  'order' => 2,
  'label' => 'Why do you think you can upload this file?',
  'help' => 'Please be a good, honest citizen',
];

Overriding settings in campaigns

Because of the way the config overriding system works, to remove a field that is included in the default config (you can find it here), you must set the field in the fields section to null.

So, for example, if you don't like the location field from the default config, disable it like so:

$wgMediaUploader['fields']['location'] = null;

In a campaign you would do it similarly:

fields:
  # "~" is YAML's short for "null"
  location: ~

`content` section

G C

Config settings in this section control how the data input by the user in the Release rights and Describe steps is transformed into wikitext on the upload's page.

`titleField`

G C

The key of the field with the title of the uploaded file. The field must be of type 'title'.

Default value

$wgMediaUploader['content']['titleField'] = 'title';

`captionField`

G C

The field with the caption that will be used by default for the uploaded file. It must be one of the types: text, textarea, singlelang, multilang.

Default value

$wgMediaUploader['content']['captionField'] = 'description';

`wikitext`

G C

Wikitext "template" for building uploaded file description pages from user-provided information. Parameters are passed as pseudo-template arguments – {{{field_name}}}. The name of the parameter corresponds to the name of the field in the form. See below for a list of available parameters.

Save transformations ({{subst: }}) are supported. You can use them with parser functions (such as those provided by the ParserFunctions extension) to build complex transforms. You can also use wikitext templates to make the output easier to manage and prettier. See ready-to-use config sets for examples of that.

When the value for this setting is unspecified, the 'mediauploader-default-content-wikitext' message will be used instead.

Available parameters

Pre-defined (from the Release rights step):
- source – value of the Source field
- author – value of the Author field
- license – wikitext corresponding to the selected license(s). See the licensing configuration for more details and settings.
For each field in the Describe step (as defined in the fields config section), a parameter named {{{field_name}}} is available. It corresponds to a wikitext value of that field.
Additionally, for some field types there are subfield parameters available. They can be accessed using dot notation – {{{field_name.subfield_name}}}. Available parameters:
- date field type:
  - field_name.mode – input mode, either arbitrary or calendar
- location field type:
  - field_name.latitude
  - field_name.longitude
  - field_name.altitude
  - field_name.heading
- singlelang field type:
  - field_name.language – ISO language code
  - field_name.text – text value of the field

Default value

== Description ==
{{{description}}}

== Media information ==
* '''Date:''' {{{date|''unknown''}}}
* '''Source:''' {{{source|''unknown''}}}
* '''Author:''' {{{author|''unknown''}}}
* '''Location:''' {{{location|''unknown''}}}

{{{other}}}

== License ==
{{{license}}}

{{{categories}}}

See also: ready-to-use configuration sets

`prepend`

G C

Wikitext to prepend before the 'wikitext' field. Useful in campaigns, when you want to include some extra information on the page, without redefining the entire wikitext template.

Parameters and save transforms can be used here in exactly the same manner as in the wikitext setting (see above).

Default value

$wgMediaUploader['content']['prepend'] = '';

`append`

G C

Wikitext to append after the 'wikitext' field. Useful in campaigns, when you want to include some extra information on the page, without redefining the entire wikitext template.

Parameters and save transforms can be used here in exactly the same manner as in the wikitext setting (see above).

Default value

$wgMediaUploader['content']['append'] = '';

Other settings

`copyMetadataFeature`

G

Whether to enable the feature for copying metadata across a batch of uploads.

Default

$wgMediaUploader['copyMetadataFeature'] = true;

`languages`

G

A list of languages and codes, for use in multilang and singlelang inputs. By default initialized to a list of all available languages that have corresponding templates (in ISO 646 language codes).

Example

$wgMediaUploader['languages'] = [ 
  'en' => 'English',
  'pl' => 'Polski',
];

`languageTemplateFixups`

G

For singlelang and multilang fields, MediaUploader wraps each description in a language template. A language template is by default assumed to be a template with a name corresponding to the ISO 646 code of the language. For instance, Template:en for English, or Template:fr for French. If this is not the case for some or all or your wiki's language templates, this map can be used to define the template names to be used. Keys are ISO 646 language codes, values are template names.

Example

$wgMediaUploader['languageTemplateFixups'] = [ 
  'en' => 'lang-en', // If you want to use Template:lang-en
  'pl' => 'lang-pl',
];

fields section

Restricted field keys (names)

Common field settings

Field types

text

textarea

singlelang

multilang

title

select

date

categories

location

license

Overriding settings in campaigns

content section

titleField

captionField

wikitext

prepend

append

Other settings

copyMetadataFeature

languages

languageTemplateFixups

`fields` section

`text`

`textarea`

`singlelang`

`multilang`

`title`

`select`

`date`

`categories`

`location`

`license`

`content` section

`titleField`

`captionField`

`wikitext`

`prepend`

`append`

`copyMetadataFeature`

`languages`

`languageTemplateFixups`