Benutzer:PerfektesChaos/js/preferencesGadgetOptions

Skriptbibliothek mit JavaScript-Funktionen, um konfigurierbare Gadgets zu unterstützen.

Kernaufgabe ist ein interaktives Dialogformular, das einfach auf einer Spezialseite zu erstellen ist. Weitere Hilfsmittel unterstützen auch sonstige MediaWiki-Benutzereinstellungen.

Möglichkeiten

Die Speicherung der Informationen erfolgt mittels API auf dem MediaWiki-Server.

Um auf die gespeicherten Optionen zuzugreifen, wird die aktuelle Seite ausgewertet, die kürzlich abgerufen wurde. Gleichwohl könnte eine Einstellung zwischenzeitlich in einem anderen Browserfenster geändert worden sein.

Gadget-Konfiguration über Benutzeroberfläche

Aus den Formular-Informationen wird spontan eine Benutzeroberfläche (GUI) generiert. Wenn die Eingaben mit + bestätigt wurden, werden die letzten Benutzerwünsche als Benutzereinstellung gespeichert und können auf jeder anderen Wiki-Seite ausgewertet werden.

Benutzerskripte, die nicht als Projekt-Gadgets registeriert wurden, erhalten einen eigenen Abschnitt zu Beginn der Spezialseite.

Selbst wenn keine Konfiguration unterstützt wird, kann ein Link auf die Dokumentationsseite angezeigt werden, und die korrekte Installation und Verfügbarkeit wird durch den sichtbaren Eintrag bestätigt.

Typsichere Benutzeroptionen in JS

MediaWiki unterstützt zurzeit nur Zeichenketten zur als benutzerdefinierte Werte. Weil "false" bei Verzweigungen ein völlig anderes Verhalten bewirkt als false (und "null" ist nicht null noch ist "5"+7 das Gleiche wie 5+7), werden einzelne Werte abgerufen wie gespeichert.

Vollständige Sätze von Optionen eines Gadget werden mittels JSON gespeichert, wodurch der Datentp erhalten bleibt.

Benutzereinstellungen

Einige Hlfsfunktionen unterstützen bei MediaWiki Standard-Benutzereinstellungen:

• Zeichenkette setzen
• Aktualisierung

Nur Standard-Benutzereinstellungen, die Zeichenketten sind, können zugewiesen werden. Es sind dabei auch nur Werte möglich, die auf Special:Preferences ebenfalls gültig wären.

Aktualisierung

Es ist möglich, eine bestimmte Benutzereinstellung in der momentanen Seite zu aktualisieren. Die Seite könnte schon vor einiger Zeit abgerufen worden sein, aber inzwischen können in einem anderen Browser-Fenster die Einstellungen geändert worden sein. Bei kritischen Aktivitäten kann es sinnvoll sein, dies abzugleichen, um sich nicht irrtümlich wieder auf einen veralteten Stand zurückzusetzen..

Callback

Wenn der Wiki-Server kontaktiert werden muss, sind die Rückgabewerte der Funktionen nicht die endgültigen Antworten. Falls ein aktualisierter Wert vom Server abgerufen wird, kommt er erst etwas später an. Die Callback-Funktionen werden, sofern sie benannt wurden, nach Antwort des Servers ausgeführt. Gleichfalls sind sie einsetzbar zur Benachrichtigung über erfolgreiche Abspeicherung wie auch zur Benachrichtigung bei Fehlersituationen.

Benutzerdefinierter Optionsbereich

Zurzeit wird der folgende Komponentenbereich für nicht von MediaWiki-Extensionen belegte Einstellungen benutzt:

mw.user.options.values.userjs-gadgetID

Das könnte sich eines Tages ändern, vielleicht

mw.user.config.values.gadgetID

Das Skript verwaltet einen davon unabhängigen Zugriff auf diesen Speicherbereich, notfalls automatische Migration.

Datenmenge

• Jedes Mal, wenn ein Benutzer eine Wiki-Seite abfordert (nach Anmeldung), wird der gesamte Satz aller Optionen neu vom Server übertragen. Es erfolgt kein Caching im Speicher des lokalen Browsers.
• Zur besseren Handhabung und schnelleren Netzwerkübertragung gehört zu jedem Gadget nur ein Objekt mit dem vollständigen Optionssatz dazu.
  • Dies ist wesentlich effizienter als ein Gadget-Bezeichner kombiniert mit einem einzelen Optionsnamen für jeden Einzelwert als Einstellung abzuspeichern.
  • Es erlaubt auch eine einfache Kombination mit einem ganzen Satz an Vorgabewerten, modifiziert durch individuelle Benutzerwünsche.
