Benutzer:Schnark/js/fliegelflagel

Fliegelflagel (benannt nach Enzensbergers Bezeichnung eines mystischen Wesens, das bei Lewis Carroll mehrfach vorkommt) ist eine Skriptsammlung. Sie enthält einen Großteil meiner Skripte und einige anderer Autoren und kann vollständig über eine eigene Einstellungsseite konfiguriert werden.

So sieht’s aus

Einbindung

Du bindest diese Skriptsammlung in deine common.js mit folgendem Code ein:

//Skriptsammlung Fliegelflagel, [[Benutzer:Schnark/js/fliegelflagel]]
(function (module) {
	if (mw.loader.getState(module)) {
		mw.loader.using(module).then(function () {
			((mw.libs.ve.targetLoader && mw.libs.ve.targetLoader.addPlugin) || mw.libs.ve.addPlugin)(function () {
				var ve = $.Deferred();
				mw.hook('userjs.schnark-fliegelflagel.ve').fire(ve);
				return ve.promise();
			});
		});
	}
})('ext.visualEditor.desktopArticleTarget.init');
mw.hook('userjs.schnark-fliegelflagel.userdefine').fire({
	version: 1.1,
	profile: undefined,
	additional: {
	},
	config: {
	}
});
//[[Benutzer:Schnark/js/fliegelflagel.js/define.js]]
mw.loader.load('https://de.wikipedia.org/w/index.php?title=Benutzer:Schnark/js/fliegelflagel.js/define.js&action=raw&ctype=text/javascript');
mw.loader.load('https://de.wikipedia.org/w/index.php?title=Benutzer:Schnark/js/fliegelflagel.js/load.js&action=raw&ctype=text/javascript');
//Fliegelflagel Ende

Du kannst diesen Code auch in anderen Projekten oder in deiner globalen JavaScript-Seite verwenden, achte dabei aber darauf, dass du ihn immer nur ein einziges Mal lädst.

Verwende den Code bitte exakt wie angegeben und ergänze ihn nur nach der Anleitung im übernächsten Abschnitt. Wenn du ganz genau weißt, was du tust, kannst du ihn natürlich auch stärker verändern, etwa nach deinen Vorlieben formatieren, solange er funktional identisch bleibt (profile, additional und config sind optional).

Über Meldungen in der Browserkonsole oder im sichtbaren Bereich wirst du eventuell hin und wieder aufgefordert, die Art der Einbindung zu aktualisieren. Dies kann nötig sein, wenn sich der Code dazu geändert hat, oder wenn Änderungen am Format der zusätzlichen Konfiguration notwendig geworden sind. In diesem Fall solltest du die Aktualisierung vornehmen, sobald es dir möglich ist, und dabei gegebenenfalls deine Konfiguration anpassen. Über Art und Umfang der notwendigen Änderungen gibt der Abschnitt Versionen Auskunft.

Du kannst Fliegelflagel auch in Verbindung mit anderen Skripten und Gadgets nutzen, solltest dabei aber beachten, dass es – auch bei Standardeinstellungen – zu Inkompatibilitäten kommen kann, sodass du eventuell einige Skripte deaktivieren musst, entweder in der Fliegelflagel-Konfiguration oder dort, wo du die anderen Skripte aktiviert hast. Um zusätzlich andere Skripte einzubinden, kannst du entweder deren Dokumentation folgen, oder (zumindest in den meisten Fällen) sie wie im übernächsten Abschnitt beschrieben mittels Fliegelflagel aktivieren.

Bitte beachte auch die allgemeinen Bemerkungen unter Benutzer:Schnark/js#Einschränkungen.

Verwendung

Durch die Einbindung werden automatisch einige Skripte eingebunden und aktiviert. Deren Bedienung kannst du den entsprechenden Dokumentationen entnehmen, sofern dies nicht selbsterklärend ist. Auf der Seite Spezial:Fliegelflagel kannst du sehen und einstellen, welche Skripte du verwenden möchtest. Beachte, dass sich Auswahl und Standardeinstellungen jederzeit ohne Vorwarnung ändern können. Es ist eine gute Idee, die Seite Benutzer:Schnark/js auf deine Beobachtungsliste zu setzen, dann wirst du über die wichtigsten Änderungen informiert. Detailliertere (aber auch technischere) Informationen erhältst du, wenn du Benutzer:Schnark/js/fliegelflagel.js/define.js beobachtest.

