Extension:Gadgets
<languages/> Template:Bundled Template:Extension <translate> The Gadgets extension provides a way for users to pick JavaScript or CSS based "gadgets" that other wiki users provide. </translate>
<translate> Gadgets are made up of JavaScript and/or CSS <tvar name=1>Template:Ll</tvar> located on pages in the MediaWiki namespace.</translate> <translate> Each gadget is defined by a line in <tvar name=1>MediaWiki:Gadgets-definition</tvar>, providing a name and description for the gadget, and a list of the JS and CSS snippets that it uses (see the [[<tvar name=2>#Usage</tvar>|Usage]] section below).</translate>
<translate> Since Gadgets reside in the MediaWiki namespace (the list defining the gadgets as well as the actual code snippets), only sysops (interface admins from 1.32) can edit the code.</translate> <translate> 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.</translate>
<translate>
Installation
</translate> Template:ExtensionInstall
<translate>
Usage
</translate>
<translate> Once <tvar name=2>MediaWiki:Gadgets-definition</tvar> is created with at least one valid gadget, a new "Gadgets" section will be shown on <tvar name=1>Special:Preferences</tvar> for all users. Users can enable the gadgets they would like to use there.</translate> <translate> An overview of gadgets currently defined by <tvar name=1>MediaWiki:Gadgets-definition</tvar> is also rendered on <tvar name=2>Special:Gadgets</tvar>, along with helpful links to the relevant localisation and script/style pages for easy creation or editing.</translate> <translate> Statistics about gadget preferences are available at <tvar name=1>Special:GadgetUsage</tvar>.</translate>
<translate>
Definition format
Each line on the <tvar name=1>MediaWiki:Gadgets-definition</tvar> page should start with a "<tvar name=2>*</tvar>" (asterisk) character to define a gadget. The line takes the following format: </translate>
* mygadget [<translate> options</translate>] | <translate> page names</translate>
<translate> The first field ("<tvar name=1>mygadget</tvar>" in the example) is the gadget's internal name. The label for the preferences page comes from an interface message page (<tvar name=2>MediaWiki:Gadget-mygadget</tvar>) where the proper name and a short description can be written, which also allows wikitext markup to be used. </translate>
<span class="citation wikicite" id="endnote_<translate> The internal name must begin with a basic Latin letter (<tvar name=1>[A-Za-z]
</tvar>) and may be followed by any number of letters, digits (<tvar name=2>[0-9]
</tvar>), hyphens (<tvar name=3>-
</tvar>), underscores (<tvar name=4>_
</tvar>), and periods (<tvar name=6>.
</tvar>).</translate> <translate> The reason for this limitation is that the internal name must be valid as the name of an [<tvar name=url>https://www.w3.org/TR/html4/types.html#type-id</tvar> HTML form name], as MediaWiki interface message key, and as ResourceLoader module name.</translate>">[[#ref_<translate> The internal name must begin with a basic Latin letter (<tvar name=1>[A-Za-z]
</tvar>) and may be followed by any number of letters, digits (<tvar name=2>[0-9]
</tvar>), hyphens (<tvar name=3>-
</tvar>), underscores (<tvar name=4>_
</tvar>), and periods (<tvar name=6>.
</tvar>).</translate> <translate> The reason for this limitation is that the internal name must be valid as the name of an [<tvar name=url>https://www.w3.org/TR/html4/types.html#type-id</tvar> HTML form name], as MediaWiki interface message key, and as ResourceLoader module name.</translate>|^]]
<translate> Options format: </translate>
[ResourceLoader | <translate> option1</translate> | <translate> option2</translate> | ... <translate> optionN</translate>]
<translate> The ResourceLoader flag is required unless the gadget contains only styles.</translate> <translate> Options that are "flags" only need to have their name written to be turned on.</translate> <translate> Options that need a value are followed by an equals sign and a comma-separated list of values.</translate> <translate> All whitespace is optional and may be omitted.</translate>
[ResourceLoader | myflag | mykey = value1, value2, value3 ]
<translate> Examples: </translate>
* mygadget[ResourceLoader]|mygadget.js|mygadget.css
<translate> or </translate>
* mygadget[ResourceLoader|package]| mygadget.js | mygadget-Foo.js | mygadget-data.json | mygadget.css
<translate> or </translate>
* mygadget[ ResourceLoader | rights=foo, bar ] | mygadget.js | mygadget.css
<translate>
Using Gadget Definition Namespace
</translate>
<translate> There are two ways to define gadgets depending on the <tvar name=1>$wgGadgetsRepoClass
</tvar>.</translate>
<translate> If It is <tvar name=1>'MediaWikiGadgetsDefinitionRepo'
</tvar> (the default value), the list of available gadgets is defined on <tvar name=2>MediaWiki:Gadgets-definition</tvar>.</translate>
<translate> In an alternative way, Gadget definitions are defined on pages in the [[<tvar name=1>Special:PrefixIndex/Gadget definition:</tvar>|Gadget definition]] namespace when <tvar name=2>$wgGadgetsRepoClass
</tvar> is set to <tvar name=3>'GadgetDefinitionNamespaceRepo'
</tvar>.</translate>
[[#ref_{{{1}}}|^]]
<translate>
Creation of the <tvar name=1>Gadget definition:mygadget
</tvar> page and putting in it the below JSON code have the same effect as <tvar name=2>mygadget[ ResourceLoader | rights=foo, bar ] | mygadget.js | mygadget.css
</tvar>.
</translate>
{
"settings": {
"rights": [ "foo", "bar" ],
"default": false,
"package": false,
"hidden": false,
"skins": [],
"actions": [],
"category": ""
},
"module": {
"scripts": [ "mygadget.js" ],
"styles": [ "mygadget.css" ],
"datas": [],
"peers": [],
"dependencies": [],
"messages": [],
"type": ""
}
}
<translate>
In above example, the <tvar name=1>Gadget:Mygadget.js
</tvar> and the <tvar name=2>Gadget:mygadget.css
</tvar> are used.
Options
</translate>
<translate> Name</translate> | <translate> Parameters</translate> | <translate> Description</translate> | <translate> Since</translate> |
---|---|---|---|
ResourceLoader |
<translate> None</translate> | <translate> Marks gadget's scripts as compatible with <tvar name=1>Template:Ll</tvar>.</translate> | 1.17 (r76527) |
dependencies
|
<translate> Comma-separated module names</translate> | <translate> These modules will be loaded before the scripts of this gadget execute.</translate> <translate> See [[<tvar name=1>Special:MyLanguage/ResourceLoader/Default modules</tvar>|list of default modules]].</translate> | 1.17 (r76639) |
rights
|
<translate> Comma-separated privilege names</translate> | <translate> Make the gadget available (and visible in preferences) only to users who have the specified [[<tvar name=1>Special:MyLanguage/Manual:User rights#List of permissions</tvar>|privileges]].</translate> | 1.18 (r85268) |
hidden
|
<translate> None</translate> | <translate> Hide the gadget from the [[<tvar name=1>Special:MyLanguage/Help:Preferences</tvar>|Preferences]] page.</translate> <translate> This can be used in two ways:</translate>
|
1.28 |
skins
|
<translate> Comma-separated skin names</translate> | <translate> Make the gadget available (and visible in preferences) only to users who use the specified [[<tvar name=1>Special:MyLanguage/Manual:Skins</tvar>|skins]].</translate> <translate> Before MediaWiki 1.32 it was taking into consideration the skin set in preferences for the user, not the current displayed one (like when adding <tvar name=1>?useskin=monobook </tvar> in the URL, <tvar name=2>Template:Phab</tvar>).</translate> <span class="citation wikicite" id="endnote_<translate> Use of <tvar name=1>skins </tvar> should be a last resort, and should be restricted to specialized code which relies on DOM manipulated which is used in the absence of non-standardized APIs that are not served by the methods listed on [[<tvar name=2>Special:MyLanguage/ResourceLoader/Core_modules</tvar>|ResourceLoader/Core modules]].</translate>">[[#ref_<translate> Use of <tvar name=1>skins </tvar> should be a last resort, and should be restricted to specialized code which relies on DOM manipulated which is used in the absence of non-standardized APIs that are not served by the methods listed on [[<tvar name=2>Special:MyLanguage/ResourceLoader/Core_modules</tvar>|ResourceLoader/Core modules]].</translate>|^]]
|
1.19 (r100509) |
actions
|
<translate> Comma-separated action names</translate> | <translate> Make the gadget available only on the specified page actions.</translate> <translate> E.g. <tvar name=1>actions = edit, history </tvar> to load a gadget only while editing and on history pages.</translate> <span class="citation wikicite" id="endnote_<translate> Specifying <tvar name=1>edit </tvar> action will also load it on <tvar name=2>action=submit </tvar>.</translate> <translate> Invalid actions effectively disable the gadget since it can't be run anywhere.</translate>">[[#ref_<translate> Specifying <tvar name=1>edit </tvar> action will also load it on <tvar name=2>action=submit </tvar>.</translate> <translate> Invalid actions effectively disable the gadget since it can't be run anywhere.</translate>|^]]
|
1.38 (gerrit:747112) |
namespaces
|
<translate> Comma-separated namespace numbers</translate> | <translate> Make the gadget available only on the specified namespaces.</translate> <translate> E.g. <tvar name=1>namespaces = 0, 2 </tvar> to load a gadget only in mainspace and user namespace.</translate>
|
1.41 (gerrit:624517) |
contentModels
|
<translate> Comma-separated content models</translate> | <translate> Make the gadget available on pages with the given content models.</translate> <translate> E.g. <tvar name=1>contentModels = wikitext </tvar> to load a gadget only on wikitext pages.</translate>
|
1.41 (gerrit:922062) |
default
|
<translate> None</translate> | <translate> Enable the gadget by default for everyone (including IPs).</translate> <translate> Registered users can still disable it in their preferences.</translate> | 1.18 (r85902) |
package
|
<translate> None</translate> | <translate> Mark this gadget as [[<tvar name=1>Special:MyLanguage/ResourceLoader/Migration_guide_(users)#Package_Gadgets</tvar>|packaged]].</translate> <translate> In this mode, only the first JavaScript page will be executed. Other pages can be imported by using the <tvar name=1>require()</tvar> function.</translate> <translate> This mode also enables use of JSON pages, which cannot be included otherwise.</translate> | 1.38 |
targets
|
<translate> <tvar name=1>desktop </tvar>, <tvar name=2>mobile </tvar> or <tvar name=3>desktop,mobile </tvar>(default)</translate>
|
<translate> Set the <tvar name=1>Template:Ll</tvar> target(s) for the gadget.</translate>
<span class="citation wikicite" id="endnote_<translate> Do not use <tvar name=1> |
1.21 (gerrit:60954) |
type
|
<translate> <tvar name=1>styles </tvar> (default for CSS-only gadgets) or <tvar name=2>general </tvar> (default otherwise)</translate>
|
<translate> Use <tvar name=1>styles </tvar> for modules that only modify styling for elements already on the page (e.g. when customizing the skin, layout, or article content).</translate> <translate> It will cause the CSS files of the module to be included from the page HTML instead of being loaded via JavaScript.</translate> <translate> For details, see [[<tvar name=1>Special:MyLanguage/ResourceLoader/Migration guide (users)#Gadget type</tvar>|ResourceLoader/Migration guide (users)#Gadget type]].</translate>
<span class="citation wikicite" id="endnote_<translate> Using <tvar name=1> |
1.28 |
peers
|
<translate> Comma-separated gadget names</translate> | <translate> These CSS-only gadgets will be loaded together with this gadget.</translate> <translate> These gadgets will be loaded before any dependencies , and their styles will be applied even if JavaScript is disabled.</translate> <translate> For details, see [[<tvar name=1>Special:MyLanguage/ResourceLoader/Migration guide (users)#Gadget peers</tvar>|ResourceLoader/Migration guide (users)#Gadget peers]].</translate>
|
1.29.0 |
supportsUrlLoad
|
<translate> None</translate> | true | false | <translate> Make the gadget available to be loaded with the <tvar name=1>?withgadget </tvar> URL query parameter.</translate>
|
1.38 |
requiresES6
|
<translate> None</translate> | <translate> Allow use of ES6 syntax (ES2015) in the gadget.</translate> <translate> Enabling this means server-side syntax validation is skipped for the gadget.</translate> <translate> Any ES6-requiring gadgets are loaded together in a single web request, which isolates failures due to invalid or unsupported syntax to those gadgets only, without affecting other gadgets and MediaWiki software features.</translate> <translate> It is recommended to use a tool like ESLint to ensure only valid ES6 syntax is used.</translate> | 1.40.0-wmf.7 (gerrit:758086) |
|
<translate> None</translate> | Template:Removed-inline <translate> Makes the gadget to be [[<tvar name=1>Special:MyLanguage/Manual:$wgResourceModules#Details</tvar>|top-loaded]].</translate> <translate> This should be used sparingly, but may be needed for some initialization stuff like registering plugins with VisualEditor.</translate> | 1.22 (gerrit:75506) |
<translate> You can specify extra dependencies for your gadgets, for example:</translate>
* mygadget[ResourceLoader|dependencies=jquery.ui, jquery.effects.clip]|mygadget.js|mygadget.css
<translate> Here, we ask ResourceLoader to load modules <tvar name=1>jquery.ui
</tvar> and <tvar name=2>jquery.effects.clip
</tvar> with <tvar name=3>mygadget</tvar>.</translate>
<translate> Note that gadgets can't depend on scripts from pages, static files or external URLs, only on modules already registered in ResourceLoader.</translate>
<translate> 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:</translate>
* childgadget[ResourceLoader|dependencies=ext.gadget.parentgadget]|childgadget.js
<translate>
To enable a gadget by default, use "<tvar name=1>default
</tvar>":
</translate>
* mygadget[ResourceLoader|default|dependencies=mediawiki.util]|mygadget.js|mygadget.css
<translate>
To make the gadget available only to users with appropriate permissions, set the rights
option, for example:
</translate>
* ImprovedDeletion [rights=delete] | ImprovedDeletion.js
<translate> Makes the gadget available only to users who can actually delete pages.
Note that restrictions are based on [[<tvar name=1>Special:MyLanguage/Manual:User rights#List of permissions</tvar>|permissions]], not user groups like [[<tvar name=2>Special:MyLanguage/Manual:Administrators</tvar>|administrators]] or bureaucrats. </translate> <translate> Here are some real examples:</translate>
* modrollback[ResourceLoader|rights=rollback]|modrollback.js * UTCLiveClock[ResourceLoader|rights=purge]|UTCLiveClock.js * Ajax_sysop[ResourceLoader|rights=patrol,rollback,markbotedits,delete]|Ajax_sysop.js
<translate>
User rights
</translate>
<span class="citation wikicite" id="endnote_<translate> This extension adds two new user rights, <tvar name=1>gadgets-edit
</tvar> and <tvar name=2>gadgets-definition-edit
</tvar>, which by default aren't given to any group.</translate>
<translate> You can add the following in your <tvar name=1>Template:Ll</tvar> to provide the appropriate permissions for users who are within the interface-admin group.</translate>
<translate> Editing pages in the Gadget namespace requires the <tvar name=1>gadgets-edit
</tvar> right and editing pages in the Gadget definition namespace requires the <tvar name=2>gadgets-definition-edit
</tvar> right.</translate>
$wgGroupPermissions['interface-admin']['gadgets-edit'] = true;
$wgGroupPermissions['interface-admin']['gadgets-definition-edit'] = true;
">[[#ref_<translate> This extension adds two new user rights, <tvar name=1>gadgets-edit
</tvar> and <tvar name=2>gadgets-definition-edit
</tvar>, which by default aren't given to any group.</translate>
<translate> You can add the following in your <tvar name=1>Template:Ll</tvar> to provide the appropriate permissions for users who are within the interface-admin group.</translate>
<translate> Editing pages in the Gadget namespace requires the <tvar name=1>gadgets-edit
</tvar> right and editing pages in the Gadget definition namespace requires the <tvar name=2>gadgets-definition-edit
</tvar> right.</translate>
$wgGroupPermissions['interface-admin']['gadgets-edit'] = true;
$wgGroupPermissions['interface-admin']['gadgets-definition-edit'] = true;
|^]]
<translate>
Pages
</translate> <translate> The remaining fields on the definition line refer to the JavaScript, CSS or JSON source pages that makes up the gadget module.</translate> <translate> These are stored in the MediaWiki namespace as interface messages (<tvar name=1>MediaWiki:Gadget-mygadget.js</tvar> and <tvar name=2>MediaWiki:Gadget-mygadget.css</tvar> in the example).</translate> <translate> The page names must end with "<tvar name=1>.css</tvar>", "<tvar name=2>.js</tvar>", or "<tvar name=3>.json</tvar>" respectively.</translate>
<translate> A gadget can use any number of source pages, e.g: </translate>
* frobinator[ResourceLoader]|frob.js|frob.css|pretty.css * l33t[ResourceLoader]|l33t.js * foobar[ResourceLoader|package]|foo.js|bar.js|foobar-data.json
<translate>
Please note that if your code contains strings that could be interpreted as wiki syntax (e.g. the signature code <tvar name=1>~~~~
</tvar>), you may want to enclose your code into <tvar name=2><nowiki></nowiki>
</tvar> and put these tags in JavaScript or CSS comments so they're not interpreted when actually used.
See the first and last lines of <tvar name=1>MediaWiki:Gadget-externalsearch-bar.js</tvar> for an example.
Sections
The list of gadgets in <tvar name=1>MediaWiki:Gadgets-definition</tvar> can be broken into sections using lines that start and end with two or more "<tvar name=2>=</tvar>" (equals) characters, enclosing the name of a system message that defines the section's name, for example: </translate>
== interface-gadgets ==
<translate> This would define a new section, with the title defined on the page <tvar name=1>MediaWiki:Gadget-section-interface-gadgets</tvar>.</translate>
<translate>
Popular gadgets
</translate> <translate> See <tvar name=1>meta:Gadgets</tvar> for gadgets which are popular in Wikimedia communities.</translate>
<translate>
See also
</translate>
- Special:Gadgets – <translate> lists all the gadgets and a brief description of each</translate>
- Template:Ll
- Template:Ll
- Template:Ll
- Template:Ll
Template:OnWikimedia Template:Used by
[[Category:Gadgets{{#translation:}}]] [[Category:JavaScript{{#translation:}}]]