(alternative) Einführung in eigene Markups

für die Liste aller Seiten

Eine ganz typische Art eines "PlugIns" – Ich werde es von hier an "Rezept" nennen, weil das die Bezeichnung in der PmWiki-Welt ist – dient dazu, eine eigene Markup-Regel zu einzurichten. Das bedeutet, Sie definieren ein gewisses besonderes Textmuster in Ihrer Seite, das eine gewisse Aktion auslöst und bewirkt, dass das gewisse Textmuster durch einen anderen Text ersetzt wird.

(Wenn Sie eigene Aktionen entwerfen wollen, dann klicken Sie hier.)

Ein simples Beispiel

Das einfachste mögliche Markup ist eine bloße Ersetzung. Hier ist ein Markup, das jedes Vorkommen des Buchstaben "a" durch den Buchstaben "z" ersetzt:

Markup('a2z', '>{$var}', '/a/', 'z');

Daraufhin wird Ihre Seite mit diesem (Quell-)Text:

diese hier ausgeben:

Das ist zwar nicht gerade nützlich, aber es gibt eine Idee davon, was ein Markuptext so macht.

Das Erzeugen eines neuen Markups hat mit dem Aufruf der Funktion Markup() zu tun. Dies wird gewöhnlich durch das Bearbeiten Ihrer config.php erreicht, Sie können es aber auch in eine eigene Gruppen- oder Seiten-PHP-Datei einfügen — nachzulesen unter Lokale Anpassungen und Individuelle Einstellungen pro Gruppe.

Die Markup()-Funktion nimmt vier Argumente entgegen:

