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

Skript laden

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

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

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

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

Abbauen

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

Funktionen

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

getFunctions

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

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

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

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

addFootitem

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

setVal

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

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$

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

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

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.

setWarning

Setzt direkt eine Warnung für ein Element.

getWarning

Liefert die aktuelle Warnung eines Elements oder null.

getTitle

Liefert den Titel (wgTitle) der Seite.

getText

Liefert den Wikitext der Seite.

setText

Ändert den Wikitext der Seite.

addComment

Setzt einen Bearbeitungskommentar.

setNotMinor

Markiert die Bearbeitung nicht als klein.

Code

Der Javascript-Code befindet sich unter Benutzer:Schnark/js/templateEditor.js.