Wikipedia:Technik/Skin/Gadgets

Gadgets (Helferlein)

---

Gadgets (in der deutschsprachigen Wikipedia meist Helferlein genannt) sind Hilfsmittel für die Benutzeroberfläche, die von angemeldeten Benutzern über die Einstellungen jederzeit individuell zu- oder abgewählt werden können.

Diese Projektseite beschreibt für Programmierer und Administratoren die technischen und organisatorischen Angelegenheiten.

Das aktuelle Angebot für die angemeldeten Benutzer ist auf Benutzer-Einstellung   Helferlein   dargestellt.

Benutzereinstellungen

• Die Einbindung durch Benutzer ist einfach möglich, indem das gewünschte Gadget in der Benutzer-Einstellung   Helferlein   ausgewählt wird.
• Die jeweils aktuell verfügbaren Helferlein werden dort thematisch gruppiert angezeigt.
• Gadgets werden immer in der aktuellen Form eingebunden (jede Veränderung bekommt eine unterschiedliche URL); Leeren des Browser-Cache ist deshalb nach Veränderungen nicht erforderlich.

Gelegentliches Laden

Wenn ein Helferlein nicht bei jedem Aufruf einer Seite geladen werden soll, sondern etwa nur in bestimmten Namensräumen, nicht beim Bearbeiten der Seite oder unter sonstigen benutzerdefinierten Bedingungen, dann lässt sich das im Benutzer-JS veranlassen wie unten angegeben.

Nicht angemeldete Benutzer

Nicht angemeldete Benutzer können die Helferlein ebenfalls nutzen, indem sie die Ressourcen mittels Greasemonkey/Browser-Skript laden wie unten angegeben.

Als Opt-out markierte Helferlein lassen sich jedoch nicht abschalten.

Name der Einstellung

Jede Einstellung im Benutzerprofil hat einen Namen; für ein Gadget lautet er:

gadget-Bezeichner

Arten

Es gibt für ein Gadget die Möglichkeit, JavaScript einzubinden (der häufigste Fall) und dies auch mit CSS zu kombinieren oder ein reines CSS-Gadget zu definieren.

Management und Vorschläge

Nur eine kleine Auswahl von besonders häufig benötigten Werkzeugen kann allen Benutzern angeboten werden.

• Vorschläge für gut dokumentierte, sichere und erprobte Skripte können auf Wikipedia:Technik/Skin/MediaWiki/Änderungen gemacht werden.

Beim Gadget übernimmt die Gemeinschaft eine Mitverantwortung für die ordnungsgemäße Funktion.

• Eine Veränderung ist nur durch Benutzeroberflächenadministratoren möglich.
• Die Funktion muss für eine große Zahl von Benutzern sinnvoll sein. Ansonsten werden Definitionsseite und Einstellungen zu unübersichtlich, und Wartung und Pflege sind kaum noch zu leisten.
• Sind ursprüngliche Autoren nicht mehr aktiv, versuchen andere Programmierer die Funktionalität zu erhalten. Das ist nur in begrenztem Umfang möglich.

Spezialseite

Auf der Spezialseite Spezial:Helferlein kann unmittelbar auf den Quellcode aller Helferlein zugegriffen werden, und es werden die Kurzbeschreibungen wie auf der Benutzereinstellungsseite angezeigt.

Außerdem werden Einzelheiten aus der Definitionsseite angegeben, also ob das Helferlein andere Module benötigt, ob es standardmäßig für alle Benutzer aktiviert ist und ob spezielle Berechtigungen erforderlich sind (heißt: nur für Administratoren gedacht).

Schließlich gibt es zu jedem Helferlein ein Link „Export“, das im XML-Format die Kurzbeschreibung usw. sowie die beteiligten Quellcodes in einer Datei zusammenfasst. Das ist dazu gedacht, das Gadget möglichst einfach in einem anderen Wiki-Projekt importieren zu können.

ResourceLoader

Jedes Modul für ein Gadget hat folgenden Namen:

ext.gadget.Bezeichner