1. Den besonderen Namen, den Sie Ihrem Markup geben. Er soll kurz, aber beschreibend sein. Achten Sie darauf, dass Sie nicht den Namen eines bestehenden Markups verwenden, jenes wird dann seinen Dienst versagen. (Sie können die Standarddefinitionen in scripts/stdmarkup.php finden.)
2. Einen Anzeiger, WANN dies auftreten soll. PmWiki hat Dutzende von diesen Regeln und es macht einen großen Unterschied, in welcher Reihenfolge die auftreten. Wenn die eine Regel (#1) jedes "a" in ein "b" verwandelt und eine weitere (#2) jedes "az" in "zz", ist es offensichtlich, dass es einen großen Unterschied macht, in welcher Reihenfolge sie aufgerufen werden. Wenn #1 vor #2 auftritt, wird der Text "azazaz" zu "bzbzbz". Wenn aber #2 vor #1 auftritt, enden Sie bei "zzzzzz". Dieser Anzeiger wird normalerweise angegeben durch eine öffnende spitze Klammer (vorher) oder eine schließende spitze Klammer (hinterher), gefolgt von dem Namen einer Regel. Nach meiner Erfahrung ist die wichtigste Regel in Sachen Reihenfolge "{$var}", die Variablen ersetzt — wenn Sie "<{$var}" eintragen, wird Ihre Regel vor der Variablenersetzung angewendet, wenn Sie ">{$var}" eintragen, wird Ihre Regel nach der Variablenersetzung angewendet.

Argument 3 und 4 sind einfach Argumente, die an die preg_replace-Funktion weitergereicht werden. Die sucht nach Argument #3 und ersetzt es mit Argument #4

3. Der Suchstring in ein regulärer Ausdruck. Er kann so einfach sein wie "/a/", (passt auf jedes vorkommende Zeichen "a") bis hin zu sehr umfangreichen und komplizierten Ausdrücken. Jedesmal, wenn dies Muster auf ihren Text passt, wird es ersetzt mit dem Argument #4. Beachten Sie, dass Ihr Muster immer von Vorwärtsschrägstrichen umgeben ist und dass dem schließenden Schrägstrich noch Modifier folgen können. Die Modifier sind einzelne Buchstaben, über die Sie mehr lesen können unter http://www.php.net/manual/en/reference.pcre.pattern.modifiers.php. Die wichtigsten sind
   • "i" → ignoriert Groß/Kleinschreibung,
   • "s" → ein Punkt passt auch auf Zeilenumbrüche,
   • "m" → die Anker "^" und "$" passen nicht nur auf den Beginn und das Ende der Zeichenkette, sondern auch vor und hinter Zeilenümbrüchen — also auf Zeilenanfang und -Ende — und (vielleicht das wichtigste in diesem Zusammenhang),
   • "e" → wertet den Ersetzungstext als PHP-Ausdruck aus — das erlaubt es, Funktionen aufzurufen, die kompliziertere Sachen machen als nur ein einfaches Suchen&Ersetzen.
4. Dies ist der Ersetzungstext. Er kann eine einfache Zeichenkette sein oder er kann Dinge wie $1, $2 etc. enthalten, wenn Sie Klammergruppen in Ihrem dritten Argument haben (Sie müssen darauf achten, einen Backslash vor das $-Zeichen zu setzen oder das Argument in einfache Anführungszeichen zu setzen etc., um eine frühzeitige Auswertung von Variablen zu verhindern). Oder er kann ein Aufruf einer PHP-Funktion sein, wenn Sie den /e-Modifier in Argument #3 benutzt haben.

Nachdem das alles gesagt ist, ist der beste Weg zu lernen, eigene Rezepte oder Markups zu schreiben, ein Blick auf Beispiele zu werfen, wie andere Leute so etwas gemacht habe.

Die (:comment ...:)-Markup-Regel

Hier ist die Definition der Regel für das (:comment ...:)-Markup aus scripts/stdmarkup.php:

Markup('comment', 'directives', '/\\(:comment .*?:\\)/i', '');

Der Sinn dieses Markups ist, dass Sie Text in ihren Quelltext einfügen können, der nicht erscheint, wenn die Seite im Browser angezeigt wird. Lassen Sie uns die Argumente betrachten:

• ARG1: 'comment' — ein kurzer, beschreibender Name - die ID der Regel
• ARG2: 'directives' — das ist eine von 9 Phasen, die die Antwort geben auf die Frage, wann meine Regel angewendet werden soll.
• ARG3: '/\\(:comment .*?:\\)/i' — dies ist der reguläre Ausdruck, der auf (:comment ANY TEXT HERE:) passt — dies ist das Muster, nach dem gesucht wird. Da der letzte Schrägstrich von einem i gefolgt wird ("/i"), passt genauso gut auch (:COMMENT some text:) und (:CoMmEnT some text:) — Groß/Kleinschreibung wird von dem Suchmuster nicht unterschieden.
• ARG4: '' — jedes Auftreten des Musters wird ersetzt durch ... NICHTS. So verschwindet der Kommentar einfach, was genau das ist, was Sie wollten.

Die (:include ...:)-Markup-Regel

Lassen Sie uns noch ein weiteres Beispiel aus stdmarkup.php ansehen, die (:include PAGENAME:)-Markup-Regel. Die Regel ist gemacht, um Text aus einer anderen Seite in die Seite hineinzuziehen. Hier ist die Definition aus stdmarkup.php:

Markup('include', '>if',
  '/\\(:include\\s+(\\S.*?):\\)/ei',
  "PRR(IncludeText(\$pagename, PSS('$1')))");

Warnung: Der /e Modifizierer ist schon seit Jahren überholt (und endgültig entfernt mit PHP7.2). Für Details, wie er zu ersetzen ist, siehe Eigene Auszeichnungen.

Die Argumente der Reihe nach:

• ARG1: 'include' — kurzer beschreibender Name dafür, was die Regel tut.
• ARG2: '>if' — wende diese Regel nach der Regel mit der ID 'if' an
• ARG3: '/\\(:include\\s+(\\S.*?):\\)/ei' — dieser reguläre Ausdruck passt auf ein Muster (:include pagename:), in dem "pagename" irgend eine Folge von Nicht-Whitespace-Zeichen ist. (Whitespace ist ein Leerzeichen, ein Tabulator- oder ein Zeilenvorschub-Zeichen). Die wichtige Änderung ist das /ei am Ende. Sie wissen schon, dass das "i" am Ende bedeutet, dass die Groß/Kleinschreibung ignoriert wird. Das "e" bedeutet, dass der Ersatztext ein PHP-Ausdruck ist, der ausgewertet werden soll. (Es bedeutet auch, dass ein Bündel von Backslashes bestimmten Zeichen vorangestellt wird, die von dem Suchmuster kommen, wenn Sie Klammern zum Einfangen von Regex-Mustern benutzen.) Beachten Sie, dass das "\\S.*?" von Klammern umgeben wird, was bedeutet, dass die Fundstelle gegriffen und dem Ersetzungsstring als $1 zur Verfügung gestellt wird.
• ARG4: "PRR(IncludeText(\$pagename, PSS('$1')))" — hierdurch wird das Suchmuster ersetzt. Da aber oben dieses "e" vorhanden ist, wird dieser Text als PHP-Ausdruck interpretiert. Beachten Sie ein paar Dinge über diesen Text, die wirklich wichtig sind:
  • Jegliche Variablennamen werden vor unmittelbarer Ersetzung geschützt, entweder durch Voranstellen eines Backslashes vor das Dollarzeichen oder durch das Setzen von einfachen Anführungszeichen um das Argument herum.
  • Die Funktion PSS('$1') "Strips Slashes" — sie wird die Slashes wieder los, die durch die obige /e-Option gesetzt wurden.
  • Die Funktion IncludeText() ist eine PmWiki-Funktion, die zwei Argumente annimmt (einen Referenzseitennamen und den Seitennamen des Textes, der behandelt werden soll) und sie liefert den Text dieser Seite zurück. Das bedeutet, dass das (:include pagename:) in Ihrer Quelle ersetzt wird durch den Text jener Seite.
  • Das umgebende PRR() weist PmWiki an, noch einmal alle Markup-Regeln durch zu gehen, für den Fall, dass etwas aus dem eingefügten Text hinzugekommen ist, das von bereits durchgelaufenen Regeln bearbeitet werden sollte. PRR() liefert immer den Wert seines Argumentes zurück, es ist so eine Art transparente Funktion mit einem Seiteneffekt.

Die (:nogroupheader:)-Markup-Regel

Diese Markup-Regel dient dazu, die Anzeige des GroupHeader zu unterdrücken. Damit das geschieht, muss die globale Variable $GroupHeaderFmt mit einer leeren Zeichenkette gefüllt werden. Hier ist die Markup-Definition.

Markup('nogroupheader', '>include',
  '/\\(:nogroupheader:\\)/ei',
  "PZZ(\$GLOBALS['GroupHeaderFmt']='')");

• ARG1: 'nogroupheader' — kurzer Name, beschreibt, was diese Regel tut.
• ARG2: '>include' — wende diese Regel nach der Regel mit der ID 'include' an (ja, das ist die Regel, die wir gerade betrachtet haben).
• ARG3: '/\\(:nogroupheader:\\)/ei' — ein wirklich einfacher regulärer Ausdruck mit der gleichen /ei-Option wie oben.
• ARG4: "PZZ(\$GLOBALS['GroupHeaderFmt']='')"
  • Und wieder ist die Variable durch escapen des Dolllarzeichens vor der Interpretion geschützt (durch Voranstellen eines Backslashes).
  • Auf die globale Variable $GroupHeaderFmt wird mit der PHP-Super-Globalen $GLOBALS[] zugegriffen.
  • Der Kern dieser Regel hat diesen Text: $GLOBALS['GroupHeaderFmt']='' — das setzt den Wert auf die leere Zeichenkette.
  • Das umgebende PZZ() sagt einfach, werde jeglichen Rückgabewert los — das Suchmuster wird durch die leere Zeichenkette ersetzt.

Eigene Aktionen

Eine Aktion wird ausgeführt durch das Anhängen von "?action=MYACTION" an das Ende des URL. Die Standardaktion ist stets "browse", wenn Sie also keine Aktion in Ihrer Adressleiste sehen, dann nimmt PmWiki an, Sie meinten "http://www.example.com/pmwiki/...?action=browse".

Wenn Sie zum Beispiel Cookbook:CleanUrls benutzen und auf die Seite

zugreifen wollen, aber auch die Aktion "source" (die zeigt den Quelltext der Seite) ausführen möchten, dann benutzen Sie

Wenn Sie aber NICHT die CleanUrls benutzen und wollen auf die Seite

zugreifen und dabei die Aktion "edit" (damit "bearbeiten" Sie die Seite) ausführen möchten, dann benutzen Sie

(Das ist eine alternative Methode, eine Seite zu bearbeiten, wenn es keinen Verweis dafür gibt.)

Es gibt mehrere andere eingebaute Aktionen, aber manchmal ist es bequemer (als Entwickler), eine eigenen Aktionen hinzuzufügen.

Wenn Sie eine Aktion "meineAktion" hinzufügen wollten, und riefen dazu die Funktion BehandleMeineAktion() auf, dann schrieben Sie diesen Kode in Ihre config.php oder in Ihr Rezeptskript:

$HandleActions['meineAktion'] = 'BehandleMeineAktion';

$HandleAuth['meineAktion'] = 'admin';

function BehandleMeineAktion($pagename, $auth) {
   $page = RetrieveAuthPage($pagename, $auth);
   if (!$page) {
      ...
   }
   ...
}

Beachten Sie, dass das $HandleAuth[]-Array bestimmt, welche Standardautorisierung als zweites Argument an Ihre eigenen Aktion übergeben wird. Sie sind dafür verantwortlich, diese Autorisierung durchzusetzen (typischerweise durch CondAuth() oder RetrieveAuthPage()).

Weitere interessante Seiten finden Sie in der PmWiki Developer-Kategorie.

für die Liste aller Seiten