• Die Menge an Daten, die mit jeder Seite übertragen wird, sollte klein gehalten werden. Dauerhafte Konfigurationsinformationen sollten in spezifische Seiten mit Konfigurationsskripten geschrieben werden, die im Browser Cache gehalten werden, oder können nach dem ersten Abruf im localStorage/sessionStorage (Web Storage) abgelegt werden.

Installation

Gadget-Programmierer müssen auf die ordnungsgemäße Installation dieses Skripts warten, bevor irgendeine Funktion benutzt werden kann. Das erfordert zwei Schritte.

Wenn die hier beschriebene Skriptbibliothek tatsächlich benötigt wird, ist frühzeitig in der Ausführung des Gadgets der Ladevorgang zu starten.

if ( ! mw.loader.getState( "ext.gadget.preferencesGadgetOptions" ) ) {
   mw.loader.state( { "ext.gadget.preferencesGadgetOptions": "loading" } );
   mw.loader.load( "https://en.wikipedia.org/w/index.php?title="
                   + "User:PerfektesChaos/js/"
                   + "preferencesGadgetOptions/r.js"
                   + "&action=raw&bcache=1&maxage=604800"
                   + "&ctype=text/javascript" );
}
mw.hook( "preferencesGadgetOptions.ready" ).add( gadgetMainTask );

Dieser Vorgang wäre nicht sinnvoll, wenn er bereits anderswo erfolgt war. Deshalb wird zunächst der state (Status) überprüft. Ein anderes Gadget, das ebenfalls die Skriptbibliothek verwendet, könnte das bereits vorgenommen haben. Um unnötige Parallelarbeit zu vermeiden, wird der state sofort auf "loading" gesetzt.

Eine Callback-Funktion (hier gadgetMainTask) wird aufgerufen, sobald die Skriptbibliothek geladen worden ist und die Ausführungsumgebung initialisiert wurde. Sie kann einen Parameter auswerten. Das ist das Anwendungsobjekt für die Skriptbibliothek. Es müsste mit mw.libs.preferencesGadgetOptions identisch sein, solange derartige Strukturen unterstützt werden.

Danach ist gadgetMainTask die wesentliche Funktionalität, die von den Benutzereinstellungen abhängt. Hilfsfunktionen aus dieser Skriptbibliothek sind innerhalb von gadgetMainTask verfügbar. Die in der aktuellen Wiki-Seite hinterlegten Benutzereinstellungen waren auch bereits wirksam geworden.

API

Nach Auslösen des mw.hook preferencesGadgetOptions.ready können Funktionen aufgerufen werden. Dabei ist der von mw.hook übergebene Parameter das Anwendungsobjekt und müsste mit mw.libs.preferencesGadgetOptions identisch sein.

Die Funktionen sind Komponenten des Anwendungsobjekts.

Übersicht

Funktion	Anwendungsbereich			Zweck
	Gadgets	UserJS	MediaWiki
.fetch()	×	–	–	Optionssatz abrufen
.form()				Dialogformular auf der Spezialseite für Gadgets
.forward()				Optionssatz abspeichern
.$button()				Einheitliches Schaltelement zum Öffnen der Spezialseite
.get()	–	×	–	Einzelne benutzerdefinierte Option typsicher abrufen
.put()				Einzelne benutzerdefinierte Option typsicher abspeichern
.remove()	×	×	–	Benutzerdefinierten Eintrag aus den Benutzereinstellungen löschen
.string()	–	–	×	MediaWiki-Einstellung als Zeichenkette speichern
.update()				Wert einer MediaWiki-Einstellung aktualisieren

.fetch()

Abrufen eines „Gadgets“-Optionssatzes, der zuvor gespeichert wurde mit .form() oder .forward().

Aufruf	.fetch(assign, assume, again, aborted)
Parameter	Type	Bedeutung
assign	string	Gadget-ID
assume	object	object – Vorgabewerte, falls keine Optionen abrufbar oder einzelne Komponenten nicht definiert; bleibt unverändert undefined, null, false – keine Vorgabewerte
again	function boolean	Aktualisiere Wert vom Server function – Callback-Funktion, wenn aktualisiert true – einfach auffrischen undefined, false – nicht vom Server aktualisieren
aborted	function	Fehler beim Update-Versuch again. function – Callback function, wenn vom Server abgelehnt undefined, false – keine Benachrichtigung
Rückgabewert		object wie momentan in der Seite oder assume; kann null sein

