Hilfe:SELFHTML-API

Im Rahmen der Makeover-Erzeugung ist ein kleines API entstanden, das auf dieser Seite beschrieben werden soll.

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 oder debug: Protokollieren, dass die genannte resourceId geladen wurde
• debug: Ausführen von debugger;. Bei aktiven Entwicklertools hält das Script dann an.

Beispiel

   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.

jQuery $.when()

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

jQuery Deferred und Promise.all()

Promise.all([
   $.ready, 
   import('/skin/Selfhtml/foo.js') 
])
.then(function(promises) {
   const fooModul = promises[1];
});