WikiSyntaxTextMod → Benutzung → Fortgeschritten → Programmierschnittstelle

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.

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

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

Laden der ausgelagerten Module anfordern.

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

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.

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

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();

Ü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).

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.

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.)

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

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

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

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.

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.

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.