.form()

Zeige ein Gadget auf einer Spezialseite an: Eintrag, Link auf Dokumentationsseite, Konfigurationsdialog (sofern vorhanden) öffnen. Wenn bereits mittels MediaWiki:Gadgets-definition vereinbart, wird nur ein Button zum Formular hinzugefügt, falls es konfigurierbare Optionen gibt.

Aufruf	.form(about)
Parameter	Type	Bedeutung
about	object	Gadget-Beschreibung, siehe unten.

.forward()

Speichere einen „Gadgets“-Optionssatz.

Aufruf	.forward(assign, apply, after, aborted)
Parameter	Type	Bedeutung
assign	string	Gadget-ID
apply	object	Zuweisungen key:value wie gewünscht.
after	function boolean	Speichern erfolgreich. function – Callback-Funktion, wenn abgeschlossen undefined, false – keine Benachrichtigung
aborted	function	Fehler beim Speichern. function – Callback function, wenn Aktualisierung fehlgeschlagen undefined, false – keine Benachrichtigung
Rückgabewert		false wenn gültig, oder Meldung bei Parameterfehler

.$button()

Schaltknopf als jQuery-Objekt im einheitlichen Design, der die einer Spezialseite in einem neuen Browser-Fenster öffnet.

Aufruf	.$button()
Rückgabewert		jQuery-Objekt mit Schaltknopf

.get()

Hole den typensicheren Wert einer USERJS-Option, der mit .put() gespeichert wurde.

Aufruf	.get(assign, assume, again, abort)
Parameter	Type	Bedeutung
assign	string	Gadget-ID.
assume	irgendwas optional	Vorgabewert, falls keine Option abrufbar oder nicht definiert.
again	function boolean	Aktualisiere Wert vom Server. function – Callback-Funktion, wenn aktualisiert true – einfach auffrischen undefined, false – nicht vom Server aktualisieren
aborted	function	Fehler beim Update-Versuch again. function – Callback function, wenn vom Server abgelehnt. undefined, false – keine Benachrichtigung
Rückgabewert		Wert beliebigen Typs, sonst assume

.put()

Speichere den typensicheren Wert einer USERJS-Option, um ihn später mit .get() abzurufen.

Aufruf	.put(assign, apply, after, aborted)
Parameter	Type	Bedeutung
assign	string	Gadget-ID.
apply	irgendwas	Wert der gespeichert werden soll.
after	function	Speichern erfolgreich. function – callback function, wenn abgeschlossen undefined, false – keine Benachrichtigung
aborted	function	Fehler beim Speichern. function – Callback function, wenn vom Server abgelehnt undefined, false – keine Benachrichtigung
Rückgabewert		false wenn gültig, oder Meldung bei Parameterfehler

.remove()

Lösche eine Benutzer-Option.

Aufruf	.remove(assign, after, aborted)
Parameter	Type	Bedeutung
assign	string	Options-ID.
after	function	Löschen ausgeführt. function – Callback-Funktion, wenn abgeschlossen undefined, false – keine Benachrichtigung
aborted	function	Fehler beim Löschen. function – Callback-Funktion, wenn Löschung fehlgeschlagen undefined, false – keine Benachrichtigung
Rückgabewert		false wenn gültig, oder Meldung bei Parameterfehler

.string()

Speichere den Zeichenketten-Wert einer MEDIAWIKI-Option.

Aufruf	.string(assign, apply, after, aborted)
Parameter	Type	Bedeutung
assign	string	Name einer MediaWiki-Option, die eine Zeichenkette ist.
apply	string	value
after	function	Speichern erfolgreich. function – Callback-Funktion, wenn aktualisiert undefined, false – keine Benachrichtigung
aborted	function	Fehler beim Speichern. function – Callback-Funktion, wenn vom Server abgelehnt undefined, false – keine Benachrichtigung
Rückgabewert		false wenn gültig, oder Meldung bei Parameterfehler

.update()

Aktualisiere den Wert einer MEDIAWIKI-Option.

Aufruf	.update(assign, after, aborted)
Parameter	Type	Bedeutung
assign	string	Name einer MediaWiki-Option.
after	function	Synchronisation ausgeführt. function – Callback-Funktion, wenn abgefragt undefined, false – keine Benachrichtigung
aborted	function	Fehler beim Synchronisieren function – Callback-Funktion, wenn Abfrage fehlgeschlagen undefined, false – keine Benachrichtigung
Return value Rückgabewert		false wenn gültig, oder Meldung bei Parameterfehler

