Benutzer:PerfektesChaos/js/WikiSyntaxTextMod/usage/advanced/API

WikiSyntaxTextMod → Benutzung → Fortgeschritten → Programmierschnittstelle

API

Ein Satz von Funktionen steht Anwendern zusätzlich zu den Steuerparametern zur Verfügung.

Sie sind für nicht-interaktive oder nicht-automatische Verwendung vorgesehen.

Ein führender Punkt . steht auf dieser Seite für das Anwendungsobjekt mw.libs.WikiSyntaxTextMod.

Übersicht

Parameter

• .config.load.inhibit = true;
  AutoRun unterdrücken beim Laden

Funktionen

• .api.load()
  Laden der ausgelagerten Module anfordern
• WikiSyntaxTextMod_Run()
  Manueller Start im Browser
• .api.isAppropriate()
  Überprüfen, ob der Einsatz für die aktuelle Seite zulässig wäre
• .api.setContext()
  Kontext für nicht-interaktive Bearbeitung definieren.
• .api.edit()
  Änderungen am Wikitext unter Beachtung der Benutzerkonfiguration
• .api.textMod()
  Änderungen an der Zeichenkette eines Wikitextes

Laden des Kopfmoduls

Das abgeschlossene Laden des Kopfmoduls kann auf mehrere Arten festgestellt werden:

• mw.hook()("WikiSyntaxTextMod.ready").add(Callback-Funktion)
• .config.load.after = Callback-Funktion
• Event loadWikiScript mit dem Wert user:PerfektesChaos/WikiSyntaxTextMod
• ResourceLoader state ready: user:PerfektesChaos/WikiSyntaxTextMod

Einzelbeschreibungen

.api.load()

Laden der ausgelagerten Module anfordern.

Aufruf

Call Aufruf	.api.load(action)
Parameter	Type Type	Meaning Bedeutung
action	function boolean	user defined external callback function Benutzerdefinierte Funktion
Return value Rückgabewert		keiner

Die benutzerdefinierte Funktion wird nach Abschluss des Ladens aufgerufen. Sie hat keine Parameter; ihr Rückgabewert ist bedeutungslos. In ihr finden dann alle folgenden Aktivitäten statt; erst in ihr sind die Funktionen der ausgelagerten Module definiert.

Die action kann auch weggelassen werden oder als false angegeben werden. Mit true wird die Standardaktivität von WikiSyntaxTextMod (AutoRun) ausgeführt.

Das abgeschlossene Laden aller Module kann auf drei Arten festgestellt werden:

