Gadget kitchen

Welcome to the gadget kitchen. This is a tutorial how you can write and use user scripts in JavaScript.

What are user scripts and gadgets?
MediaWiki allows anyone to write public 1>Special:MyLanguage/Learning JavaScript|JavaScript code to immediately change the behavior of the software.

This code can be shared with other users.

This code is located in wiki pages.


 * A user script belongs to you as a user and is executed for that user. The code is usually hosted on a sub page of your user page.


 * A gadget is a user scripts which has been "promoted" by an 1>meta:Interface administrators|interface administrator, by adding it to MediaWiki:Gadgets-definition. Logged-in users can enable gadgets in the 1>Special:Preferences#mw-prefsection-gadgets|"Gadgets" tab of their user preferences.  Gadgets are created and managed by interface administrators.
 * For completeness: Interface administrators can also add and edit the siteJS located at MediaWiki:Common.js.  The JavaScript in that file affects everyone and is executed automatically for both logged-out and logged-in users.

If you're running your own copy of MediaWiki, needs to be enabled for user scripts to work, and the gadgets>Extension:Gadgets|Gadgets extension needs to be installed to make it possible to promote individual scripts to gadget status.

For a nicer development experience, ensure that the  extension is installed on your wiki.

Write your first user script
In this section, you create an example user script which calculates the estimated reading time of a wiki page.
 * 1) Ensure you are logged in.
 * 1) Visit Special:MyPage/common.js. This page holds your personal>Manual:Interface/JavaScript#Personal_scripts|personal JavaScript that is loaded on every page view (except for Special:Preferences).
 * 1) Either create the page, or edit the page if it already exists.
 * 2) Copy the following six lines and paste these lines into the page:
 * 3) Click "Publish changes".
 * 4) Go to any page. Look at the title.
 * 1) Go to any page. Look at the title.

This example user script is taken from ChickTech High School Kickoff 2017/Tasks. There are more examples for simple user scripts on that page.

In general, check out jsconv>Manual:Coding conventions/JavaScript|the JavaScript coding conventions to write JavaScript that complies with MediaWiki's style.

Load an existing user script
In this section, you will load the existing script MediaWiki:Tutorial-QuickRC.js.

is a ResourceLoader function. See below for more information.
 * 1) Ensure you are logged in.
 * 2) Visit Special:MyPage/common.js. This page holds your personal>Manual:Interface/JavaScript#Personal_scripts|personal JavaScript that is loaded on every page view (except for Special:Preferences).
 * 3) Either create the page, or edit the page if it already exists.
 * 4) Copy the following text and paste it into the page: mw.loader.load('//www.mediawiki.org/w/index.php?title=MediaWiki:Tutorial-QuickRC.js&action=raw&ctype=text/javascript');
 * 5) Click "Publish changes". You should now have a link in the "Tools" section called "Quick changelog".
 * 6) Click "Quick changelog". You get a pop-up window. It shows you a subset of the recent changes on this website.

How do I use a script on another Wikimedia wiki?
If you want to use a script on another Wikimedia website (for example English Wikipedia instead of MediaWiki.org), you perform the same steps as above: You tell ResourceLoader to load your code. Visit your common.js on English Wikipedia and add the following:

Of course, you could also load the user script you just created by changing MediaWiki:Tutorial-QuickRC.js in the URI above to  (replace   and   accordingly).

This also helps to keep code in one single place, so you have to update code in only one place.

ResourceLoader
RL>ResourceLoader|ResourceLoader is a core feature of MediaWiki that intelligently delivers JavaScript and CSS assets to users and readers. Because Gadgets are coded in JavaScript, as a Gadget coder you're bound to interact with ResourceLoader. Since the year 2015 (MediaWiki 1.26), gadgets must use ResourceLoader (T107399).

Your gadget should load useful ResourceLoader modules instead of "reinventing the wheel."


 * modules>ResourceLoader/Modules|Modules — A list of JavaScript libraries, jQuery plugins and MediaWiki utilities that already exist within ResourceLoader for you to reuse.
 * See the jQuery documentation for information about using jQuery in MediaWiki
 * 1>Special:MyLanguage/ResourceLoader/Developing with ResourceLoader|Developing with ResourceLoader — A list of useful practices, like enabling the debug mode and help with debugging.
 * Also see the RL>ResourceLoader/Migration_guide_(users)#Good_practices</>|ResourceLoader good practices.

