Aufgrund einer Server-Wartung kommt es am 3. Juni 2025 zwischen 12:00 MESZ und 16:00 MESZ zu einer ca. 30minütigen Downtime des Forums.
Wir bitten um euer Verständnis.
Hilfe:SELFHTML-API
Im Rahmen der Makeover-Erzeugung ist ein kleines API entstanden, das auf dieser Seite beschrieben werden soll.
Inhaltsverzeichnis
mw.Selfhtml
Kern des API ist das Selfhtml-Objekt, das in die globale Mediawiki-Variable mw
eingesetzt wird. Es wird im zentralen Skin-Script selfhtml.js erzeugt. Etliche der angebotenen Methoden benötigen eine Ressourcen-ID. Sie dient entweder als ID für eine in skin.json konfigurierte Ressource, oder als Key im localStorage, um bestimmte Features in den API Funktionen für diese ID zu aktivieren. Da es in der Entwicklungszeit möglich ist, dass der Selfhtml-Skin unter verschiedenen Namen verfügbar ist (z.B. Selfhtml und Makeover), soll die Ressourcen-ID nicht fix im Code hinterlegt werden. Statt dessen soll sie mit Hilfe der mw.Selfhtml.resourceId(name) Methode generiert werden. Diese Methode schaltet dem übergebenen Namen das Präfix "skins." + SkinName vor, im Standardfall also "skins.Selfhtml.". Im Makeover-Skin war es "skins.Makeover.". Auf diese Weise kann ein fertiges Modul einfach in eine andere Selfhtml-Skinvariante übernommen werden, ohne dass man darin IDs austauschen muss.
Das Verfahren, bestimmte Testhilfe-Features über ein zentrales Konfigurationsmedium ein- und ausschalten zu können, nennt man Instrumentierung.
Das Selfhtml-Objekt bietet die folgenden Eigenschaften und Methoden an:
name
mw.Selfhtml.name: string
Der Name des Skins. Im Normalfall "Selfhtml", bei Varianten der Variantenname, z.B. "Makeover". Wenn DU eine Variante erstellt, denk daran, dies in selfhtml.js einzutragen.
resourceId()
mw.Selfhtml.resourceId(name): string
Wie schon gesagt: dem Namen wird ein zum Skin passendes Präfix vorangestellt.
loaded()
mw.Selfhtml.loaded(resourceId): void
Die loaded-Methode lädt aus dem localStorage den Eintrag zur übergebenen resourceId und führt je nach Wert folgendes aus:
-
show
oderdebug
: Protokollieren, dass die genannte resourceId geladen wurde -
debug
: Ausführen vondebugger;
. Bei aktiven Entwicklertools hält das Script dann an.
const resourceId = mw.Selfhtml.resourceId("access_nav.js");
mw.Selfhtml.loaded(resourceId);
ready()
mw.Selfhtml.ready(resourceId, msg='start'): void
Diese Methode kann aufgerufen werden, wenn eine Komponente auf das $.ready
oder DOMContentLoaded warten muss und der registrierte ready-Handler startet. Ist für die angegebene resourceId show
oder debug
instrumentiert, protokolliert dieser Aufruf den ready-Zustand der Komponente
report()
mw.Selfhtml.report(resourceId, string): string
Dies ist die eigentliche, instrumentierbare Protokollierungsmethode. Sie wird von loaded und ready genutzt, kann aber auch direkt verwendet werden. Ist für die resourceId der Wert show
oder debug
instrumentiert, wird in der Browserkonsole eine Zeile mit diesen Informationen geschrieben:
- Die Zeit in Millisekunden, seit die Seite geladen wurde (mediaWikiLoadStart)
- Die übergebene Ressourcen-ID
- Der übergebene String
Die Methode gibt den instrumentierten Wert zur Ressourcen-ID zurück.
buildForumQuestionUrl()
buildForumQuestionUrl(baseUrl): string
Helper für alle Module, die "Frage im Forum" anbieten wollen. Zu übergeben ist die Basis-URL im Forum, um einen neuen Beitrag zu erstellen ('https://forum.selfhtml.org/self/new'). Diese URL wird so erweitert, dass sie als href eines Links gesetzt werden kann, der zur aktuellen Seite einen Fragethread im Forum erstellt
requestES6Module()
mw.Selfhtml.requestES6Module(relativePath): Promise<Module>
Das aktuelle Mediawiki unterstützt keine ECMAScript-Module als konfigurierbare Ressource. Wenn Du eine Komponente als ECMAScript-Modul nachladen willst (z.B. Frickl 2.0 oder die Helferlein), verwende die diese Methode. Sie lädt das gewünschte Modul aus dem aktuellen Skin-Path. Rückgabe ist ein Promise, das zu einem Modul-Objekt resolved wird. Wie dieses Objekt aussieht, findest Du bei der Beschreibung der import()
-Funktion.
getReplacement()
mw.Selfhtml.getReplacement(resourceId): Promise<Module>
Mit dieser Methode kann für Selfhtml-Skinkomponenten, die Replacing unterstützen, eine private Implementierung geladen werden. Dazu muss im localStorage ein Key 'replace:resourceId' hinterlegt werden. Der Wert des Eintrags ist die Adresse, unter der die Ersatzimplementierung zu finden ist. Es kann sich dabei um einen Wiki-Artikel handeln (analog zu Benutzer:common.js) oder eine https-Adresse, aus der das Replacement zu laden ist.
Das Replacement wird als ECMAScript-Modul geladen. Es muss eine default-Funktion exportieren, die nach dem Laden des Replacements aufgerufen wird und das Replacement aktiviert. Wie das genau geschieht, hängt vom jeweiligen Modul ab. Beispiel: Das access_nav Modul steuert sich über eine Klasse AccessNav. Die Replacement-Funktion bekommt die Konstruktorfunktion dieser Klasse übergeben und kann sie nutzen, um eine von AccessNav abgeleitete Klasse zu erzeugen, die die Abläufe von AccessNav modifiziert. Das access_nav Modul erwartet, dass die exportierte Default-Funktion die Konstruktorfunktion dieser abgeleiteten Klasse zurückgibt.
Wichtige Helfer aus jQuery und Mediawiki
jQuery? Wie bitte? Ja. jQuery. Das ganze Mediawiki basiert heftig auf jQuery, und deshalb sollte man sich, sofern nötig, in die von jQuery vorgegebenen Abläufe einfügen.
Leider verwendet Mediawiki 1.29 noch jQuery 1, was ein paar Hindernisse bedeutet.
Warten auf Deferred Objekte
jQuery implementiert eine Vorversion der ECMAScript Promises, unter dem Namen "Deferred" Objekte. Ein Deferred-Objekt besitzt - analog zu Promises - then() und catch()-Methoden, aber eigentlich verwendet jQuery statt dessen done() und fail(). Auf einzelne Deferreds kann man mit .then oder .done warten, auf mehrere wartet man mit $.when(). Diese Methode erwartet 1-n Parameter. Sind es Deferred-Objekte, wird darauf gewartet, dass sie resolven und dann ihr Resolved-Wert weitergegeben. Andere Objekte werden 1:1 durchgereicht. Die then-Methode, die auf dem Ergebnis von $.when() aufgerufen werden muss, bekommt für jeden when-Parameter einen Parameter mit den Deferred-Ergebnis.
$.when(
$.ready,
$.getJSON( "ajax/test.json" )
)
.then(function(jq, json) { ... });
$.when bekam 2 Parameter, then bekommt sie deshalb auch. Ergebnis von $.ready ist das jQuery-Objekt.
Mischen von Deferred und Promise
jQuery 3 ist im Stande, ECMAScript-Promises wie Deferred-Objekte zu behandeln. In jQuery 1 ist das noch nicht der Fall, deshalb kann man ein normales Promise nicht an $.when() übergeben.
- Aber:** ECMAScript-Promises sind im Stande, jQuery-Deferred-Objekte wie Promises zu behandeln, zumindest was das Warten darauf angeht. Um auf eine Mischung aus Deferred und Promises zu warten, ist deshalb
Promise.all()
das Mittel der Wahl. Hier ist nur zu beachten, dass Promise.all ein Array mit Promises erwartet.
- Aber:** ECMAScript-Promises sind im Stande, jQuery-Deferred-Objekte wie Promises zu behandeln, zumindest was das Warten darauf angeht. Um auf eine Mischung aus Deferred und Promises zu warten, ist deshalb
Promise.all([
$.ready,
import('/skin/Selfhtml/foo.js')
])
.then(function(promises) {
const fooModul = promises[1];
});