Extension:Gadgets

From MediaWiki.org
(Redirected from Gadgets)
Jump to: navigation, search
This extension is bundled with MediaWiki 1.18 and above. Thus you do not have to download it again.
MediaWiki extensions manual
Crystal Clear action run.png
Gadgets

Release status: stable

Screenshot-gadgets-tab.png
Implementation MyWiki, Special page, API
Description Allow users to enable JS-based, user-provided gadgets from their preferences page.
Author(s) Daniel Kinzler (Duesentriebtalk)
MediaWiki 1.11+ (current version requires 1.19, versions for older MediaWiki (1.11+) are available here or from Git
Database changes No
License GNU General Public License 2.0 or later
Download
README
Example Wikimedia Commons: Gadget overview, user preferences (click "Gadgets"; you need to be logged in of course)
Hooks used
ArticleSaveComplete

BeforePageDisplay
GetPreferences
ResourceLoaderRegisterModules
UnitTestsList

Translate the Gadgets extension if it is available at translatewiki.net

Check usage and version matrix; code metrics

Issues:

Open tasks · Report a bug

The Gadgets extension provides a way for users to pick JavaScript or CSS based "gadgets" that other wiki users provide.

Gadgets are made up of JavaScript and/or CSS snippets located on pages in the MediaWiki namespace. Each gadget is defined by a line in MediaWiki:Gadgets-definition, providing a name and description for the gadget, and a list of the JS and CSS snippets that it uses (see the Usage section below).

Since Gadgets reside in the MediaWiki namespace (the list defining the gadgets as well as the actual code snippets), only sysops (aka wiki admins) can edit the code. This is as it should be: only users especially trusted by the wiki community should be able to edit JavaScript code that is used by other users, since JavaScript can easily be used to hijack accounts or spy on people.

Installation[edit | edit source]

  • Download and extract the file(s) in a directory called Gadgets in your extensions/ folder. If you're a developer and this extension is in a Git repository, then instead you should clone the repository using:
git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/Gadgets.git
  • Add the following code at the bottom of your LocalSettings.php:
require_once "$IP/extensions/Gadgets/Gadgets.php";
  • Done! Navigate to "Special:Version" on your wiki to verify that the extension is successfully installed.

Usage[edit | edit source]

Selection of some gadgets at the user preferences in de.wikipedia

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.

Format[edit | edit source]

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 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 (".").

Options format:

[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

Examples:

 * mygadget|mygadget.js|mygadget.css

or

 * mygadget[ResourceLoader]|mygadget.js|mygadget.css

or

* mygadget[rights=foo,bar]|mygadget.js|mygadget.css

or

* mygadget[ ResourceLoader | rights=foo, bar ] | mygadget.js | mygadget.css

Options[edit | edit source]

Name Parameters Description Since
ResourceLoader None Marks gadget's scripts as compatible with ResourceLoader.  ?
dependencies 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).  ?
rights Comma-separated privilege names Make the gadget available (and visible in preferences) only to users who have the specified privileges.  ?
skins Comma-separated skin names Make the gadget available (and visible in preferences) only to users who use the specified skins.  ?
default None Enable the gadget by default for everyone (including IPs). Registered users can still disable it in their preferences. 1.18
targets "desktop" (default), "mobile" or "desktop,mobile" Set the RL target(s) for the gadget.  ?
top None 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.ui and 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.

To enable it by default use "default":

* mygadget[ResourceLoader|default|dependencies=mediawiki.util]|mygadget.js|mygadget.css

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

ResourceLoader support[edit | edit source]

Each gadget's CSS is always loaded via the ResourceLoader. However, older JavaScript is often incompatible with RL, so every gadget must be explicitly marked as compatible in order to have its scripts loaded by RL. Otherwise, plain old <script src="/w/index.php?title=MediaWiki:Gadget-gadget_name.js&action=raw&ctype=text/javascript"> will be used.

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>.

Pages[edit | edit source]

The remaining fields on the line refer to the JavaScript or CSS code that makes up the gadget, contained in system messages (MediaWiki:Gadget-mygadget.js and MediaWiki:Gadget-mygadget.css in the example); the names of those messages must end with ".js" or ".css", respectively. A gadget can use any number of code messages, specifically, common code can be put into a code message used by several gadgets, in addition to their own specific code, e.g:

 * frobinator|commonStuff.js|frob.js|frob.css|pretty.css
 * l33t|commonStuff.js|tools.js|l33t.js

Sections[edit | edit source]

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.

ToDo[edit | edit source]

List of gadget scripts[edit | edit source]

This table is manually updated. Images link to scripts
Gadgets Usage
MediaWiki.org commons meta wikipedia
en
installed i i i
UTCLiveClock.js Yes check.svg Yes check.svg Yes check.svg Yes check.svg
SearchFocus.js Yes check.svg Yes check.svg
Syntax highlighter Yes check.svg
mySandbox Yes check.svg
Pages gadgets
edittop.js Yes check.svg Yes check.svg Yes check.svg Yes check.svg
HomeArrow.js
Category gadgets
HotCat.js Yes check.svg Yes check.svg Yes check.svg Yes check.svg
Tab gadgets
addsection-plus.js Yes check.svg
Sidebar gadgets
SubPages.js
UserRights.js

See also[edit | edit source]


Language: English  • Deutsch • français