(alternative) Einführung in eigene Markups

für die Liste aller Seiten

Administratoren

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:

The alphabet begins with "abc"

diese hier ausgeben:

The zlphzbet begins with "zbc"

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.
Aber es gibt noch jede Menge anderer Stellen in der Regelreihenfolge — jemand anderes muss da mehr ins Detail gehen, wenn Sie es brauchen. Jene Seite mit eigenen Auszeichnungen gibt ein paar gute Anhalte dazu.

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

  1. 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.
  2. 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:

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')))");

Die Argumente der Reihe nach:

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']='')");

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

http://www.example.com/pmwiki/Mygroup/Mypage

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

http://www.example.com/pmwiki/Mygroup/Mypage?action=source

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

http://www.example.com/pmwiki/pmwiki.php?n=Mygroup.Mypage

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

http://www.example.com/pmwiki/pmwiki.php?n=Mygroup.Mypage?action=edit

(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

Originalseite auf PmWikiDe.CustomMarkupAlt   —   Rückverweise

Zuletzt geändert:   PmWikiDe.CustomMarkupAltam 18.12.2019