Zum Modul gehören alle Seiten (Systemnachrichten: MediaWiki/Ressourcen), die in der entsprechenden Anweisung auf der Definitionsseite in die Liste aufgenommen wurden. Systemnachrichten ohne diese Definition werden nicht erkannt.

Bezeichner

Die Gadget-Bezeichner müssen mit einem Buchstaben ([A-Za-z]) beginnen, gefolgt von jeder Zahl von Buchstaben, Ziffern ([0-9]), gegliedert durch Bindestrich (-), Unterstrich (_), Doppelpunkt (:) und Punkt (.).

Zwar ist es nicht ausdrücklich ausgeschlossen und könnte wahrscheinlich funktionieren, aber aus zahlreichen Kompatibilitätsgründen bei der Nutzung durch JavaScript-Anweisungen und für gut lesbare URL beschränkt man sich auf den ASCII-Zeichensatz und verzichtet auf Umlaute usw. Die Bildung der Kodierung nach UTF-8 kann zu unterschiedlichen Bezeichnern an irgendeiner Stelle führen. Unterstreichungstriche verhindern einfache eindeutige Abschnittsüberschriften bei der Beschreibung. Ohne Bindestriche (-) lassen sich ggf. eindeutigere Suchausdrücke und weitere Nutzungen erreichen.

Zu jedem Gadget-Bezeichner sollen Administratoren eine textliche Systemnachricht als Wikitext anlegen, welche in einem Satz die Funktion erläutert. Sie wird bei den Einstellungen des Kontos und auf der Spezialseite dargestellt und solte, soweit vorhanden, die Dokumentation zu diesem Gadget verlinken.

Die Systemnachricht wird auf MediaWiki:Gadget-Bezeichner hinterlegt.

Die Systemnachrichten können auch als Unterseite /en eine englischsprachige usw. Version anbieten.

Manuelles Laden

Alle JavaScript- und CSS-Ressourcen eines Gadgets lassen sich auf einmal in der aktuellen Version laden.

• Nicht ausgewertet werden dabei die in der Gadget-Definition spezifizierten Einschränkungen.

Aus dem eigenen Projekt heraus

mw.loader.load( "ext.gadget.Bezeichner" );

Aus jedem anderen Wiki heraus

mw.loader.load( "https://de.wikipedia.org/w/load.php?modules=ext.gadget.Bezeichner" );

• Beachte das ausführende PHP-Skript load.php – sonst stünde index.php an dieser Stelle.

Definitionsseite

Die wirksame Definition im Wiki erfolgt über die Seite MediaWiki:Gadgets-definition, die nur von Benutzeroberflächenadministratoren geändert werden kann.

Gadgets sollten so programmiert sein, dass sie nicht vom Eintrag in der Definitionsseite abhängig sind, sondern auch alleinstehend gestartet werden können. Zum einen ist das für die Entwicklung und zum Testen sinnvoll; zum anderen erlaubt das auch dynamische Zugriffe nur unter bestimmten Bedingungen, etwa nur in bestimmten Namensräumen.

Diese Definitionsseite selbst kann ganz normal angesehen werden. Innerhalb der daraus resultierenden Spezial:Einstellungen #mw-prefsection-gadgets sind jedoch keinerlei projektdefinierte CSS- oder JS-Ressourcen wirksam.

Format des Eintrags

Jeder Eintrag für ein Gadget hat die Form:

* Bezeichner|Quellcode1|Quellcode2

• Eine Systemnachricht MediaWiki:Gadget-Bezeichner muss als Wikitext eine Kurzbeschreibung enthalten, die auf der Benutzereinstellungsseite angezeigt wird.

Die Definition kann mit Optionen versehen werden: Jeder Eintrag für ein Gadget hat die Form:

* Bezeichner[Optionsliste]|Quellcode-Liste

• Dabei ist Optionsliste eine durch | gegliederte Aufzählung von Optionen; Beispiel:

  [ResourceLoader|dependencies=mediawiki.util]

  • Geeignet für Einbindung mittels ResourceLoader.
  • Hängt vom Modul mediawiki.util ab, das vor dem Start geladen worden sein sollte.

