Release status: stable
|Implementation||MyWiki, Special page, API|
|Description||Allow users to enable JS-based, user-provided gadgets from their preferences page.|
|Author(s)||Daniel Kinzler (Duesentriebtalk)|
|License||GNU General Public License 2.0 or later|
|Example||Wikimedia Commons: Gadget overview, user preferences (click "Gadgets"; you need to be logged in of course)|
Translate the Gadgets extension if it is available at translatewiki.net
|Check usage and version matrix.|
|Open tasks · Report a bug|
- Download and place the file(s) in a directory called
- Add the following code at the bottom of your LocalSettings.php:
wfLoadExtension( 'Gadgets' );
- Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
To users running MediaWiki 1.24 or earlier:
The instructions above describe the new way of installing this extension using
wfLoadExtension() If you need to install this extension on these earlier versions (MediaWiki 1.24 and earlier), instead of
wfLoadExtension( 'Gadgets' );, you need to use:
The list of available gadgets is defined on MediaWiki:Gadgets-definition. Once created with at least one valid gadget, gadgets defined there show up in the "Gadgets" section of Special:Preferences, so users can pick the gadgets they would like to use. An overview of the gadgets defined by MediaWiki:Gadgets-definition is also shown on Special:Gadgets, along with links to the respective system messages, for easy editing. Statistics for non-default gadget usage can be seen at Special:GadgetUsage.
Each line in MediaWiki:Gadgets-definition that starts with one or more "*" (asterisks) characters defines a gadget; it must have the following form:
* gadget_name [options (can be omitted)] | page names
The first field ("gadget_name" in the example) is the gadget's internal name, and references a system message (MediaWiki:Gadget-gadget_name in the example) that contains a short description of the gadget, using wiki syntax.
Note: The internal name is used as part of the name of a form field and must follow the rules defined for NAME attribute values. This means it must begin with a letter ([A-Za-z]) and may be followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), and periods (".").
[option1 | option2 | ... optionN]
whitespace can be omitted. Single option can either consist of single option name (in this case it is a flag option), or contain a comma-separated list of values:
option = value1, value2, value3
* mygadget[ ResourceLoader | rights=foo, bar ] | mygadget.js | mygadget.css
||None||Marks gadget's scripts as compatible with ResourceLoader.||?|
||Comma-separated module names||See list of default modules. Note that this option has no effect if current gadget has no ResourceLoader-compatible resources (i.e. no styles and scripts not marked as compatible).||?|
||Comma-separated privilege names||Make the gadget available (and visible in preferences) only to users who have the specified privileges.||?|
||None||Hide the gadget from the Preferences page. This can be used in two ways:
||Comma-separated skin names||Make the gadget available (and visible in preferences) only to users who use the specified skins.||?|
||None||Enable the gadget by default for everyone (including IPs). Registered users can still disable it in their preferences.||1.18|
||Set the RL target(s) for the gadget.||?|
||Comma-separated module names||Require CSS-only gadgets (which usually would be hidden). These gadgets will be loaded sooner than by
||None||(removed in 1.28) Makes the gadget to be top-loaded. This should be used sparingly, but may be needed for some initialization stuff like registering plugins with VisualEditor.||?|
You can specify extra dependencies for your gadgets, for example:
* mygadget[ResourceLoader|dependencies=jquery.ui, jquery.effects.clip]|mygadget.js|mygadget.css
Here, we ask ResourceLoader to load modules
jquery.effects.clip with mygadget. Note that gadgets can't depend on scripts from pages, static files or external URLs, only on modules already registered in ResourceLoader. To make a script from a page depend on another script from a page, each should be a gadget which registers itself as a module in ResourceLoader, then they can be made to have dependencies using the following syntax:
To enable a gadget by default, use "
To make the gadget available only to users with appropriate permissions, set the
rights option. For example,
* ImprovedDeletion [rights=delete] | ImprovedDeletion.js
makes the gadget available only to users who can actually delete pages. Note that restrictions are based on permissions, not user groups like administrators or bureaucrats. Here are some real examples:
* modrollback[ResourceLoader|rights=rollback]|modrollback.js * UTCLiveClock[ResourceLoader|rights=purge]|UTCLiveClock.js * Ajax_sysop[ResourceLoader|rights=patrol,rollback,markbotedits,delete]|Ajax_sysop.js
Every gadget that at least partially uses ResourceLoader (that is, that has styles or compatible scripts) has its own RL module. The modules are named ext.gadget.<gadget name>.
* frobinator|commonStuff.js|frob.js|frob.css|pretty.css * l33t|commonStuff.js|tools.js|l33t.js
Please note that if your code contains strings that could be interpreted as wiki syntax (e.g. the signature code
The list of gadgets in MediaWiki:Gadgets-definition can be broken into sections using lines that start and end with two or more "=" (equals) characters, enclosing the name of a system message that defines the section's name - for example:
== interface-gadgets ==
This would define a new section, with the title defined on the page MediaWiki:Gadget-section-interface-gadgets.
- Fulfill Basic gadgets
List of gadget scripts
|This extension is being used on one or more Wikimedia projects. This probably means that the extension is stable and works well enough to be used by such high-traffic websites. Look for this extension's name in Wikimedia's CommonSettings.php and InitialiseSettings.php configuration files to see where it's installed. A full list of the extensions installed on a particular wiki can be seen on the wiki's Special:Version page.|
|Other languages:||English • Deutsch • français|