Benutzer:PerfektesChaos/js/menuSwitcher/config

Hier werden JavaScript-Anweisungen dargestellt, die für die Bereitstellung und Konfiguration von menuSwitcher benötigt werden.

Benutzer müssten die Zeilen in die persönliche common.js, global.js etc. einfügen.

Auf Ebene des Wiki-Projekts sind andere Seiten maßgeblich.

Einbindung

• Wenn das Projekt dieses Gadget registriert haben sollte, bzw. eine Kopie vorhält, ist folgende Anweisung auszuführen:

mw.loader.load( "ext.gadget.menuSwitcher" );

• Sonst wäre die folgenden Zeile einzufügen:

mw.loader.load( "https://en.wikipedia.org/w/index.php?title=User:PerfektesChaos/js/menuSwitcher/r.js&action=raw&bcache=1&maxage=604800&ctype=text/javascript" );

Mehr JavaScript-Anweisungen werden aber ohnehin benötigt, die an einem der beschriebenen Orte einzufügen sind.

Ein mw.hook mit der Kennung ext.gadget.menuSwitcher.ready wird ausgelöst, wenn die Initialisierung abgeschlossen ist. Als Parameter wird eine Kurzinformation über Version und Status übermittelt.

Die Einbindung sollte möglichst spät erfolgen, nachdem zuvor alle Konfigurationsereignisse ausgelöst wurden.

Konfigurationsereignis

Ein mw.hook mit der Kennung ext.gadget.menuSwitcherg.config kann beliebig oft von interessierter Seite (Projekt oder einzelne Benutzer) ausgelöst werden, um die bisherigen Wünsche zu erweitern.

Beispiel; mit einem privaten Objekt meineMenuS:

mw.hook( "ext.gadget.menuSwitcher.config" ).fire( meineMenuS );

Sofern nicht ausdrücklich anders angegeben, wirken auch spätere Anforderungen noch auf die bisherige Darstellung.

Der Anforderung ist ein Parameter mit der Spezifikation mitzugeben:

Datentyp	Bedeutung
boolean	false – Darstellung komplett ausblenden true (Vorgabe) – sobald möglich darstellen Identisch mit der Komponente .live im Konfigurationsobjekt.
object	Konfigurationsobjekt

Hier wie auch bei allen Einzeldaten werden ungültige Angaben stillschweigend ignoriert. Eine Fehlermeldung erfolgt aus Performance-Gründen nicht.

Konfigurationsobjekt

Es wird einem Konfigurationsereignis mitgegeben und kann die folgenden optionalen Komponenten haben:

Komponente	Datentyp	Bedeutung
.css	object	CSS-Zuweisungen zur Gestaltung des gesamten Menü-Blocks
.defs	object	Werkzeuggruppen
.help	boolean string object	kontextsensitive Hilfe
.hide	boolean object	Ein- und Ausblenden
.live	boolean	siehe oben
.position	Array	Positionierung
.select	string	Bezeichner einer (initial) auszuwählenden Werkzeuggruppe
.top	Array	Reihenfolge im Auswahlelement
.client	object	Konfiguration für besondere, nicht mehr offiziell unterstützte Browser

Positionierung

Die Anordnung einer oder mehrerer Werkzeugzusammenstellungen erfolgt relativ zu entsprechenden in der Seite permanent enthaltenen Elementen.

Die Bezugselemente sind durch einen Selektorausdruck zu spezifizieren.

• Der Selektorausdruck kann durch Kommata mehrere Elementselektoren aufreihen.
• Durch :first oder :last können mehrfache Treffer einer Klasse wieder reduziert werden.
• Beispiel: textarea:enabled:first,input:text:enabled trifft das erste mehrzeilige Texteingabefeld sowie alle einzeiligen Texteingabefelder, die Eingaben annehmen würden.

Es ist möglich, eine Kaskade von Selektorausdrücken zu verwenden.

• Die Selektorausdrücke werden nacheinander ausprobiert.
• Gibt es keinen Treffer, so wird der nächstfolgende Ausdruck versucht; andernfalls die Abarbeitung der Kaskade beendet.
• Damit lässt sich auf das individuelle Vorhandensein anderer Werkzeugleisten usw. reagieren.
• Die Kaskade wird durch ein Array aus Zeichenketten oder komplexeren Objekten gebildet.