• action Callback-Funktion
• ResourceLoader state ready: user:PerfektesChaos/WikiSyntaxTextMod/*
• Eigenschaft .api.loaded hat den Wert true

.api.loaded

Alle ausgelagerten Module wurden zuvor geladen: true

Diese Eigenschaft kann benutzt werden, um einen zusätzlichen Aufruf von .api.load() zu vermeiden. Intern würde dies ohnehin geprüft und die Module werden nicht zum zweiten Mal geladen.

WikiSyntaxTextMod_Run()

Manueller Start der Textänderung während des Editierens.
Die Funktion ist bereits im Kopfmodul verfügbar (.api.load() nicht erforderlich).

Aufruf

Call Aufruf	WikiSyntaxTextMod_Run(); .api.run()
Return value Rückgabewert	void(0)

Der Rückgabewert void(0) ist für bestimmte Aktionen in einer GUI wichtig.

Die Funktion dient nur zur Erleichterung; der reguläre Aufruf lautet:

• mw.libs.WikiSyntaxTextMod.api.run();

.api.isAppropriate()

Überprüfen, ob der Einsatz von WSTM für die aktuelle Seite zulässig wäre (unter Berücksichtigung von Benutzereinstellungen).
Die Funktion ist bereits im Kopfmodul verfügbar (.api.load() nicht erforderlich).

Aufruf

Call Aufruf	.api.isAppropriate(advanced)
Parameter	Type Type	Meaning Bedeutung
advanced	boolean	interactive / automatic mode Manueller/Automatischer Einsatz false – automatic processing to be done true – interactive request allowed?
Return value Rückgabewert		true if advanced mode permitted wenn advanced möglich

.api.setContext()

Der Kontext für die Bearbeitung mit .api.textMod usw. kann definiert werden. Dies ist dringend ratsam, damit Selbstlinks identifiziert werden können und die sprachen- und projektspezifischen Vereinbarungen wirksam werden. Erforderlich ist das, wenn außerhalb des normalen interaktiven Browser-Kontextes des Projektes gearbeitet wird.
Die Funktion ist erst nach .api.load() verfügbar.

Aufruf

Call Aufruf	.api.setContext(article, aNS, aDB)
Parameter	Type Type	Meaning Bedeutung
article	string	wgTitle
aNS	number	wgNamespaceNumber
aDB	string	wgDBname
Return value Rückgabewert		keiner

Jeder Parameter kann weggelassen werden, oder es kann false angegeben werden. Dann wird der jeweilige Wert nicht verändert.

Damit kann am Beginn einer Bearbeitungsserie von Artikeln der allgemeine Kontext gesetzt werden:

.api.setContext(false, 0, "dewiki");

und dann im Wechsel vor jedem bearbeiteten Artikeltext nur sein Titel:

.api.setContext("Der wichtige Artikel");

Der anfängliche Projekt-Kontext bleibt dann erhalten. (Zur Bedeutung der Wiki-Global-Variablen.)

.api.edit()

Änderungen am Wikitext im Kontext von Bearbeitungskommentar und Benutzerkonfiguration; auch zum Abspeichern per API.
Die Funktion ist erst nach .api.load() verfügbar.

Aufruf

Call Aufruf	.api.edit(arglist)
Parameter	Type Type	Meaning Bedeutung
arglist	object	.wikitext	string	entire wikitext Vollständiger Wikitext
		.summary	string	optional	summary Bearbeitungskommentar
Return value Rückgabewert
	boolean	false – no change at all Keinerlei Änderungen am Wikitext
	object	.wikitext	string	modified text geänderter Wikitext
		.diffpage	boolean	true	recommended sichtbare Änderungen
				false	suppressed since negligible Unterdrücken weil Änderungen minimal
		.summary	boolean	false – No arglist.summary, no user-defined change keine Vorgabe; nur minimale Änderungen
			string	Merged, if changes Zusammengefasster Kommentar
		.minor	boolean	false	user-defined or visible change Benutzer-definierte oder sichtbare Ersetzung
				true	invisible changes unsichtbare Änderungen

Die Bemerkungen zu .api.textMod() gelten entsprechend.

.api.textMod()

Änderungen an der Zeichenkette eines Wikitextes.
Die Funktion ist erst nach .api.load() verfügbar.

Aufruf

Call Aufruf	.api.textMod(adjust)
Parameter	Type Type	Meaning Bedeutung
adjust	string	wikitext Wikitext
Return value Rückgabewert
	boolean	false – Keinerlei Änderungen am Wikitext
	Array[2]	[0]	string	geänderter Wikitext
		[1]	boolean	true	nur minimale Änderungen
				false	Größere Änderungen am Wikitext, oder durch benutzer-definierte Ersetzungen ausgelöst

Dabei kann es sich bei dem Wikitext adjust um einen vollständigen Artikel oder auch nur um einen Abschnitt oder einen Absatz handeln. Kategorien oder Interwiki müssten aber am Schluss stehen. Unvollständige Wikitext-Abschnitte könnten als fehlerhafte Syntax gewertet werden.

Bei Abruf mit action=raw oder über die API ist zu beachten, dass der Text in der Datenbank in der Kodierung UTF-8 vorliegt, also nur 8 Bit pro Zeichen. Um die Zeichenkette in den multibyte Unicode von adjust umzuwandeln, muss ggf. vorher transformiert werden. Bei der interaktiven Bearbeitung erfolgt das automatisch im Browser, weil das encoding in HTTP-Feldern angegeben ist.

Vor einem Abspeichern ist geeignet zu überprüfen, ob der veränderte Text sinnvoll ist. Durch Korrektur fehlerhafter Syntax kann es dazu kommen, dass „schlummernde“ Teile des Artikels reaktiviert und sichtbar werden, und benutzerdefinierte Änderungen können unbeabsichtigte Auswirkungen haben.

Stapelverarbeitung

Die normale Anwendung des Skripts erfolgt im Editierfenster. Auch außerhalb dieses Kontextes ist die Anwendung möglich, etwa mit API-Daten oder völlig offline.

Die Abfolge könnte etwa folgendermaßen aussehen:

1. mw.libs.WikiSyntaxTextMod = { config: { load: {inhibit:true} } };
   Benutzerkonfiguration vereinbaren
   AutoRun unterdrücken beim Laden
2. Laden des Skriptes r.js mit dem Kopfmodul von entsprechender URL:
   • mw.loader.load()
3. mw.libs.WikiSyntaxTextMod.api.load(callback);
   Damit werden weitere Module nachgeladen.
   Dabei ist callback eine benutzerdefinierte Funktion, die nach Abschluss des Ladens aufgerufen wird und innerhalb der alle folgenden Aktivitäten stattfinden.
4. mw.libs.WikiSyntaxTextMod.api.setContext(false, 0, "dewiki");
   Kontext definieren.
5. Zeichenkette text eines Artikel-Wikitextes heranschaffen.
6. mw.libs.WikiSyntaxTextMod.api.setContext("Der wichtige Artikel");
   Titel dieses Artikels vereinbaren.
7. neu = mw.libs.WikiSyntaxTextMod.api.textMod(text);
   Möglicherweise geänderten Wikitext neu ermitteln und verwerten.
8. Weitere Zeichenkette text eines Artikel-Wikitextes heranschaffen.
9. mw.libs.WikiSyntaxTextMod.api.setContext("Anderer Artikel");
10. neu = mw.libs.WikiSyntaxTextMod.api.textMod(text);
    etc. etc.

Fehlermeldungen werden nicht in den Wikitext eingefügt. Es kann aber das Array .errors.collection analysiert werden, falls diese Komponente nicht den Wert false hat.

Betreiben eines Bots (JS-Server ohne Browser)

Die nachstehenden Schritte sind zur Initialisierung einer JavaScript-Arbeitsumgebung erforderlich, so dass anschließend unabhängig von einem Browser jedoch mutmaßlich mit Internet-Verbindung (etwa per MediaWiki-API) automatisierte Bearbeitungen erfolgen können:

• Simulierte Umgebung:

var mediawiki = { config: { },
                  libs:   { } },
    mw = mediawiki,
    WSTM;
mw.libs.WikiSyntaxTextMod = { config: { },
                              main:   { } };
WSTM = mw.libs.WikiSyntaxTextMod;

• Definieren einer Callback-Funktion zum Laden aller Untermodule

WSTM.config.load = { after: function () { /* ... */ } };

• Setzen der aktuellen Projekt-Umgebung auf mw.config
• Laden des Hauptmoduls
• Callback-Funktion zum Laden aller Untermodule:
  1. Laden aller Komponenten
  2. Aufruf Callback: Aktivitäten starten
• Callback-Funktion: Aktivitäten starten

Der Quellcode der Module mag live aus dem Web bezogen werden oder kann auf Festplatte abgelegt sein.