• An Pipes und Kommata sind Leerzeichen zulässig.

Liste der Quellcode-Ressourcen

Auf den Bezeichner und möglicherweise die Optionsliste folgt die Liste der Verweise auf Quellcode-MediaWiki/Ressourcen (Systemnachrichten).

• Die Liste sollte möglichst auf eine Seite für JS und eine für CSS beschränkt bleiben, um den Überblick nicht zu verlieren.
• Deshalb sollten sie auch denselben Bezeichner verwenden:

  * Bezeichner|Bezeichner.js|Bezeichner.css

Gemeinsame Bibliotheksressourcen sind in der deutschsprachigen Wikipedia kaum vorhanden, ließen sich aber ohne eigenständiges Gadget als „Systemnachricht“ definieren und auflisten.

• Im Prinzip sind somit auch weitere Seiten und Unterseiten möglich. Ein JavaScript-Gadget könnte sie aber auch selbst nachladen. Das müsste es ohnehin automatisch machen, wenn die Ressourcen noch nicht geladen sind, damit es getestet und außerhalb der Gadget-Automatik eingesetzt werden kann. Weitere Ressourcen sind möglicherweise nicht immer erforderlich und müssten nur bei tatsächlichem Bedarf nachgefordert werden.

Jedem Quellcode-Verweis wird MediaWiki:Gadget- zur Bildung des Seitennamens vorangestellt.

ResourceLoader

Geeignet für Einbindung mittels ResourceLoader.

Deklaration:

• [ResourceLoader]

Die Quellcodes werden nicht einfach aus den Mediawiki-Seiten geladen, sondern es werden automatisch Pakete daraus gebildet und diese versioniert.

Achtung: Die Paketbildung setzt voraus, dass die Programmierung auf einem modernen Stand ist.

• Die JavaScript-Einheiten werden gekapselt.
• Das hat zur Folge, dass angebotene Funktionsaufrufe über das globale Objekt angeboten werden müssen, also window oder besser mw.libs verwenden.
• Deklarationen über var und Funktionsdeklarationen haben nur lokale Wirkung.

Optionsliste

Abhängigkeiten

Durch Kommata getrennte Liste von Modulen (MW-Standard-Module).

Deklaration:

• [ResourceLoader|dependencies=Liste von Modulen]

bzw. angehängtes

• |ResourceLoader|dependencies=Liste von Modulen

in einer vorhandenen Optionsliste.

• Die Option ResourceLoader muss in der Optionsliste vorhanden sein.

Um ein Gadget jedoch universell nutzen zu können und bereits für die Entwicklungsphase ist es sinnvoll, wenn auch intern das Vorhandensein erforderlicher Module geprüft und bei deren Fehlen das Nachladen veranlasst wird.

Das Laden in Standardsituationen kann jedoch effizienter gestaltet werden, wenn von vornherein sichergestellt ist, dass benötigte Module in demselben Paket ausgeliefert werden.

Achtung: Die beiden fundamentalen Module mediawiki und jquery dürfen niemals als Abhängigkeiten aufgeführt werden, da es sonst zu einer deadlock-Situation kommt.

Die Anforderung eines nicht existierenden Moduls (womöglich falsch geschriebenen Modulnamens) führt nur zu einem einfachen Fehler mit begrenzten Auswirkungen.

Skins

Durch Kommata getrennte Liste von Skin-Bezeichnern, wie etwa: cologneblue modern monobook vector

Deklaration:

• [skins=Liste von Skin-Bezeichnern]

bzw. angehängtes

• |skins=Liste von Skin-Bezeichnern

in einer vorhandenen Optionsliste.

Die Präsentation des Gadgets auf der Einstellungsseite wird auf solche Benutzer beschränkt, die momentan eine dieser Skins aktiviert haben. Die Einstellungswirkung des Gadgets bleibt nach einem Skin-Wechsel jedoch erhalten; es wird allerdings nicht ausgeführt, solange keine geeignete Skin vom Benutzer gewählt wurde.