Die Konfiguration sollte möglichst bereits erfolgen, bevor das Dokument dargestellt ist, und parallel dazu ausgewertet werden.

• Zu diesem Zeitpunkt sind die Elemente im DOM noch nicht bekannt, und es können nur die Selektorausdrücke vorgegeben werden.
• Sollte die Aktivierung erst später erfolgen, kann anstelle des Selektorausdrucks ein jQuery-Objekt angegeben werden, das dann Vorrang hat.

Die Positionierung wird ein einziges Mal nach Aufbau des DOM vorgenommen (sobald auch live gegeben ist) und kann dann nachträglich nicht mehr verändert werden.

Die Positionierung erfolgt in der Komponente .position des Konfigurationsobjekts und muss ein Array sein. Für jedes Element des Array muss gelten:

Datentyp	Bedeutung
string	Selektorausdruck (Einfügung unterhalb dieses Bezugselements)
object	Erweitert, mit den optionalen Komponenten: Komponente Datentyp Bedeutung .jQuery object Bezugselement(e) (statt .selector) .last boolean Verhältnis zu anderen (bisherigen) Positionierungen in der Kaskade: true – nachrangig false (Vorgabe) – vorrangig .lead boolean Anordnung zu all diesen Bezugselementen: true – oberhalb false (Vorgabe) – unterhalb .selector string Selektorausdruck für Bezugselement(e)

Ein mw.hook mit der Kennung ext.gadget.menuSwitcher.created wird ausgelöst, nachdem die Seite mit Zusammenstellungen ausgestattet wurde. Als Parameter wird ein jQuery-Objekt mit den generierten Containern übermittelt.

Die Container erhalten jeweils class="menuSwitcher".

Werkzeuggruppen

In der Komponente .defs des Konfigurationsobjekts können die Werkzeuggruppen („Panels“) in unterschiedlichen Spezifikationsformaten angefordert werden.

Die Komponente muss ein object sein und kann folgene Komponenten enthalten, wobei contentmodel, system und create Pflichtangaben sind:

Komponente	Datentyp	Bedeutung
.contentmodel	boolean string Array	Beschränkung auf bestimmtes Seiteninhaltsmodell boolean true – Alle Seiteninhaltsmodelle false (Vorgabe) – Kein Seiteninhaltsmodell string Schlüsselwort für Seiteninhaltsmodell, etwa wikitext, das mit der aktuellen Seite übereinstimmen muss. Spezialseiten gelten als Wikitext. Array Liste von geeigneten Schlüsselwörtern, von denen eines übereinstimmen muss.
.create	object (auch Array)	Spezifikation im Format system
.last	boolean	true – Die Angaben sollen zum Schluss der Auswahlliste angeordnet werden. Damit können projektweite Vorgaben den individuellen Benutzerwünschen nachgeordnet werden, unabhängig vom Zeitpunkt des Konfigurationsereignisses. false (Vorgabe) – Spezifikation an führender Stelle anordnen.
.system	string	Spezifikationsformat. Eine der bekannten Angaben: builtin – Generisches Format; ermöglicht alle Features. charinsert – Übernahme bereits in der Seite vorhandener HTML-Elemente. stringArrays – Kompakte Notation, vor allem für viele Einzelbuchstaben gut geeignet. stringArrayObject – Nicht empfehlenswertes Format, ähnlich stringArrays, jedoch Anordnung nicht in einem Array, so dass die Reihenfolge nicht gesichert ist.

Mehrfache Konfigurationsereignisse nacheinander können Werkzeuggruppen zuliefern, die nach unterschiedlichem system organisiert sind.

builtin

Möglicher Inhalt der Komponente create.

Ein Array, bei dem jedes Element ein object ist und eine Werkzeuggruppe („Panel“) bildet. Die Reihenfolge wird im Auswahlelement reflektiert.

Jedes einzelne Werkzeuggruppen-object kann folgende Komponenten enthalten, wobei selector und def Pflichtangaben sind:

