Wikiup:Technik/Skin/Gadgets

aus Wikipedia, der freien Enzyklopädie

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    ⧼prefs-gadgets⧽   dargestellt.

Benutzereinstellungen

  • Die Einbindung durch Benutzer ist einfach möglich, indem das gewünschte Gadget in der Benutzer-Einstellung    ⧼prefs-gadgets⧽   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.

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

  • Eine Veränderung ist nur durch Administratoren 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), 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.

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 Administratoren 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:

* Bezeichner[Optionsliste]|Quellcode-Liste
  • Dabei ist Optionsliste eine durch | gegliederte Aufzählung von Optionen; Beispiel:
    [ResourceLoader|dependencies=mediawiki.util]
  • An Pipes und Kommata sind Leerzeichen zulässig.

Liste der Quellcode-Systemnachrichten

Auf den Bezeichner und möglicherweise die Optionsliste folgt die Liste der Verweise auf Quellcode-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.

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.

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

Seit Anfang 2022

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.

Deklaration:
  • [actions=Liste von Aktionen]
bzw. angehängtes
  • |actions=Liste von Aktionen
in einer vorhandenen Optionsliste.

Geräte

Durch Kommata getrennte Liste von Ausgabegeräten. Zurzeit sind das: desktop mobile

  • Vorgabe ist desktop – auf Mobilgeräte haben die Definitionen standardmäßig keinen Einfluss.
Deklaration:
  • [targets=Liste von Ausgabegeräten]
bzw. angehängtes
  • |targets=Liste von Ausgabegeräten
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[1] und soll mittelfristig vermeiden, dass sicherheitshalber CSS-Ressourcen doppelt geladen werden müssen.

Ü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.

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]

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.

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.

Zukünftige Namensräume

Im Sommer 2015 wurden neue Namensräume angelegt:

Nr. Name Änderungsrecht Geplante Verwendung
2300 gadgets-edit Ressourcen (JS- und CSS-Quellcodes)
2301 Diskussionsseiten zu Gadget, betrieben mit Flow
2302 gadgets-definition-edit Nachfolger von MediaWiki:Gadgets-definition.
Enthält möglicherweise nur diese eine Seite.
2303 Diskussionsseite zu ', betrieben mit Flow

Grund für die neuen Namensräume ist, dass für die sicherheitsseitig heikleren Ressourcen neue Benutzerrechte eingeführt werden sollten; was im Sommer 2018 mit den Benutzeroberflächenadministratoren erfolgte.

  • Lokal (in der deutschsprachigen Wikipedia) ist das mittlerweile geregelt.
  • Global sind unterschiedliche Zuordnungen vorstellbar.
    • Globale Gadget-Betreuer könnten auf allen Wikis das Recht erhalten, deren Quellcodes zu pflegen und zu verteilen.
    • Das wird zwangsläufig das Recht einschließen, auch auf jedem Wiki die Definitionsseite zu warten.
    • Auf kleineren Wikis, die ohnehin keine Kapazitäten zur sicherheitstechnischen Wartung ihres JavaScript-Codes haben, ist das Recht zur Veränderung von Gadget-Quellcodes den Administratoren entzogen worden.
    • Fraglich war, ob die WMF auch bei größeren Wikis wie der englisch- oder deutschsprachigen Wikipedia die Veränderungsmöglichkeiten an diesen Namensräumen irgendwann an sich ziehen wird oder es weiterhin der Community überlässt. Personell wird es zumindest mit den hauptberuflichen Kräften eng, den individuellen Konfigurationswünschen von 1000 WMF-Wikis unterschiedlicher Aufgaben und Kulturen nachzukommen und jede Zeile JavaScript und CSS selbst zu programmieren und in die Seiten zu kopieren.

Der MediaWiki-Namensraum soll wieder auf reine Systemnachrichten beschränkt werden, also auf Seitennamen, Reintext und kurze Wikitext-Sequenzen. Dass vor einem Jahrzehnt dort die Monobook.js untergebracht wurde, gilt als Sündenfall und war aus der Not geboren.

Die Vorlage:MediaWikiGadgetPage ermöglicht robuste Verlinkungen in Beschreibungen.

Dokumentationsseiten zu den Gadgets werden intelligenterweise nicht im Gadget-Namensraum angelegt. Zwar wäre Wikitext dort technisch sicher möglich, aber zur Korrektur jedes Tippfehlers müsste ggf. ein globales Bug-Ticket ausgelöst werden.

  • Dokumentationsseiten, Testseiten und Beispielzusammenstellungen wären also weiterhin als Unterseiten dieser Seite im Projekt-Namensraum zu führen.
  • Diskussionsseiten zur Dokumentation zu missbrauchen wäre angesichts von Flow nicht weitsichtig.
  • Die Diskussionsseite wird dann eher als Weiterleitung in den Projektbereich zu erwarten sein, wie das im Modul-Namensraum aus gleichen Gründen bereits praktiziert wird.

Unklar ist, ob die Zwischenüberschriften der Definitionsseite im MediaWiki-Namensraum verbleiben oder ihr im Namensraum 3202 Gesellschaft leisten sollen. Eine Implementierung ist noch nicht realisiert.

Weitere Informationen

MediaWiki: Extension:Gadgets – Freie Wikisoftware (englisch)
Phabricator – Quellcode: EGAD/*

Anmerkungen

  1. ↑ 1.28.0-wmf.21, phab:T42284 / gerrit:308096
Abgerufen von „https://de.wikiup.org/index.php?title=Wikiup:Technik/Skin/Gadgets&oldid=226094410“