Die Präsentation ist intransparent; die fortbestehende Wirkung nach der Rückkehr zu dieser Skin würde kaum bemerkt werden. Gadgets sollten sowohl in JS wie CSS die momentan aktive Skin abfragen, wenn Einschränkungen bestehen, und darauf dynamisch reagieren. Die Deklaration dieser Option ist zu vermeiden. Es kann in Kauf genommen werden, Gadgets überflüssigerweise zu laden, die von den Benutzern zwar aktiviert wurden, selbst wenn zwischenzeitlich eine andere Skin ausgewählt wurde.

Opt-out

Seit MW 1.18 gibt es die Möglichkeit, ein Gadget standardmäßig als opt-out zu vereinbaren. Es wird dann bei allen nicht angemeldeten Benutzern ausgeführt, und angemeldete Benutzer müssen es explizit deaktivieren.

Deklaration:

• [default]

bzw. angehängtes

• |default

in einer vorhandenen Optionsliste.

Benutzerrechte

Durch Kommata getrennte Liste von Kennwörtern für ein Benutzerrecht (keine Benutzergruppen wie etwa sysop). Damit kann die Präsentation des Gadgets auf der Einstellungsseite auf solche Benutzer beschränkt werden, die alle diese Rechte haben. Praktisch wird es auf die Administratoren hinauslaufen.

Deklaration:

• [rights=Liste von Benutzerrechten]

bzw. angehängtes

• |rights=Liste von Benutzerrechten

in einer vorhandenen Optionsliste.

Im Prinzip handelt es sich um eine Komma-getrennte Liste; alle aufgezählten Rechte müssen gleichzeitig vorliegen. Praktisch kommt es durch den Pyramidenaufbau der Rechte wohl kaum dazu, dass mehr als ein Recht anzugeben wäre.

Aktionen

Durch Kommata getrennte Liste von Kennwörtern für eine Aktion (view, edit, history, etc). Falls angegeben, wird das Helferlein nur bei der/den angegebenen Seitenaktion(en) ausgeführt. edit schließt submit ein. (seit Anfang 2022)

Deklaration:

• [actions=Liste von Aktionen]

bzw. angehängtes

• |actions=Liste von Aktionen

in einer vorhandenen Optionsliste.

Geräte

Dieses Feature wurde 2023 auf korrespondierende Skins migriert und im Januar 2024 beendet.

Durch Kommata getrennte Liste von Ausgabegeräten. Das waren: desktop mobile

• Vorgabe war desktop – auf Mobilgeräte hatten die Definitionen standardmäßig keinen Einfluss.

Deklaration:

• [targets=Liste von Ausgabegeräten]

bzw. angehängtes

• |targets=Liste von Ausgabegeräten

in einer vorhandenen Optionsliste.

Namensräume

Durch Kommata getrennte Liste von Namensraum-Nummern (seit Herbst 2023).

• Vorgabe ist: alle.
• Beispiel für typische Foren: 1,3,4,5,7,9,11,13,15,100,101

Deklaration:

• [namespaces=Liste von Namensraum-Nummern]

bzw. angehängtes

• |namespaces=Liste von Namensraum-Nummern

in einer vorhandenen Optionsliste.

Inhaltsmodelle

Durch Kommata getrennte Liste von Inhaltsmodellen (seit Herbst 2023).

• Vorgabe ist: alle.
• Beispiel für Ressourcen: css,javascript,json

Deklaration:

• [contentModels=Liste von Inhaltsmodellen]

bzw. angehängtes

• |contentModels=Liste von Inhaltsmodellen

in einer vorhandenen Optionsliste.

Kategorien

Seit Ende März 2024 kann das Laden auf (fast nur Wikitext-)Seiten eingeschränkt werden, die in bestimmten Kategorien gelistet sind.

Durch Kommata getrennte Liste von Kategorie-Titeln.

• Vorgabe ist: jede Seite.
• Kategorien, die ein Komma im Titel enthalten, wurden vom Programmierer nicht berücksichtigt.
• Mehrere Kategorien erweitern im Sinne einer ODER-Verknüpfung die wirksamen Seiten; jede Seite, die von Kategorie1 oder auch Kategorie2 erfasst ist.