Die Einstellungen gelten in der Regel für das Hauptprofil. Wenn du dich dagegen in einem alternativen Profil befindest, dann wird zwar aus dem Hauptprofil übernommen, welche Skripte standardmäßig aktiv sein sollen, du kannst dies aber unabhängig vom Hauptprofil ändern. In der Praxis heißt das: Wenn du die Einstellungsseite mit einem mobilen Browser besuchst, dann gelten die Einstellungen (nur bezüglich dem Aktivieren und Deaktivieren von Skripten, nicht die anderen Konfigurationseinstellungen) nur für mobile Browser, wobei der Standard deine üblichen Einstellungen sind.

Da die Skripte nur dann eingebunden werden, wenn sie benötigt werden, kann es schwer sein den Cache zu aktualisieren. Dazu gibt es die Seite Spezial:FliegelflagelPurge. Sollte es einmal nötig sein den Cache zu leeren, so kannst du einfach diese Seite aufrufen und warten, bis sie sich selbst neu lädt. Dann sollten alle Skripte in der aktuellen Version geladen werden.

Falls es für Testzwecke nötig ist, Fliegelflagel temporär zu deaktivieren, so kann in der Browserkonsole der Code sessionStorage['fliegelflagel-disable'] = true ausgeführt werden (gilt nur für das aktuelle Browsertab, für alle Tabs kann stattdessen localStorage genutzt werden).

Konfiguration

Eine weitergehende Konfiguration erreichst du dadurch, dass du den Code, den du von oben kopiert hast, nach deinen Wünschen anpasst.

Profil

Wie oben beschrieben gibt es neben dem Hauptprofil weitere Profile mit unabhängigen Einstellungen. Indem du die Zeile

	profile: undefined,

geeignet veränderst, kannst du selbst bestimmen, in welcher Situation welches Profil aktiv sein soll. Ein Profil ist immer ein String, wobei das Hauptprofil durch den Leerstring bezeichnet wird. Folgende Typen kannst du statt undefined verwenden:

• String: direkte Angabe des Profils
• Array von Strings: es wird das erste passende Profil gewählt (nur 'mobile' für mobile Browser und 'old' für alte Browser möglich)
• Objekt mit regulären Ausdrücken als Werte: es wird der erste Schlüssel als Profil gewählt, bei dem der reguläre Ausdruck auf den User-Agent-String passt
• Funktion: wird einmalig aufgerufen und sollte ein Profil zurückgeben

Weitere Skripte

Wenn du weitere Skripte über Fliegelflagel laden willst, kannst du sie in folgendes Objekt aus dem kopierten Code aufnehmen:

	additional: {

	},

Im einfachsten Fall schreibst du in die Zeile zwischen den geschweiften Klammern eine Anweisung der Form

	idFuerDasSkript: '[[Benutzer:Name/skript.js]]'

Achte darauf, alle Zeilen außer der letzten durch ein Komma abzuschließen. Die ID muss rein alphanumerisch sein, statt der Wikilink-Syntax kannst du auch eine komplette URL zum Skript angeben.

Statt einem einfachen String kannst du auch ein Objekt mit verschiedenen Optionen angeben. Dies erlaubt es auch, das Skript wie alle anderen zu konfigurieren. Folgende Parameter sind möglich:

Parameter	Typ	Standardwert	Beschreibung
scripts	String/Array von Strings	(Pflicht)	Name oder URL zum Skript
base	String	aktuelles Wiki	Pfad zur index.php des Wikis, von dem das Skript geladen werden soll
defaultEnabled	Zahl	0	Summe aus 1 (für Leser aktivieren), 2 (für Bearbeiter aktiveren) und 4 (für Experten aktivieren)
wiki	Array		IDs der Wikis auf denen das Skript verwendet werden kann, falls dies nicht überall der Fall ist
only	Funktion		Funktion, die true zurückgibt, wenn das Skript aktiviert werden soll, falls es nicht in jeder Situation gebraucht wird
before	Funktion		Funktion, die vor dem Laden ausgeführt wird und optional ein weiteres Skript (als vollständige URL) benennen kann, das ebenfalls geladen werden muss
after	Funktion		Funktion, die während oder nach dem Laden ausgeführt wird
type	String	'normal'	've': als VE-Plugin, 'hybrid': sowohl als normales Skript, als auch als VE-Plugin laden
readyWait	Boolean	false	Laden des Skripts erst nach bestimmten Hook-Aufruf als abgeschlossen ansehen (vor allem für VE-Plugins)
Konfiguration
title	String	(Pflicht)	Titel des Skripts
description	String	(Pflicht)	Beschreibung des Skripts
docpage	String		URL zur ausführlichen Beschreibung
category	String	'other'	Grobe Kategorie, mögliche Werte sind: 'read', 'edit', 'nav', 'history', 'other'
status	String	'unknown'	Status, mögliche Werte sind: 'stable', 'beta', 'deprecated', 'unknown'
config	Array		Angaben zu Konfigurationsparametern

