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

aus Wikipedia, der freien Enzyklopädie

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

Funktionen

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.

Abgerufen von „https://de.wikiup.org/index.php?title=Benutzer:PerfektesChaos/js/WikiSyntaxTextMod/usage/advanced/API&oldid=198976108“