In der deutschsprachigen Wikipedia werden Unterkategorien von Kategorie:MediaWiki:Gadget verwendet, deren Titel durch Anhängen des Bezeichners gebildet wird.

Deklaration:

• [categories=Liste von Kategorie-Titeln]

bzw. angehängtes

• |categories=Liste von Kategorie-Titeln

in einer vorhandenen Optionsliste.

Vorrangiges Laden

In sehr seltenen Fällen (etwa für VisualEditor-Plugins) ist es sinnvoll, ein Gadget vor anderen Modulen zu laden.

Deklaration:

• [top]

bzw. angehängtes

• |top

in einer vorhandenen Optionsliste.

Ressourcen-Typ

Bei Ressourcenlisten, die auch CSS enthalten, ist zu entscheiden, ob sie am Anfang geladen werden müssen, und möglichst schon auf den ersten Seitenaufbau wirken sollen, oder ob dies zusammen mit den anderen Ressourcen und JavaScript geschehen kann. Werden HTML-Elemente erst durch das JavaScript-Gadget generiert, und sind sie womöglich nicht ohne Benutzeraktivität sichtbar, dann genügt der zweite Fall.

Deklaration:

• [type=]

bzw. angehängtes

• |type=

in einer vorhandenen Optionsliste.

Dabei kann einer der beiden Werte angegeben werden:

• type=general
  • Wird vom Wiki-Server automatisch gesetzt, wenn alle Ressourcen JavaScript sind.
  • CSS-Ressourcen werden zusammen mit JavaScript geladen; also ggf. später.
• type=styles
  • Wird vom Wiki-Server automatisch gesetzt, wenn alle Ressourcen CSS sind.
  • Die CSS-Ressourcen werden zum ersten Seitenaufbau geladen.
• Keine Spezifikation:
  • Zumindest übergangsweise wird CSS doppelt geladen; einmal zum Seitenaufbau und einmal beim Laden von JavaScript.
  • Relevant bei Gadgets, die Ressourcen beider Art enthalten.
  • Es sollte dann explizit mittels type=general spezifiziert werden, dass ein späterer Ladezeitpunkt ausreicht.

Wenn ein Gadget sowohl CSS- wie auch JavaScript-Ressourcen enthält und es erforderlich ist, dass das CSS bereits auf den Seitenaufbau wirkt, dann sollte dieses in ein separates, ggf. verstecktes Gadget ausgelagert werden. Es kann durch eine Abhängigkeitsdeklaration vom eigentlichen JavaScript-Gadget abgefordert werden.

Diese Funktionalität wurde Anfang Oktober 2016 eingeführt und soll mittelfristig vermeiden, dass sicherheitshalber CSS-Ressourcen doppelt geladen werden müssen.

Versteckte Module

Durch Kennzeichnung mit hidden werden Gadgets in der Einstellungsseite unsichtbar. Das wirkt sich nur auf die Einstellungsseite aus; aus den sonstigen Datenstrukturen wird die Definition nicht entfernt.

Somit lassen sich Gadgets vor den Benutzern verstecken, aber trotzdem die Zuweisung des Bezeichner zu einem Quellcode nutzen, wie auch die weitere Effizienzsteigerung bei der Paketbildung.

Deklaration:

• [hidden]

bzw. angehängtes

• |hidden

in einer vorhandenen Optionsliste.

Diese Code-Blöcke können auch als dependencies angegeben werden.

Zwar sind die Gadgets in der Einstellungsseite niemals zu sehen, für niemanden; jedoch wird ihr Beschreibungstext auf Special:Gadgets erwartet. Fehlt dieser, dann gibt es hässlichen Ersatz und ein Rotlink würde produziert. Es soll deshalb immer eine Nachricht für den Beschreibungstext erstellt werden, in der dann auch auf eine Dokumentation verlinkt werden kann.

Enthält ein Abschnitt nur versteckte oder für dieses Konto nicht wirksame (rights, skins) Gadgets, so wird auch dessen Abschnittsüberschrift nicht angezeigt.

Bis November 2016 wurden für versteckte Module Konstrukte der Form

