Benutzer:Schnark/js/templateEditor

Das Skript templateEditor.js stellt anderen Skripten (etwa Benutzer:Schnark/js/personendaten.js und Benutzer:Schnark/js/personendaten.js/normdaten.js) Funktionen zur Verfügung um Bearbeitungen durch einfache Formulare zu ermöglichen. Weitere Beispiele für die Verwendung finden sich in den QUnit-Tests unter Benutzer:Schnark/js/templateEditor.js/test.js.

Verwendung Bearbeiten

Skript laden Bearbeiten

Vor Benutzung muss das Skript natürlich erst geladen werden, was man entweder dem Benutzer überlässt, oder selbst im Skript macht. Letztendlich steht es unter mw.libs.templateEditor zur Verfügung.

Registrieren Bearbeiten

Die Funktion mw.libs.templateEditor wird zum Registrieren verwendet. Sie wird mit den Parametern id (einem String, der das aufrufende Skript kennzeichnet, am besten dessen Seitentitel), short (einem String, der der Version vorangestellt wird, eine möglichst kurze Abkürzung am besten in Kleinbuchstaben des aufrufenden Skripts), version (der Versionsnummer, entweder als Zahl oder String) und hooks aufgerufen. Der letzte Parameter ist dabei ein Objekt aus optionalen Funktionen (onStart, onReady und onFinish), die zur rechten Zeit aufgerufen werden. Zurückgegeben wird etweder false (im Fehlerfall) oder ein Objekt mit nützlichen Funktionen (siehe unten).

Anschließend sollte man dem Benutzer die Möglichkeit geben, irgendwie zu starten, oder von selbst starten, oder eventuell einfach abwarten.

Starten Bearbeiten

Entweder man startet selbst, indem man die zurückgegebene Funktion start aufruft. Diese erwartet einen Parameter, ein Objekt, dessen Inhalt das weitere Verhalten etwas steuert: headline gibt die Überschrift des Bearbeiten-Formulars an. Setzt man redirect auf false, so wird bei einer Weiterleitung nicht der Zielartikel angezeigt. Soll das Formular an einer bestimmten Stelle stehen, so kann man mit $ eine jQuery-Instanz angeben, die dann damit gefüllt wird (sonst unter dem Titel). order gibt die Reihenfolge an, in der mehrere Nutzer von templateEditor.js beachtet werden sollen (siehe unten). Andere Daten können nach Belieben angegeben werden.

Die andere Möglichkeit ist, dass ein anderer Nutzer startet. In diesem Fall wird der Hook onStart mit einem Objekt aufgerufen, das unter id das startende Skript und unter data dessen übergebene Daten enthält. Zurückgeben sollte man entweder 0, wenn man nicht mit diesem Skript zusammen starten möchte oder eine von 0 verschiedene Zahl um ebenfalls zu starten. Für den weiteren Verlauf werden die Skripte in der Reihenfolge beachtet, die durch diese Zahlen angegeben wird, je größer, desto später.

In beiden Fällen sollte man dem Benutzer die Möglichkeit nehmen, einen weiteren Start auszulösen, das würde ohnehin zu keinem Erfolg führen.

Aufbauen Bearbeiten

Sobald der Hook onReady aufgerufen wird, kann man den Text parsen, das Formular aufbauen und mit Vorschlägen füllen (siehe unten).

Abbauen Bearbeiten

Sobald der Hook onFinish aufgerufen wird, sollte man die Daten aus dem Formular auslesen, den Text entsprechend ändern und Bearbeitungskommentare setzen.

Funktionen Bearbeiten

Von der bereits erwähnten Funktion start abgesehen, werdem beim Registrieren folgende Funktionen zurückgegeben:

getFunctions Bearbeiten

Liefert sämtliche Funktionen für ein anderes Skript, dessen Name man als Parameter übergibt, oder false. Dies ist notwendig, wenn man Formularfelder anderer Skripte auslesen will.

getVersion Bearbeiten

Liefert die Versionsnummer. Was genau zurückgegeben wird, hängt vom übergebenen Parameter ab:

Parameter	Rückgabe
`undefined`	Versionsnummer von `templateEditor.js`
`false`	Versionsstring aus allen registrierten Skripten
`true`	Versionsstring aus allen aktiven Skripten
id	Versionsnummer des angegebenen Skripts bzw. `null`

addInput Bearbeiten

Fügt ein Eingabeelement zum Formular hinzu. Erster Parameter ist dessen Name, zweiter ein Objekt mit folgenden optionalen Eigenschaften:

Parameter	Werte	Standard	Bedeutung
`text`	String	Leerstring	Beschriftung des Feldes
`type`	`'text'` oder `'bool'`	`'text'`	Art des Feldes: Texteingabe oder Kontrollkästchen
`autofill`	boolesch	`false`	Vorschlag bei leerem Feld direkt übernehmen?
`autocorr`	Funktion		automatische Korrektur sowohl beim Befüllen als auch Lesen des Feldes
`val`	String/boolescher Wert	Leerstring/`false`	Vorbelegung des Feldes

Zurückgegeben wird null im Fehlerfall oder ein jQuery-Element hinter dem eigentlichen Eingabeelement, das zusätzliche Informationen aufnehmen kann.

addRow Bearbeiten

Fügt eine Tabellenzeile ins Formular ein und gibt diese wieder zurück.

addFootitem Bearbeiten

Fügt das übergebene HTML in die Fußzeile ein.

setVal Bearbeiten

Befüllt das mit dem ersten Parameter bezeichnete Element mit dem im zweiten Parameter übergebenem Wert und gibt im Fehlerfall null, sonst das Eingabefeld als jQuery-Instanz zurück.

getVal Bearbeiten

Liefert den Inhalt das gewünschten Elements, oder null im Fehlerfall. Übegibt man keinen Bezeichner, so liefert die Funktion ein Objekt mit allen Werten zurück.

get$ Bearbeiten

Liefert die jQuery-Instanz des gewünschten Eingabefelds oder null zurück. Statt dem Eingabefeld kann man mit dem zweiten Parameter auch die Warnungen ('warning'), der Bereich mit der Auswahlliste ('list') oder den Zusatzbereich ('additional') anfordern.

setSuggestions Bearbeiten

Setzt Vorschläge für das bezeichnete Eingabefeld. Die im zweiten Parameter übergebenen Vorschläge können null oder [] für das Entfernen der Vorschläge, ein einzelner String oder ein Array mit mehreren Strings sein.

setList Bearbeiten

Fügt eine Auswahlliste an das bezeichnete Eingabefeld an. Im zweiten Parameter wird dazu ein Array mit den Vorschlägen in der Form ['Anzeige', 'Wert'] übergeben. Der dritte Parameter ist optional und gibt an, wie der erste Eintrag benannt sein soll (Standard: -Vorschläge-); wird dieser Eintrag ausgewählt, so wird der ursprüngliche Wert wieder hergestellt. Alternativ kann im vierten Parameter ein anderer Wert hierfür angegeben werden.