Gadget-Küche
Willkommen in der Gadget-Küche. Dies ist eine Anleitung, wie du Gadgets und Benutzerskripte in JavaScript schreiben und verwenden kannst.
Was sind Benutzerskripte und Gadgets?
MediaWiki allows anyone to write public 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 can be edited by the original author (if it is stored in the
User:
namespace) and by anyone with the "edituserjs" user right (usually just interface administrators).
The code is usually hosted on a subpage of your user page. Examples include: XTools/ArticleInfo.js and m:User:Hoo man/useful links.js. User scripts are similar to the personal JavaScript pages such as Special:MyPage/common.js, but they allow single code chunks to be shared with other users.
- Ein Gadget ist ein Benutzerskript, das von einem Schnittstellenadministrator "hochgestuft" wurde, indem es zu MediaWiki:Gadgets-definition hinzugefügt wurde Logged-in users can enable gadgets in the "Gadgets" tab of their user preferences. Gadgets are created and managed by interface administrators.
- For completeness: There is also the site-wide JavaScript located at MediaWiki:Common.js and several other pages. The JavaScript in those pages affects everyone and is executed automatically for both logged-out and logged-in users. Interface administrators can edit them. Read Manual:Interface/JavaScript for detailed information.
Wenn bei dir eine eigene Version von MediaWiki läuft, muss $wgAllowUserJs
aktiviert sein, damit Benutzerskripte funktionieren, und die Erweiterung für Gadgets muss installiert sein, damit Skripte in den Rang von Gadgets befördert werden können.
Um angenehmer arbeiten zu können, solltest du die CodeEditor extension in deinem Wiki installiert haben.
Write your first user script
In this section, you create an example user script which calculates the estimated reading time of a wiki page.
- Ensure you are logged in.
- Besuche Special:MyPage/common.js. This page holds your personal JavaScript that is loaded on every page view (except for Special:Preferences).
- Either create the page or edit the page if it already exists.
- Copy the following six lines and paste these lines into the page:
var numWords = $("#mw-content-text > div").text().split(" ").length; var headerWords = $("h1").text().split(" ").length; var totalWords = numWords + headerWords; var timeInMinutes = totalWords / 200; var header = $("h1").text(); $("h1").text(header + " (it will take you " + timeInMinutes + " minutes to read this page)");
- Klicke "Änderungen veröffentlichen".
- 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.
A more complex user script example
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.
Kopiere die Inhalte von MediaWiki:Tutorial-QuickRC.js in Deine Special:MyPage/common.js.
Das Ergebnis ist das gleiche wie vorhin. Aber jetzt kannst du das Skript verändern und ausprobieren, was passiert, wenn du andere Inhalte hineinschreibst.
Load an existing user script
In the previous section, you copied the content of a user script. In this section, you will load the existing script MediaWiki:Tutorial-QuickRC.js instead.
- Stell sicher, dass du eingeloggt bist
- Besuche Special:MyPage/common.js. This page holds your personal JavaScript that is loaded on every page view (except for Special:Preferences).
- Either create the page or edit the page if it already exists.
- 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');
- Click "Publish changes". You should now have a link in the "Tools" section called "Quick changelog".
- Click "Quick changelog". You get a pop-up window. It shows you a subset of the recent changes on this website.
Use a script on another Wikimedia wiki
Wenn du dein Skript statt auf MediaWiki.org in der englischsprachigen Wikipedia laufen lassen willst, kannst du das importScript()
hier nicht verwenden. Aber du kannst deinen Code über den ResourceLoader laden. Geh einfach auf common.js in der englischsprachigen Wikipedia und füge hinzu:
mw.loader.load("//www.mediawiki.org/w/index.php?title=MediaWiki:Tutorial-QuickRC.js&action=raw&ctype=text/javascript");
Natürlich kannst du auch das Benutzerskript laden, dass du gerade geschrieben hast, indem du MediaWiki:Tutorial-QuickRC.js in der URI oben in User:YourName/YourScript.js
änderst. Ta-daa! So einfach ist es, sich eine maßgeschneiderte Wikipedia zu basteln!
This first requires that you do not store the code of your user script in Special:MyPage/common.js itself but instead in a separate sub page of your user page.
This also helps to keep code in one single place, so you have to update code in only one place.
Entwickeln von Benutzerskripten und Gadgets
This section lists resources which are either needed or helpful for non-simple user scripts.
ResourceLoader
Helferlein müssen den ResourceLoader verwenden. Der ResourceLoader ist eine Kernfunktion des MediaWiki. Er spielt auf intelligente Art und Weise JavaScript- und CSS-Anwendungen aus. Da Gadgets immer in JavaScript geschrieben sind, musst du, wenn du Gadgets schreibst, immer mit dem ResourceLoader arbeiten.
Ihr Gadget sollte nützliche ResourceLoader-Module laden.
- Modules — Eine Reihe von im ResourceLoader schon vorhandenen JavaScript-Libraries, jQuery-Plugins and MediaWiki-Utilities. Bedien dich einfach!
- See the jQuery documentation for information about using jQuery in MediaWiki
- Developing with ResourceLoader — A list of useful practices, like enabling the debug mode and help with debugging.
- Also see the ResourceLoader best practices.
OOUI
OOUI is a JavaScript library with user interface elements (for example pop-up windows) specifically for use in MediaWiki. The library Using OOUI in MediaWiki#Gadgets can be used in gadgets.
MediaWiki Action API
Within the context of a MediaWiki website the Action API can be accessed from JavaScript via the mw.Api JavaScript API. (mw.ForeignApi for allowed cross-site requests, e.g. between WMF wikis.) See API for more information.
?callback=?
"-Parameter zur API-URL hinzu, sobald du eine API-Anfrage durchführst, die die Same-Origin-Policy verletzen würde (z.B. eine Anfrage an die Commons-API von Wikipedia aus). Das löst JSONP aus und setzt bestimmte Beschränkungen durch.VisualEditor
See VisualEditor/Gadgets for a tutorial specifically for VisualEditor gadgets.
Debugging user scripts and gadgets
- Gadgets are usually compacted by the ResourceLoader, minimized and aggregated. Use the
debug=true
URI parameter (preceded by?
or&
, of course), to ask for the non-compacted version of the page and to load the "original source form" of your gadget. Also see Developing with ResourceLoader for more information. - 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.
- If an existing gadget has problems, you can also use the page Special:Gadgets to find the source code location of a gadget.
Privacy and external content
Du solltest keine externen Skripte laden, die die Privatsphäre der NutzerInnen gefährden. In Wikimedia-Wikis gelten die folgenden Domänen als sicher:
- *.wiktionary.org
- *.wikimedia.org
- *.wikibooks.org
- *.wikisource.org
- *.wikiversity.org
- *.wikinews.org
- *.wikiquote.org
- *.wikidata.org
- *.wikivoyage.org
- www.mediawiki.org
Running code on page load
The common task of running code as soon as the page is loaded has several pitfalls which even experienced editors fall into.
- First of all, when your code works with elements of the DOM, run it on page load. Otherwise, your code may run too early. The general way to do it is to use jQuery's
$()
function, which does the same as$(document).ready()
. - However, if your code works with the content part of the page (the
#mw-content-text
element), you should use the'wikipage.content'
hook instead. This way your code will successfully reprocess the page when it is updated asynchronously and the hook is fired again. There are plenty of tools which do so, ranging from edit preview to watchlist autoupdate. - Be sure to only work with the descendants of the
$content
element that your handler function takes and not the whole page. Otherwise, you may end up running the same code for the same elements many times. Note that the'wikipage.content'
hook may be fired really many times. - Be cautious about what comes in the
$content
argument of the handler function. You shouldn't assume it's the#mw-content-text
element. It can be a small portion of the page, e.g. when it is previewed.
Code that works with page content and avoids the aforementioned pitfalls may look like this:
mw.hook( 'wikipage.content' ).add( function ( $content ) {
const $target = $content.find( '.targetClass' );
if ( $target.length ) {
// Do things with $target
}
// Only perform some operations when it is #mw-content-text in the argument
if ( $content.is( '#mw-content-text' ) ) {
const $note = $( '<div>' )
.addClass( 'myScript-note' )
.text( 'MyScript has successfully processed the content!' );
$content.prepend( $note );
}
} );
If your code works with page content and adds event handlers to DOM elements, then, instead of hooking to 'wikipage.content'
and looking for elements to attach event listeners to when it is fired, you may attach one event listener to an element outside of the content area or the whole document
but filter events by a selector (see jQuery's documentation).
That is, instead of writing $content.find( '.targetClass' ).on( 'click', ... )
you can write $( document ).on( 'click', '.targetClass', ... )
.
Recording metrics
Some gadgets are serious business. When your gadget gets serious, you might want to instrument it for analytics purposes, for example to measure the click rate of specific UI elements added to a page by the gadget.
Miscellaneous
- Gadget code doesn't have to follow the JavaScript coding conventions for MediaWiki, but if you expect others to touch your code, it may be used as reference.
- If you're developing in an IDE like VS Code, you may use type definitions for MediaWiki, OOjs, OOUI, and jQuery for code completion and type checking.
Disadvantages and problems of gadgets
- Gadgets werden von Community-Mitgliedern entwickelt. Bis heute ist für Gadgets auf Wikimedia-Websites keine formale Codeüberprüfung erforderlich (siehe phab:T71445). Bitte befolge die auf dieser Seite aufgeführten Best Practices.
- 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.
Ideen woran man arbeiten soll
Some Wikimedia community members may share their ideas what they would like to see implemented by someone else.
- phabricator:tag/wikidata-gadgets/ - you can do small fixes on already existing gadgets, or work on proposals
- Gadget Kitchen/Requests - not a popular page, so you might waste time
- w:Wikipedia:User scripts/Requests - for English Wikipedia
Deploying or enabling a gadget
If your user script should become a gadget (see the definitions above) on a wiki, the following steps are needed:
- Steps for the user script author:
- Recruit an experienced developer to review your gadget code. There is no formal process to do so.
- Check with community members if there aren't any concerns with enabling the gadget on a wiki. For the website MediaWiki.org itself, this would be Project:Village Pump.
- Recruit a site administrator with interface rights. See the page Special:ListUsers/interface-admin on your wiki.
- Steps for the interface administrator:
- Copy your JS & CSS files in the
MediaWiki:
namespace on your wiki, and make sure the page names have the prefixGadget-
.
Beispiel:MediaWiki:Gadget-userfeedback.js
- Define the gadget on the MediaWiki:Gadgets-definition page of your wiki. That includes the modules used, dependencies, JS, and CSS file names, etc. This will allow users to enable the gadget on the Special:Preferences page of your wiki.
Beispiel:userfeedback[ResourceLoader|default|dependencies=ext.eventLogging]|userfeedback.js|userfeedback.css
- Create a page for the gadget in the
MediaWiki:
namespace with prefixGadget-
. This will generate a label for the gadget on the Special:Preferences page of your wiki.
Beispiel:MediaWiki:Gadget-userfeedback
- Copy your JS & CSS files in the
Contributing to user scripts
If a user script is made by another user you may be able to contribute to it. You can do this by making a copy of the user script as a subpage of your own user page. Then replace the original user script you had enabled with the one that is a user page in your common.js. Proceed to make edits as you please to your copy of the script. If you want the script to contain the changes you made to your copy of the script, you should ping the author of the script on the discussion page of the original user script with the page that contains your changes and ask them to add the changes. If the user is no longer active, then you should notify the community that your version of the script exists by linking the script on your wiki's list of scripts.
Related pages
- 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 user scripts guide on the English Wikipedia has tons of useful information to get you started.
- Wikipedia:Gadget-Seite auf der englischsprachigen Wikipedia
- Slides for a workshop to teach the basics of user scripts and gadgets (part of meta:Small wiki toolkits)
- List of gadgets by popularity across all Wikimedia projects
- For a specific website, see Special:GadgetUsage for the number of users that each gadget has
- Kompatibilität - MediaWiki's JavaScript support per browser and browser version
- A video tutorial from the year 2012 regarding gadgets and user scripts. This is a bit outdated and the quality could be better, but shows how to use developer tools etc.
- See Erweiterung:EventLogging for a mechanism to gather data created from users interacting with a gadget.
- Category:Snippets with JavaScript – useful JavaScript snippets