Gadget kitchen

Jump to navigation Jump to search
Other languages:
Deutsch • ‎English • ‎français

Welcome to the gadget kitchen. This is intended to become a space where developers far and wide can coordinate their work on user scripts and gadgets to the benefit of the MediaWiki community far and wide. Right now, it's a quick tutorial to get you started.

What are user scripts and gadgets?[edit]

One of MediaWiki's coolest features is that it enables anyone to immediately write enhancements to the software, and to share those enhancements with other users.

  • User scripts are publicly visible scripts (written in JavaScript) which are executed for a given user
  • Gadgets are user scripts which a wiki admin has "promoted" by adding them to MediaWiki:Gadgets-definition, which makes them available in the "Gadgets" tab of user preferences for all logged-in users.

If you're running your own copy of MediaWiki, $wgAllowUserJs needs to be enabled for user scripts to work, and the Gadgets extension needs to be installed to make it possible to promote individual scripts to gadget status. Both are enabled for nearly all Wikimedia Foundation sites, including Wikipedia.

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

I want to try![edit]

  1. Ensure you are logged in, then visit Special:MyPage/common.js. This file holds your personal JavaScript that is loaded on every page view.
  2. Create this page with the following text:
  3. Save. You should now have a link in the toolbox section called "Quick changelog" which shows you a subset of recent changes in a quick pop-up.
Tutorial by Brion Vibber regarding gadgets and user scripts at the San Francisco Hackathon January 2012

I want to do more![edit]

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.

Note Note: Clicking "Preview" (or using the keyboard shortcut, typically Shift+Alt+P) 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 "Save page".

Are there additional tutorials?[edit]

What's this ResourceLoader thing?[edit]

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. Starting with MediaWiki 1.26, gadgets must use ResourceLoader (phab:T107399).

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

  • Modules — A list of JavaScript libraries, jQuery plugins and MediaWiki utilities that already exist within ResourceLoader for you to reuse.
  • Developing with ResourceLoader — A list of useful practices, like enabling the debug mode and help with debugging.

Note Note: Changes to ResourceLoader ("Gadgets 2.0") will make managing gadgets even simpler.

What should I work on?[edit]

How do I use my script on other wikis?[edit]

Let's say you want to run the script on English Wikipedia instead of You can't use importScript() to import a page of JavaScript from a different wiki, but you can 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 User:YourName/YourScript.js. Ta-da! It's really that easy to customize your experience on one of the largest web sites on the planet.

Note Note: If your gadget uses the MediaWiki API, add the "?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 restrictions.

Developing gadgets[edit]

Got any tips for writing or debugging JS?[edit]

Writing a gadget
  • Gadgets are usually compacted by the resource loader, minimized and aggregated. use the debug=true 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.
  • Read the Google Chrome developer tools documentation or Firebug documentation to get the most out of the powerful debugging tools built into your browser.
    • If you experience issues with cached versions of scripts, it can be helpful to disable all caching. Click the settings (gears) icon in the Chrome developer console and select "Disable cache", or click "Disable Browser Cache" in the Net panel's dropdown menu in Firebug.
  • The ExternalArticles extension can be used to work on gadget code in an external IDE (it will update the corresponding wiki pages every time a file is saved).
Gadgets are developed by community and as of today there is no formal code review required for them (see discussion phab:T71445). However, it is strongly recommended to follow best practices!
You should not load external resources that may harm users privacy. For example in WMF wikis, the following domains are considered safe:
  • *
  • *
  • *
  • *
  • *
  • *
  • *
  • *
There is a Jenkins job (job, code) for automatic check of this principle

Where can I find more docs?[edit]

These are key resources:

Live chat[edit]