Extension:Gadgets/Gadgets 2.0

Tracked in Phabricator
Task T31272

Gadgets 2.0 is a broad overhaul of the Gadgets extension to make it more powerful and user-friendly. See ResourceLoader/Version 2 Design Specification for more information.

Features

A Gadget Manager interface making it easy to create, edit, or delete gadgets from a wiki
~~New Gadget and Gadget_definition namespaces (along with associated content models and user rights)~~
Simple interface for exporting gadgets
Multi-language support for Gadgets via localized messages

Gadget Manager

New Special:Gadgets page

Interface for creating new gadgets

Gadgets 2.0 will feature a completely revamped Special:Gadgets page. This page will allow users to not only view the configured gadgets, but also create, edit, and delete them. It will replace MediaWiki:Gadgets-definition as the interface for managing the gadgets on a wiki.

Adding multi-language support to a gadget

Gadgets can now easily use translatable MediaWiki messages. This means that your gadget's interface can be rendered entirely in the language of the user using the gadget (regardless of what wiki they are on). There are two ways that a message and its translations can be defined: either within the MediaWiki software itself or on-wiki in the MediaWiki namespace (or both).

Defining messages

If your gadget has a simple interface, you may be able to find messages already defined in the MediaWiki software. Some examples:

Message key	Translated message
ok	OK
cancel	Cancel
go	Go
view	View
delete	Delete
badaccess	Permission error

If your gadget has a more complicated interface, you may need to define your own messages for it. For example, let's say that you want to create a link for your gadget that says "My favorite categories", but you want it to be translatable. To create this translatable message, you will need to create a page for it in the MediaWiki namespace. The page will be titled MediaWiki:<message-key>, where <message-key> is a string with no spaces related to the message you are creating. It is strongly recommended that you prefix the message key with "gadget-<name-of-your-gadget>-" so that it doesn't collide with messages defined for other gadgets or MediaWiki software. If your gadget were named "Category links", you could create the message page at MediaWiki:gadget-categorylinks-favorite-categories.

The content of the MediaWiki page should be the string you want displayed written in the default language of the wiki. In our example above, this would be "My favorite categories" (if you were on the English Wikipedia). You could then enable a French translation by creating a page at MediaWiki:gadget-categorylinks-favorite-categories/fr with the French version of the string: "Mes catégories favorites". For each language that you want to support, just create additional sub-pages of your MediaWiki message pages using the language codes for those languages.

Adding defined messages to your gadget definition

To make messages available for your gadget to use, you must add them to your gadget definition. To do this, click the "Modify gadget" link for your gadget within the Gadget Manager. This will launch the editing interface (similar to the creation interface pictured above). In the Messages field, type the key for the translatable message, for example, "gadget-categorylinks-favorite-categories" or "cancel". If the key is valid it will turn into a blue "propcloud" item in the Messages field.

Adding defined messages to your gadget code

After you have added messages to your gadget definition, you can then use them in your gadget's JavaScript code. To do this, follow the directions given at Manual:Messages API . To follow our example above, you could create your link with:

$( '<a>' ).prop( 'href', '#' ).text( mw.msg( 'gadget-categorylinks-favorite-categories' ) );

Upgrading a wiki to Gadgets 2.0

Temporary method until Gadgets 2.0 code is merged

To try out the new Gadgets 2.0 interface, you'll need to check out the development code from the Gadgets repo. If you have already cloned the existing Gerrit repo for Gadgets, you can do this by running the following command from the repo:

git review -d 247869

... or if you don't have git review installed:

git fetch https://gerrit.wikimedia.org/r/mediawiki/extensions/Gadgets refs/changes/69/247869/37
git checkout FETCH_HEAD

You will then need to update your LocalSettings.php config with the following:

$wgGadgetsRepoClass = "GadgetDefinitionNamespaceRepo";

Migrating existing gadgets

Warning:

Once you do this there's no going back. If you later decide to go back to Gadgets 1.0, you'll have to move all the moved gadgets manually.

To migrate your existing gadgets, run the update.php script. This will move your existing gadget JS and CSS pages into the Gadget namespace and will create new gadget definitions in the Gadget_definition namespace.