[rights=hidden-gadget]
[rights=hidden-NIEMAND]

verwendet. Durch Forderung nach einem frei erfundenen Benutzerrecht wurde die gleiche Wirkung erzielt. Das kann mittlerweile umgestellt werden und sollte zur Verständlichkeit auch nicht mehr genutzt werden.

Überschriften

Die Einstellungsseite kann gegliedert werden durch

== Was-Neues ==

und diese erscheinen auch auf der Spezialseite.

Der deutschsprachige Text für die Überschrift (hier Was-Neues) muss in einer Systemnachricht MediaWiki:Gadget-section-Was-Neues hinterlegt werden.

Neben H2-Überschriften sind auch tiefere Ebenen möglich.

Die Systemnachrichten können auch als Unterseite /en eine englischsprachige usw. Version anbieten.

Systemgadgets

Systemgadgets enthalten CSS- und JavaScript-Code, der über das Gadgetsystem geladen wird, aber nicht zum de-/aktivieren durch einzelne Benutzer vorgesehen ist. Systemgadgets sind standardmäßig für alle registrierten und nicht registrierten Benutzer aktiviert. Ihren Ursprung haben sie meist in den zentralen Ressourcenseiten, also etwa der MediaWiki:Common.css, aus der sie ausgelagert wurden. Dieses Vorgehen hat folgende Vorteile:

• Das Laden von Code ist über die Definitionsseite zielgerichteter möglich, etwa durch die Beschränkung auf Namensräume und Aktionen. Code in zentralen Ressourcenseiten wird dagegen bei jedem Seitenaufruf geladen, auch wenn dieser in einem Fall gar nicht erforderlich wäre.
• Es können Redundanzen zwischen zwischen Desktop- und Mobilansicht vermieden werden, wenn über Gadgets der selbe Code in beiden Ansichten geladen wird. Dies ist über die Ressourcenseiten nur eingeschränkt möglich.
• In der Versionsgeschichte des Gadgets finden sich nur Codeänderungen, die die dort bereitgestellten Funktionen betreffen. Änderungen sind über die Zeit somit leichter nachzuvollziehen.

Derzeit sind folgende Systemgadgets aktiviert:

• citeRef – Verbesserungen und projektspezifische Anpassungen bei der Anzeige von Einzelnachweisen
• defaultPlainlinks – Darstellung ausgewählter Linkziele als interne Links
• desktopHauptseite – spezifische Formatierung der Hauptseite in der Desktopansicht
• dewikiCommonHide – projektweites Ausblenden bestimmter Elemente
• dewikiCommonLayout – projektweite CSS-Klassen für Positionierungen
• dewikiCommonStyle – projektweite CSS-Klassen für Hintergrund- und Rahmenfarben
• donateLink – Umbiegen des Spendenlinks in der Seitenleiste auf die Spendenadresse von Wikimedia Deutschland
• mobileHauptseite – spezifische Formatierung der Hauptseite in der Mobilansicht
• NavFrame – projektweite CSS-Klassen für ausklappbare Navigationsleisten
• prettytableLegacy – Definition der früher genutzten prettytable-Klasse für den Benutzernamensraum
• sourceEditing – Verbesserungen bei Quelltext-Bearbeitungen
• specialpageLoader – Nachladen weiterer Gadgets auf bestimmten Spezialseiten
• uploadtools – ermöglicht die Vorschaufunktion im lokalen Hochladeformular
• watchlistMessage – ermöglicht das Ausblenden von Hinweisnachrichten auf der Beobachtungsliste

Zeitweise kann aktiviert werden:

• dewiki-logo – Änderung des Seitenlogos zu besonderen Anlässen

Weitere Informationen

MediaWiki: Extension:Gadgets – Freie Wikisoftware (englisch)

Phabricator – Quellcode: EGAD/*

• MediaWiki:Gadgets-definition – Spezifikation der Gadgets
• JS/Gadget – Hinweise für Gadget-Entwickler
• Alle Gadget-Unterseiten
• Spezial:GadgetUsage – Statistiken zur Nutzung von Helferlein pro Wiki