Komponente	Datentyp	Bedeutung
.class	string	Zusätzliche Klassen.
.contentmodel	boolean string Array	Seiteninhaltsmodell, siehe oben
.def	Array	mit den Einzelelementen als object; siehe unten
.lang	string	Sprachcode; kann sprachspezifische Formatierungen auslösen.
.selector	string	Text im Auswahlelement
.style	string	CSS-Eigenschaften
.support	string	Tooltip
.last	boolean	nachrangig anordnen, siehe oben
.low	boolean	low level Syntaxelemente; dieses Panel wird nur bei Quelltextbearbeitung gezeigt.

Jedes Einzelelement im Array .def muss ein object sein. Jedes ist einem von zwei Typen zuzuordnen:

• Link (aktiv)
• Passiv (dekorativ),

Zwischen aktiven Elementen wird ein normales Leerzeichen angeordnet.

Das object für ein Einzelelement kann folgende Komponenten enthalten:

Komponente	Datentyp	Bedeutung
.class	string	Zusätzliche Klassen.
.contentmodel	boolean string Array	Seiteninhaltsmodell, siehe oben
.fun	function	Funktion, die aufgerufen wird.
.sample	string	Text, wird eingefügt, falls nichts selektiert ist.
.show	string	Elementbeschriftung Bei aktiven Elementen einfacher Text, sonst HTML-Code. Vorgabe: Komposition aus .start und .suffix usw.
.src	string	URL eines Icons zur (zusätzlichen) Linkbeschriftung. Kann nur relativ in der Domain der Seite oder in eines der großen WMF-Wikis verweisen. Das Bild muss bereits die richtigen Dimensionen aufweisen.
.start	string	Text, wird vor der Cursorposition eingefügt.
.style	string	CSS-Code zur Formatierung
.suffix	string	Text, wird nach der aktuellen Selektierung eingefügt.
.support	string	Tooltip.

Benutzerdefinierte Funktion

• .show oder .src werden zur Beschriftung benötigt.
• Die sonstigen Definitionen zur Texteinfügung werden ignoriert.
• Die Funktion wird mit folgenden Parametern aufgerufen:
  1. Definition des Einzelelements
     • Enthält auch eine fortlaufend über alle Einzelelemente nummerierte Komponente id.
     • Benutzerdefinierte Komponenten können zur Steuerung der Funktionalität eingearbeitet werden.
  2. DOM Event.
  3. jQuery-Objekt der aktuellen Texteingabe, falls Formular; false beim VisualEditor.
  4. Surface Model beim VisualEditor.
• Wenn die Funktion eine Zeichenkette zurückgibt, wird der selektierte Bereich dadurch überschrieben.

charinsert

Möglicher Inhalt der Komponente create.

Ein object mit zwei Komponenten:

Komponente	Datentyp	Bedeutung
.selector	string	Selektor für die gesamte Zusammenstellung.
.segments	string	Geeigneter Selektorausdruck, der innerhalb der gesamten Zusammenstellung die Elemente der einzelnen Werkzeuggruppen identifiziert.

In jedem Element für eine Werkzeuggruppe wird ein HTML-Attribut title erwartet, das als Beschriftungstext im Auswahlelement dienen soll.

stringArrays

Möglicher Inhalt der Komponente create.

Ein Array, bei dem jedes Element ein Array aus zwei Elementen ist und eine Werkzeuggruppe (Panel) bildet:

Element	Datentyp	Bedeutung
[0]	string	Beschriftungstext im Auswahlelement
[1]	Array	aus Elementen folgender Spezifikation: Allererstes Element wahlweise Datentyp Bedeutung object mit besonderen Eigenschaften der Werkzeuggruppe: Element Datentyp Bedeutung .class string Zusätzliche Klassen. .font-size string CSS-Angabe. .lang string Sprachcode; kann sprachspezifische Formatierungen auslösen. Array wie alle weiteren Elemente. Reguläre Elemente sind Arrays. Jedes dieser Arrays stellt eine Untergruppe dar. Zwei Untergruppen werden durch einen Separator optisch getrennt. Für jedes Element der Untergruppen-Arrays gilt eines der Formate: Datentyp Bedeutung string Einzelzeichen/Text, wird vor der Cursorposition eingefügt. Array mit den optionalen string-Elementen: [0] – Text, wird vor der Cursorposition eingefügt. [1] – Text, wird nach der aktuellen Selektierung eingefügt. [2] – Text, wird eingefügt, falls nichts selektiert ist. [3] – Tooltip.

