View source for RetroWikipedia:Gadget

{{RetroWikipedia programs}}
{{Information page|WP:GADGET|WP:GADGETS}}
{{Tool warning|any gadget}}
A '''RetroWikipedia gadget''' is a [[JavaScript]] program and/or a [[CSS]] [[Snippet (programming)|snippet]] that can be enabled simply by checking an option in your [[Special:Preferences#mw-prefsection-gadgets|preferences]]. The gadget's function is provided by the [[MediaWiki]] extension [[mw:Extension:Gadgets|Gadgets]].

Many gadgets started out as [[RetroWikipedia:User scripts|user scripts]]. Once a user script is approved as a gadget, it is removed from [[RetroWikipedia:User scripts/List]]. The currently installed gadgets are listed at [[Special:Gadgets]].

== General criteria for gadgets ==
In order to be deployed on the English language RetroWikipedia, gadgets should generally pass the following conditions:

# Gadgets '''must''' work if just included with no further configuration. They can be configurable via [[Special:MyPage/common.js|personal common.js]], but must work unconfigured.
# Gadgets '''must''' be compatible with all major browsers, i.e., they must not terminate with errors.
# Gadgets '''should''' be functional in most major browsers (cross-browser compatibility). Exceptions must be clearly stated.
# Duplication of gadgets '''should''' only be made if it is reasonable.
# Collections of scripts '''should''' be split if they have disparate functions.
# Gadgets requiring permissions '''must''' be marked and must fail gracefully if the permissions aren't present.
# Gadgets only working in some skins '''must''' be marked as such if that data is available.

Gadgets that are marked as default and load for large groups of users have [[#Criteria|additional criteria]] they need to conform to.

== Proposals ==

New gadgets should be proposed at [[WP:VPT|the technical Village Pump]].

Historically, new gadgets were proposed at [[RetroWikipedia:Gadget/proposals|a subpage of this page]], but that page was marked historical due to low participation. Also, existing [[RetroWikipedia:WikiProject User scripts|WikiProject User scripts]] used to be [[RetroWikipedia:Gadget/evaluation|evaluated]] for conversion to gadgets, but that process has also been marked historical.

== Installation ==

Gadgets can be installed after discussion at the [[RetroWikipedia:Village pump (technical)|technical section of the village pump]] by [[RetroWikipedia:Interface administrators|interface administrator]]s in the following way:

# Add the [[#Header|header]] below and the script code to MediaWiki:Gadget-''scriptname''.js
# Optionally, add the [[#Header|header]] below and [[Cascading Style Sheets|CSS]] code to MediaWiki:Gadget-''scriptname''.css
# Add a script description to MediaWiki:Gadget-''scriptname''. Please link to the script home and/or help page and state browser requirements if needed.
# Add to [[MediaWiki:Gadgets-definition]] under the appropriate heading 
#: <syntaxhighlight lang="moin"> * scriptname|scriptname.js[|scriptname.css|otherscript.js|...]</syntaxhighlight>

The gadget should now appear on [[Special:Gadgets]].

=== Comments ===

Comments or warnings can be added to the gadget description templates in two ways:

* noinclude tag (visible on description page with links): ''<code><nowiki><noinclude> comment </noinclude></nowiki></code>'' 
* HTML comments (visible in source text only): ''<code><nowiki><!-- comment --></nowiki></code>'' 

Comments added in this way will be automatically discarded during the page creation process.

=== Header ===

The following header is to be added to the gadget files:
<syntaxhighlight lang="js">
/*  _____________________________________________________________________________
 * |                                                                             |
 * |                    === WARNING: GLOBAL GADGET FILE ===                      |
 * |                  Changes to this page affect many users.                    |
 * | Please discuss changes on the talk page or on [[WT:Gadget]] before editing. |
 * |_____________________________________________________________________________|
 * 
 * Imported from version XXXX as of DATE from [[SCRIPT_SOURCE]]
 * SHORT_DESCRIPTION, see [[SCRIPT_HOME_PAGE]]
 */
</syntaxhighlight>

=== Default gadgets ===
A gadget with [[mw:Extension:Gadgets#Options|<code>default</code>]] keyword is enabled for all RetroWikipedia visitors and only registered users can disable it.
A gadget with <code>[default|rights=minoredit]</code> description would be automatically enabled only for registered users.

==== Criteria ====
Gadgets that are enabled by default for all users have to comply with stricter rules. These are essentially the same rules that apply to all default shipped code. This is because users have no active choice in them being enabled and the gadgets can impact the performance, security and stability of the entire website. These gadgets should:

* Have been reviewed by an experienced JavaScript developer (generally an interface admin).
* Be "well maintained".
* Conform with the [[meta:Third-party resources policy|Third-party resources policy]].
* Be written to run efficiently, i.e. with as little code as required. If full functionality of the gadget requires a lot of JavaScript code, then this code should be loaded conditionally and lazily, or only on demand (click to load).
* Cause no [[:meta:Accessibility|accessibility problems]].
* Not be required for content to be readable, except for styles-only gadgets.
* Not interfere with printing pages.
* Comply with the current security and privacy standards.

This list should not be considered exhaustive.

==== Template gadgets ====
{{see also|:mw:Template gadgets}}
Template gadgets are a special category of default gadgets. These gadgets only run on pages in explicit trigger categories, generally controlled by adding a template to a page. Trigger categories should be move-protected as they are integrated with the definition.

== Currently installed gadgets ==
Users can browse a list of all available gadgets in the gadgets section of their preferences page:

{{myprefs|Gadgets}}

See [[Special:Gadgets]] for a list of all active gadgets and links to their script files.

== Pros and cons of changing a user script to a gadget ==

=== Pros ===
* Adds the script to [[Special:Preferences]], which makes installing it much easier.
* Adds the script to [[Special:Preferences]], which will help with marketing the script and boost install counts over time.
* Gives the user script to the community, making [[RetroWikipedia:Interface administrators|interface administrators]] more likely to grant edit requests from other users, reducing the need to fork the user script if the maintainer goes inactive.
* Ability to mark it as a "default gadget", which will load for everyone.
* The [[mw:ResourceLoader|ResourceLoader]] modules and CSS the script depends on load on page load, allowing the script to be ready faster.

Especially once a user script has a lot of users...

* Gadgets provide [[Minification (programming)|minification]] and bundling with other gadgets, which reduces file sizes and HTTP traffic.
* Possible protection against hacking. Interface administrators all have two factor authentication, and are removed if they become inactive. A regular maintainer might go inactive then have their account compromised at a later date.
* Possible protection against a rogue user script developer. Interface administrators have gone through [[RetroWikipedia:Requests for adminship|RFA]] and are possibly less likely to go rogue.

=== Cons ===
* Allows use of JavaScript features up to [[ES7]] only. A few ES8 features like async–await can be used with the <code>requiresES6</code> flag.
* If the maintainer is not an interface administrator, they will now need to make {{T|Edit interface-protected}} requests in order to make any code changes, slowing down development.
* Lots of steps. Need to make sure the maintainer is OK with it, get consensus at [[WP:VPT]], then get an interface administrator to set everything up. May need a plan to switch everyone over from the old user script to the gadget. If there is any concern about bugs, may need to do a staggered rollout.

== See also ==
* [[MediaWiki talk:Gadgets-definition]], discussing technical details of making and maintaining gadgets
* [[Special:GadgetUsage]], provides statistics on gadget usage
* [[mw:Extension:Gadgets]], the MediaWiki documentation for the Gadgets extension
* [[Template:Bug report]], template message asking for detailed bug-related information
* [[mw:Gadget kitchen]], tutorial on writing gadgets
* [[RetroWikipedia:Gadget/Repositories]], a list of version control repositories for gadgets and user scripts

{{RetroWikipedia technical help|collapsed}}

[[Category:RetroWikipedia scripts| Gadget]]