Benutzer:PerfektesChaos/js/menuSwitcher/config

aus Wikipedia, der freien Enzyklopädie
Zur Navigation springen Zur Suche springen

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

[Bearbeiten | Quelltext bearbeiten]
  • 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

[Bearbeiten | Quelltext bearbeiten]

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

[Bearbeiten | Quelltext bearbeiten]

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

[Bearbeiten | Quelltext bearbeiten]

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

[Bearbeiten | Quelltext bearbeiten]

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

[Bearbeiten | Quelltext bearbeiten]

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

[Bearbeiten | Quelltext bearbeiten]

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

[Bearbeiten | Quelltext bearbeiten]

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

[Bearbeiten | Quelltext bearbeiten]

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

[Bearbeiten | Quelltext bearbeiten]

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

[Bearbeiten | Quelltext bearbeiten]

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

[Bearbeiten | Quelltext bearbeiten]

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.
Abgerufen von „https://de.wikipedia.org/w/index.php?title=Benutzer:PerfektesChaos/js/menuSwitcher/config&oldid=183178187“