Benutzeroberfläche auf einer Spezialseite

Durch Benutzer wie auch das Projekt angeforderte Gadgets können auf einer Spezialseite Werbung machen und weiter konfiguriert werden.

• Jedes Benutzerskript kann dort auf seine Dokumentationsseite verlinken.

Falls about.opts spezifiziert ist, wird am Schluss des Eintrags der Schaltknopf zum Öffnen des Formulars gezeigt, das wieder geschlossen werden kann.

• Das Formular endet mit einem Schaltknopf + – dadurch wird die Aktualisierung der Optionen in der Spezialseite und das Abspeichern als Benutzereinstellung veranlasst.

• Bis Herbst war 2016 Special:Gadgets zusammen mit den projektweit unterstützten Gadgets benutzt worden.
  • Hier fiel jedoch die Ausführung von JavaScript weg.
• Seitdem wird Special:Blankpage/preferencesGadgetOptions verwendet.

Von den folgenden Komponenten sind alle außer .script optional; aber etwas mehr als der Gadget-Bezeichner würde den Eintrag sinnvoll aussehen lassen und Funktionalität bieten.

about object in .form()

Komponente	Type	Bedeutung
.script	string	Erforderliche Gadget-ID.
.suite	string	ID in MediaWiki:Gadgets-definition. .script wenn nicht definiert
.show	string	Angezeigter Name des Helferleins. .script wenn nicht definiert
.support	string	URL der Helferlein-Dokumentationsseite. "/wiki/User:PerfektesChaos/js/preferencesGadgetOptions"
.suffix	string	Weitere Erläuterung des Helferleins (weiß der Opt-In-Benutzer aber ohnehin). Wird dem Namen .show des Helferleins nachgestellt.
.fiat	function	Funktion, die nach Ausstattung der .opts aufgerufen wird. In .opts sind dann alle jQuery-Objekte der controls .$checkbox .$item .$text enthalten und können mit untereinander verknüpften on-Funktionen komplexe wechselseitige Beziehungen definieren. Sie erhält als ersten Parameter das Objekt about und als zweiten das jQuery-Objekt des Submit-Buttons +. this ist dieses Objekt about.
.filled	function	Funktion, die nach Submit + als Argument das geänderte oder unveränderte Objekt der gespeicherten Optionen erhält. Sie erhält als ersten Parameter das Objekt about und als zweiten das Objekt mit allen Werten. this ist dieses Objekt about.
.fed	function	Callback Funktion, die nach dem erfolgreichen Speichern auf dem Server aufgerufen wird.
.failure	function	Callback Funktion, die aufgerufen wird, wenn das Speichern auf dem Server fehlgeschlagen war.
.opts	Array	Konfigurierbare Optionen. Jedes Element ist ein object und beschreibt eine Option. Jedes Element hat zwei Pflichtkomponenten: .signature und .type – die sinnvollerweise von inhaltlicher Ausgestaltung zu begleiten wären. Format für jedes Element siehe folgende Tabelle.

Array about.opts element

Komponente	Type	Bedeutung
.signature	string	Erforderliche Options-ID.
.type	string	Erforderlicher Typ der Option; einer von checkbox – einzelnes Kästchen zum Ankreuzen radio – Abfolge von Radio Buttons; Array .poly erforderlich multi – Abfolge von Ankreuzkästchen, multiple choice; Array .poly erforderlich text – einzelne Textzeile.
.show	string	Optionsbeschreibung.
.val	any	Vorgabewert, und momentane Wahl
.poly	Array	Definition eines Mehrfach-Schaltelements (nur .type=radio|multi). Jedes Element des Arrays ist ein object mit zwei Komponenten: .val – beliebiger Datentyp und Inhalt; wird zugewiesen, wenn ausgewählt .show – string mit Beschreibung Für den .type=multi ist der resultierende Optionswert .val ein Array der einzelnen Elemente .poly[.val,.val] und ansonsten der Wert des angewählten .type=radio Schaltelements.
.suffix	string	Nur .type=text (optional) Dem Eingabefeld nachgestellte Beschreibung. Kann als vollständiges HTML-Element angegeben werden, oder plain text.
.minimum	number	Nur .type=text (optional) Dargestellte Länge des Eingabefeldes in Zeichen
.maxlength	number	Nur .type=text (optional) Maximal erlaubte Länge der Eingabe in Zeichen
.ime	boolean	Nur .type=text (optional) true – IME erlauben
.field	function	Nur .type=text (optional) Funktion, die als Argument das jQuery-Objekt des Textfeldes erhält. Dies lässt sich mit on-Funktionen ausstatten und mag abhängige Hintergrundfarbe setzen. this ist diese Text-Option.
.$checkbox .$item .$text	object	jQuery-Objekt, das durch dieses Skript generiert wird nach dem ersten Öffnen des Formulars.

