Wikipedia

Benutzer:PerfektesChaos/js/preferencesGadgetOptions

< Benutzer:PerfektesChaos‎ | js

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 Bearbeiten

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 Bearbeiten

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 Bearbeiten

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 Bearbeiten

Einige Hlfsfunktionen unterstützen bei MediaWiki Standard-Benutzereinstellungen:

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 Bearbeiten

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 Bearbeiten

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 Bearbeiten

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 Bearbeiten

  • 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 Bearbeiten

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 Bearbeiten

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() Bearbeiten

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() Bearbeiten

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() Bearbeiten

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() Bearbeiten

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() Bearbeiten

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() Bearbeiten

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() Bearbeiten

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() Bearbeiten

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() Bearbeiten

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 Bearbeiten

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.

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 Bearbeiten

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 Bearbeiten

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 Bearbeiten

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 Bearbeiten

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

Quellcode
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 Bearbeiten

Abgerufen von „https://de.wikipedia.org/w/index.php?title=Benutzer:PerfektesChaos/js/preferencesGadgetOptions&oldid=182934389“