Die Parameter unter Konfiguration sind dabei nur Pflicht, wenn das Skript tatsächlich konfiguriert werden soll. Beachte aber, dass ein Skript, das weder standardmäßig aktiviert ist noch konfiguriert werden kann, funktionslos bleibt. Ein mögliches Beispiel für die Angabe eines konfigurierbaren Skripts ist:

	idFuerDasSkript: {
		scripts: '[[Benutzer:Name/skript.js]]',
		title: 'Titel',
		description: 'Beschreibung'
	}

Konfigurationsfunktionen

Zum Konfigurieren von Skripten kannst du die Konfigurationsfunktionen in folgendes Objekt aus dem kopierten Code schreiben:

	config: {

	}

Ein Eintrag, der in die Zeilen zwischen den geschweiften Klammern eingetragen werden muss, kann folgendermaßen aussehen:

	idDesSkripts: function (config) {
		config.xyz = 'abc';
	}

Die Details sollten beim jeweiligen Skript angegeben sein. Achte darauf, alle Einträge außer dem letzten durch ein Komma abzuschließen.

Versionen

1.0

erste Version

1.1

geänderter Code zur Einbindung (Workaround für den VisualEditor), keine Änderungen am Format der eigenen Konfiguration

Aufnahme fremder Skripte

Wenn du ein eigenes Skript gerne in dieser Sammlung sehen würdest, dann beachte bitte die folgenden Punkte:

• Der Code muss halbwegs lesbar sein und mindestens so aussehen, als enthalte er keine Sicherheitslücken. JSHint oder vergleichbare Werkzeuge sollten bei vernünftiger Konfiguration keine Probleme finden, das Skript darf keine Funktionen verwenden, die als deprecated markiert sind.
• Das Skript funktioniert unabhängig von Browser, Skin und weiteren Einstellungen, Ausnahmen müssen begründet und dokumentiert sein.
• Wenn das Skript die Bearbeiten-Oberfläche erweitert, muss es mit dem VisualEditor kompatibel sein, eine Unterstützung der alten Oberfläche ist dagegen optional.
• Von Ausnahmefällen abgesehen muss das Skript einen Mechanismus zur Internationalisierung besitzen sowie Lokalisierungen für de, de-at, de-ch und de-formal, im Idealfall auch für en. Die Internationalisierung bezieht sich dabei auch auf eventuell abweichende Konfiguration für verschiedene Projekte.
• Das Skript ist zumindest grob durch Softwaretests abgedeckt. Diese können einfach verbal beschrieben und regelmäßig von Hand durchgeführt werden, im Idealfall liegen aber automatisierte Tests vor (gerne auch mittels Benutzer:Schnark/js/browsertest oder Benutzer:Schnark/js/qunit).
• Es existiert eine Dokumentationsseite für das Skript.
• Das Skript tut etwas so Sinnvolles, dass ich annehmen kann, dass eine Reihe von Benutzern es tatsächlich verwenden werden. Das ergibt sich entweder aus der Beschreibung des Skripts oder aus der Tatsache, dass es bereits von mehreren Benutzern verwendet wird. Außerdem sollte es auch ohne komplexe Konfiguration benutzbar sein; wenn man erst fünf Seiten JSON-Notation in seiner common.js unterbringen muss, kann man das Skript auch gleich von Hand einbinden.
• Der Code, den du mir zur Einbindung angibst, sollte meinen Code-Konventionen folgen, am besten kopierst du ihn dir aus den entsprechenden Dateien zusammen. Kurzfassung: Einrückung per Tabs, Leerzeichen um Operatoren, einfache Anführungszeichen, keine unnötigen Klammern, keine unnötigen Parameter.

Code

Der Javascript-Code befindet sich unter Benutzer:Schnark/js/fliegelflagel.js/define.js, Benutzer:Schnark/js/fliegelflagel.js/load.js, Benutzer:Schnark/js/fliegelflagel.js/config.js und Benutzer:Schnark/js/fliegelflagel.js/manage.js. Andere Seiten enthalten noch den Code der Vorversion und sollten nicht mehr verwendet oder auch nur beachtet werden.