Community Central

November has come to an end and the rituals must be observed. Check out This Month at Fandom!

READ MORE

Community Central
Advertisement
This extension is not enabled by default but may be available upon request.

Gadgets deliver custom CSS or JavaScript to users who choose to use them. Unlike community CSS and JS, which are loaded for all users, gadget CSS and JS are only seen by users who enable the gadget. Gadgets are specific to each community; users can enable or disable them in their preferences under the "Gadgets" tab.

An example Gadgets section in Special:Preferences

Gadgets are a way to provide users with optional site-wide experiences. However, keep in mind that anonymous users cannot enable gadgets or disable any gadgets set as enabled by default.

Requesting the extension

By default, most Fandom communities do not use gadgets. Gadgets are powered by an extension; any community that wishes to use gadgets must contact staff to request enabling the extension on that community.

List of gadgets

An example of Special:Gadgets

To view a community's list of gadgets, go to Special:Gadgets. This special page will also provide edit links for gadget descriptions, show a list of files used by each gadget, and show any rights required by each gadget. Note that you cannot enable or disable gadgets on this page; you must go to Special:Preferences to enable or disable which gadgets you use.

Wikis that do not have the Gadgets extension enabled will show an error page on Special:Gadgets, as it does not exist.

Creating a gadget

Gadget definition

An example of MediaWiki:Gadgets-definition

The first step in creating a gadget is to define it. To do this, edit MediaWiki:Gadgets-definition on your community. Each gadget is defined by an entry in a bulleted list, so each line has to start with *. The gadget definition formatting is as follows:

* gadget_name [options] | file1 | file2 | etc.

  • gadget_name must be unique and is case-sensitive. It must start with a basic Latin letter ([A-Za-z]) and may be followed by any number of letters, digits ([0-9]), hyphens (-), underscores (_), colons (:), and periods (.).
  • See § Gadget options for an explanation on options.
  • See § Gadget files for an explanation on file1, file2, etc.

If your wiki has many gadgets, it may help to split the list into sections by using ==headings==. For example, the following list of four gadgets is split into two sections: utilities and visual. Like gadget names, section headings are also case-sensitive and must be unique.

==utilities==
* Utility1 [ResourceLoader] | NiceUtility.js
* Utility2 [ResourceLoader|rights=rollback] | RollbackUtil.js | RollbackUtil.css

==visual==
* Theme1 [type=styles] | CoolTheme.css
* Theme2 [type=styles] | FireTheme.css

Gadget description

By default, users will see your gadget presented in Special:Preferences as ⧼gadget-gadget_name⧽. This is not a very helpful description. You can edit this description by going to MediaWiki:Gadget-gadget_name on your wiki. You can also go to the list of gadgets at Special:Gadgets and click the "Edit" link next to each gadget definition.

Gadget descriptions must be reasonable. A helpful description explains everything the user will see differently or gain access to if they enable the gadget. Remember that gadgets are about giving your users choices on modifying their experience. To do so, they need accurate information.

Section headings can also be edited to appear more user-friendly. In the above example, to edit the utilities heading, simply go to MediaWiki:Gadget-section-utilities or click the "Edit" link next to the section heading at Special:Gadgets.

Gadget options

A gadget definition can include options that further specify how to load the gadget or who can enable it. Each option must be separated by a | pipe character. Options that do not take any parameters, such as ResourceLoader, can simply be included on their own; options that do take parameters must be included with an equals sign followed by a comma-separated list of parameters, such as rights=rollback,delete.

The table below lists the available gadget options for Fandom communities.

Name Parameters Description
ResourceLoader None Marks the gadget's scripts as compatible with ResourceLoader.
This option is required for any gadget that loads at least one JS file, otherwise Special:Gadgets will display an error and the JS will not load.
dependencies Comma-separated ResourceLoader module names Note that this option has no effect if the gadget has no ResourceLoader-compatible resources (i.e. no styles and scripts not marked as compatible).
rights Comma-separated privilege names Disable and hide the gadget in preferences for users who do not have these privileges. Note that user rights are not user groups; the full list of user rights is available at Special:ListGroupRights.
default None Any gadget set as default MUST adhere to the customization policy.
Enable the gadget by default for everyone, including anonymous users. Only registered users can disable this gadget.
type styles or general Use type=styles for gadgets that only load CSS files. This will load the CSS through the page HTML, which is faster than the default JavaScript loading behavior. Note that type=styles will not load any JS files in the gadget.

Gadget files

The bread and butter of a gadget are the files that it loads when it is enabled. Every CSS or JS page that a gadget loads must be prefixed with MediaWiki:Gadget-. In the above example, Utility2 defines two files, "RollbackUtil.js" and "RollbackUtil.css", which would be located at MediaWiki:Gadget-RollbackUtil.js and MediaWiki:Gadget-RollbackUtil.css, respectively. A good rule of thumb is to use the same name for the gadget and the files, but, as demonstrated, this is not a requirement.

Other than the Gadget- prefix, gadget CSS and JS files work like any other CSS or JS file. As such, please note that gadget JS files must be approved by the JavaScript review process before they are live for everyone. In terms of load order, gadgets are loaded after other local community code, but before personal code.

One gadget can load as many pages as desired, but it is rare to load more than one JS and one CSS page. Every file must be preceded in the gadget definition by a | pipe character. Any gadget CSS or JS page can also be loaded by multiple gadgets. Like other sidewide pages, gadgets can only be written using JS or CSS.

See also

Further help and feedback

Advertisement