Callback-Funktion

Nach Abschluss einer Aktion auf dem Wiki-Server meldet sich eine benutzerdefinierte Rückruf-Funktion, falls gewünscht. Es gilt jeweils:

• Sie wird mit einem Parameter aufgerufen:
  • Bei der Funktion für erfolgreiche Ausführung ist das ein Objekt, dessen Komponente options den Wert "success" enthält.
  • Die Funktion für den Fehlerfall erhält eine Zeichenkette mit einer bestmöglichen Beschreibung.
• this ist das Anwendungsobjekt mw.libs.preferencesGadgetOptions.

Synchronisation

Für empfindliche Operationen könnte es wichtig sein, dass die Konfiguration nicht in einem anderen Browser-Fenster verändert worden ist, seit die aktuelle Seite angezeigt wurde. Durch die angebotenen Aktualisierungsfunktionen und Callback-Funktionen kann gesichert werden, dass eine Aktion nicht ausgeführt wird, bevor der allerneueste Status berücksichtigt wurde.

Konfiguration der Spezialseite

Auf Ebene des gesamten Wiki-Projekts kann die Standard-Umgestaltung von den Projektverantwortlichen beeinflusst werden; namentlich durch MediaWiki:Common.js vorab definiert.

Die Verwendung durch Gadgets ist ausdrücklich nicht erwünscht und könnte vom Projektmanagement als missbräuchlich angesehen werden.

Der nachstehende Code passt die Gestaltung an:

if ( mw.config.get( "wgCanonicalSpecialPageName" )  ===  "Gadgets" ) {
   mw.libs.preferencesGadgetOptions.config = {
      $sectionUser: $( ... ),
      $btnOpts:     $( ... ),
      ...
                                             };
}

Optionale Komponenten in .config

jQuery-Objekte
.$sectionUser	Wrapper für den Abschnitt zu benutzerdefinierten Skripten. <div id="preferencesGadgetOptions-user"> Einschließlich: Überschrift (H2) Rahmen etc. zur Unterscheidung von den MediaWiki-Abschnitten Auf Wunsch einleitende Bemerkungen zum Abschnitt An den Wrapper angehängt wird nur noch eine <ul> mit der Liste benutzerdefinierter Skripte.
.$optsForm	<div> für jedes einzelne Optionsformular.
.$btnOpts	Schaltfläche <button> für das Öffnen eines Optionsformulars.
.$btnSubmit	Schaltfläche <button> für das Übertragen des Optionssatzes.
.$btnClose	Schaltfläche <button> für das Schließen des Optionsformulars.
.$throbber	Grafik <img> für die laufende API-Kommunikation.
.$stored	Grafik <img> für die Bestätigung der erfolgreichen Speicherung.
.$denied	Grafik <img> für die fehlgeschlagene Speicherung.

Standard-Stil:

div.preferencesGadgetOptions-optsForm {
   border:  solid 1px #80FFFF;
   margin:  .5em;
   padding: .5em;
}
div#preferencesGadgetOptions-user {
   border:  solid 2px #80FFFF;
   margin:  1em;
   padding: 1em;
}

Code und Stammseite

Die Stammseite ist en:User:PerfektesChaos/js/preferencesGadgetOptions mit:

Quellcode	JavaScript – Komprimierter Code zum Laden Kommentiertes Skript – zum Lesen durch Menschen und Debuggen
ResourceLoader	ext.gadget.preferencesGadgetOptions Dependencies: user.options
Namensräume	-1   (Blankpage) Jede Seite, die für das anwendende Gadget interessant ist.
mw.libs	preferencesGadgetOptions
mw.hook	preferencesGadgetOptions.ready Bibliothek initialisiert; in der aktuellen Wiki-Seite hinterlegte Benutzereinstellungen wirksam geworden.

Bekannte Anwendungen

• browserStorageManager
• citoidWikitext
• clickDivertimento
• editMenusPREGO
• externalLinkProblem
• filesMetaData
• idResolver
• keyboardMapper
• lintHint
• listPageOptions
• loadResourceFile
• paneMarker
• resultListSort
• WikiSyntaxTextMod