stringArrayObject

Möglicher Inhalt der Komponente create.

Ein object, bei dem die Namen der Komponenten die Beschriftungen im Auswahlelement darstellen.

• Der Wert der Komponente ist ein Array, dessen Aufbau dem Format stringArrays entspricht; also dessen jeweiliger Komponente [1].

Der Speicherverwaltung ist es überlassen, in welcher Reihenfolge auf die Komponenten zugegiffen wird. Deshalb ist es nicht garantiert, dass die Reihenfolge der Definitionen mit der Reihenfolge im Auswahlelement übereistimmt.

Dieses Format wurde ein Jahrzehnt in der deutschsprachigen Wikipedia verwendet.

Ein- und Ausblenden

Auf Wunsch kann jede Zusammenstellung mit einem Button zum Minimieren und Expandieren ausgestattet werden.

Es gibt zwei Modi:

1. Die Zusammenstellung wird auf das Auswahlelement minimiert.
   • Zur Reaktivierung kann das Auswahlelement angeklickt oder daraus eine Werkzeuggruppe gewählt werden.
2. Die Zusammenstellung wird völlig ausgeblendet.
   • Die Reaktivierung muss selbst organisiert werden.
   • Ein Button in einer anderen Werkzeugleiste würde sich anbieten.
   • Es genügt ein Konfigurationsereignis mit dem Wert true.

Die Anforderung erfolgt in der Komponente .hide des Konfigurationsobjekts und kann nach Generierung nicht mehr durch diese Konfiguration völlig zurückgenommen, jedoch umgestaltet oder ausgeblendet werden.

Für die Komponente .hide muss gelten:

Datentyp	Bedeutung
boolean	true – Modus 1 (minimieren/expandieren) false – keine Wirkung
object	Erweitert, mit den optionalen Komponenten: Komponente Datentyp Bedeutung .class string Zusätzliche Klassen für den Button. .css object (Vollständige) Zuweisungen an CSS-Eigenschaften des Button. Vorgabe ist ein weißes X auf rotem Grund. .mode number Modus: 0 – Kein Ein- und Ausblenden 1 – Minimieren: Beim Ausblenden verbleibt Panel-Auswahl. Einblenden mittels Panel-Auswahl. 2 – Ausblenden komplett. Einblenden durch anwenderseitiges Konfigurationsereignis. .show string Beschriftung des Buttons. Vorgabe ist ein X. .support string Tooltip zum Button. Vorgabe ist „Hide“.

Reihenfolge im Auswahlelement

Für die Komponente .top muss gelten:

Datentyp

Bedeutung

Array

Jedes Element ist eine Zeichenkette. Jede Zeichenkette benennt einen möglichen Bezeichner einer Werkzeuggruppe. Nicht existierende Bezeichner, die vorsorglich einsortiert wären oder nur manchmal vorhanden sind, wären unschädlich und würden ignoriert. Die Elemente werden der Reihe nach zu Beginn eingefügt; das zuletzt übermittelte Element der Liste bildet also anschließend den Anfang der Auswahl-Liste. Bisher weiter hinten in der Auswahl erschienene Optionen fallen im Gegenzug weg.

Diese Zuweisung kann beliebig wiederholt werden.

Technische Hinweise

Die Programmierung folgt einem lazy-Prinzip. Das bedeutet:

• HTML-Elemente werden so spät wie mögich generiert und in das HTML-Dokument eingefügt.
• Eine Werkzeuggruppe wird erst dann generiert, wenn sie erstmalig angezeigt werden soll.
• Nachfolgend werden generierte Elemente nur noch ein- und ausgeblendet.
• Sendet man zu Beginn der Konfiguration ein live=false, dann werden die Konfigurationsinformationen nur gesammelt und strukturiert, aber noch kein einziges HTML-Element generiert.
• Übergibt man in JavaScript ein Objekt, dann wird nur ein Pointer auf Speicherplatz übermittelt und ggf. gespeichert. Kopiervorgänge erfolgen nicht.