OOUI
ooui>Special:MyLanguage/OOUI</>|OOUI is a javascript library with user interface elements (for example pop-up windows) specifically for use in MediaWiki. The library oouiusing>Special:MyLanguage/OOUI/Using OOUI in MediaWiki#Gadgets</>|can be used in gadgets.

MediaWiki Action API
See Special:MyLanguage/API for more information.

If your gadget uses the MediaWiki API, add the <tvar|callback>" "</> parameter to the API URL if you are trying to make an API request that would violate the same-origin policy (e.g. making a request to the Commons API from Wikipedia). This triggers the use of JSONP and enforces certain restrict>API:Data formats#JSON callback restrictions</>|restrictions.

VisualEditor
See ve-gadgets>VisualEditor/Gadgets</>|VisualEditor/Gadgets for a tutorial specifically for VisualEditor gadgets.

A more complex user script
Check out MediaWiki:Tutorial-QuickRC.js which uses mw.loader, mw.util, mw.html, mw.user from ResourceLoader, the MediaWiki Action API, a jQuery UI dialog, jQuery AJAX, and jQuery event binding.

Copy and paste the contents of MediaWiki:Tutorial-QuickRC.js into your Special:MyPage/common.js.

The result should be the same as above, but now you can modify the script, play with it, and replace it with something else entirely.

Clicking "Preview" (or using the keyboard shortcut, typically ) in the editor will also execute the latest version of the script. This is a good way to iterate without saving the page. But remember, nothing is saved until you press "Publish page".

Got any tips for writing or debugging JS?

 * Debugging:
 * Gadgets are usually compacted by the resource loader, minimized and aggregated. use the  url parameter (preceded by ? or &, of course), to ask for the non-compacted version of the page, to facilitate debugging, by loading the "source form" of your gadget, comments and all.
 * Learn how to use the Developer Tools of your browser (for example how to disable the cache in your browser). See the corresponding documentation: Chrome/Chromium, Firefox, Internet Explorer, Opera, Safari.


 * audit-resources: You should not load external resources that may harm users privacy. For example in WMF wikis, the following domains are considered safe:
 * .wiktionary.org
 * .wikimedia.org,
 * *.wikibooks.org
 * *.wikisource.org
 * *.wikisource.org
 * *.wikiversity.org
 * *.wikinews.org
 * *.wikiquote.org
 * *.wikidata.org
 * *.wikivoyage.org
 * www.mediawiki.org

Disadvantages and problems of gadgets

 * Gadgets are developed by community members. As of today, there is no formal code review required for gadgets on Wikimedia sites (see T71445). Please follow the best practices listed on this page.
 * On Wikimedia sites, the process how to "promote" a user script to a gadget in the "Gadgets" tab of the user preferences is not always clear. You will have to find an interface administrator and might have to provide deployment instructions to them.
 * Wikimedia lacks a systematic process for re-using, modifying and contributing to existing user scripts and gadgets.

What could I work on?
If you want to write features that directly help Wikimedia community members, see:
 * Gadget Kitchen/Requests in general
 * requests>w:Wikipedia:User scripts/Requests</> for English Wikipedia

Related pages

 * scripts>w:en:Wikipedia:User scripts</>|Wikipedia:User scripts on the English Wikipedia and its alternatives in other languages are the primary hubs for user script and gadget development in Wikipedia.
 * The guide>w:en:Wikipedia:WikiProject User scripts/Guide</>|user scripts guide on the English Wikipedia has tons of useful information to get you started.


 * engadget>w:en:Wikipedia:Gadget</>|Wikipedia:Gadget page on English Wikipedia
 * Slides for a workshop to teach the basics of user scripts and gadgets (part of Small wiki toolkits)


 * the MediaWiki web service api>Special:MyLanguage/API:Main page</>|API documentation will also be very useful

In the future, changes to ResourceLoader ("Gadgets 2.0") will make managing gadgets simpler.
 * gadgets>m:Gadgets</>|List of gadgets by popularity in Wikimedia projects
 * Compatibility - MediaWiki's JavaScript support per browser and browser version

Live chat

 * There is an IRC channel on the Freenode network: