Funktionen

Diese Seite erklärt einiges der inneren Arbeit von PmWiki, indem sie erklärt, wie einige der Funktionen in PmWiki arbeiten. Wegen einer kürzeren Liste/Übersicht, die zum Beispiel für Rezepteschreiber nützlich ist, siehe Cookbook:Functions.

Wenn Sie diese Funktionen nutzen, versichern Sie sich, dass alle relevanten internen Variablen korrekt initialisiert worden sind. Siehe Eigene Auszeichnungen und Eigene Aktionen wegen weiterer Informationen darüber, wie diese Funktionen typischerweise von Markup() or $HandleActions[] aufgerufen werden.

PSS($string)

Die PSS()-Funktion entfernt die Backslashes, die automatisch durch die /e-Option von PHPs preg_replace-Funktion vor Anführungszeichen gesetzt werden. PSS() wird am ehesten eingesetzt, um Argumente für Markup() zu ersetzen, wenn das Muster die /e-Option gesetzt hat und eines oder mehrere der eingeklammerten Musterteile Backslashes oder Anführungszeichen enthalten könnte/könnten ("PSS" steht für "PmWiki Strip Slashes").

Von PM: PmWiki erwartet den Einsatz von PSS() immer innerhalb von Strings in doppelten Anführungszeichen, in deren Inneren wiederum einfach angeführte Strings enthalten sind. Der Grund dafür ist, dass wir nicht wollen, dass $1 oder $2 aus Versehen Zeichen enthalten, die dann zwischen den doppelten Anführungzeichen interpretiert werden, wenn PSS() durchgeführt wird.

Markup('foo', 'inline', '/(something)/e', 'Foo(PSS("$1"))'); # falsch

Markup('foo', 'inline', '/(something)/e', "Foo(PSS('$1'))"); # richtig

Beispiel

Dies ist ein fiktives Beispiel, bei dem PSS() eingesetzt werden sollte. Nehmen wir an, dass Sie eine Direktive (:example:) definieren wollen, so dass (:example "Ein Pferd":) diesen HTML-Kode ergibt:

Und so könnte die Markup-Regel erzeugt werden:

Markup('example', 'directives',
       '/\\(:example\\s(.*?):\\)/e',
       "Keep('<div>'.PSS('$1').'</div>')");

Der Einsatz von PSS() um '$1' ist nötig, weil der auf das Muster passende Text Anführungszeichen enthalten könnte und das /e Backslashes davorsetzen wird.

stripmagic($string)

Diese Funktion sollte eingesetzt werden beim Bearbeiten des Inhalts von $_POST- oder $_GET-Variablen, wenn diese Anführungszeichen oder Backslashes enthalten könnten. Es prüft get_magic_quotes() und entfernt, beim Ergebnis wahr, die automatisch eingefügten Escapes aus dem String.

FmtPageName($fmt, $pagename)

Gibt $fmt zurück, mit durchgeführter $variablen- und $[internationalisierungs]-Ersetzung, mit der Vorgabe, dass die aktuelle Seite $pagename ist. Siehe unter den Variablen nach einer (unvollständigen) Liste der verfügbaren Variablen, siehe auch nach in Internationalisierungen wegen der Internationalisierung. Sicherheit: Nicht anwenden bei vom Benutzer eingegebenen Daten.

Das ist eine der wichtigsten Funktionen in PmWiki, siehe in FmtPageName() wegen der vielen Dateils.

Markup($name, $when, $pattern, $replace)

Fügt der Umwandlungstabelle ein neues Markup hinzu. Eine detailiertere Beschreibung finden Sie in Eigene Auszeichnungen.

Diese Funktion wird verwendet, um Übersetzungsregeln in PmWikis Übersetzungs-'Maschine' einzufügen. Alle Argumente von Markup() sind Strings, und zwar

$name

Der String benennt die eingefügte Regel. Wenn es schon eine Regel mit diesem Namen gibt, wird diese Regel ignoriert.

$when

Dieser String wird genutzt, um zu kontrollieren, wann eine Regel angewandt wird relativ zu anderen Regeln. Die Angabe "<xyz" bedeutet, wende diese Regel vor der Regel namens "xyz" an, während ">xyz" bedeutet, wende diese Regel nach der Regel namens "xyz" an. Siehe Eigene Auszeichnungen wegen weiterer Details bezüglich der Reihenfolge von Regeln.

$pattern

Dieser String ist ein regulärer Ausdruck, der von der Übersetzungs-'Maschine' benutzt wird, um nach dem Auftreten dieser Regel in der Quelle für das Markup zu suchen.

$replace

Dieser String wird den auf den regulären Ausdruck passenden Text ersetzen, wenn einer gefunden wurde.

Siehe auch Eigene Auszeichnungen und Cookbook:Functions#Markup

MarkupToHTML($pagename, $str)

wandelt den String in $str, der das Markup enthält, in den korrespondierenden HTML-Kode um, unter der Vorgabe, die aktuelle Seite sei $pagename.

Also see: Cookbook:Functions#MarkupToHTML

mkdirp($dir)

Die Funktion mkdirp($dir) legt ein Verzeichnis $dir an, wenn es nicht schon existiert, einschließlich aller Elternverzeichnisse, die nötig sind. Für jedes erzeugte Verzeichnis wird geprüft, ob die Rechte für dies Verzeichnis ausreichen, damit PmWiki-Skripten daraus lesen und darin schreiben dürfen. Das schließt den Test auf Einschränkungen ein, die PHPs 'safe_mode'-Einstellungen bewirken. Wenn es mkdirp() nicht möglich ist, erfolgreich ein Schreib-/Lese-Verzeichnis anzulegen, bricht mkdirp() mit einer Fehlermeldung ab, die dem Administrator die Schritte anzeigt, entweder das Verzeichnis manuell anzulegen oder PmWiki genügend Rechte einzuräumen, dass es Das selbst erledigen kann.

MakeLink($pagename, $target, $txt, $suffix, $fmt)

Die Funktion MakeLink($pagename, $target, $txt, $suffix, $fmt) gibt ein ??? zurück. Ihre Argumente sind wie folgt:

 $pagename ist die Quellseite
 $target ist das Ziel des Verweises
 $txt ist der Wert für '$LinkText' in der Ausgabe 
 $suffix ist ein Anhängsel, das an $txt angehängt wird 
 $fmt ist ein Formatstring, der zur Anwendung kommt

Wenn $txt NULL ist oder nicht angegeben ist, dann wird es automatisch aus $target bestimmt.

Wenn $fmt NULL ist oder nicht angegeben ist, dann verwendet MakeLink das Standardformat, das durch den Typ des Verweises gegeben ist. Für Seitenverweise sind das die $LinkPageExistsFmt und die $LinkPageCreateFmt-Variablen, für externe Verweise kommt es entweder vom $IMapLinkFmt-Array oder von $UrlLinkFmt. Innerhalb des Formatstrings wird $LinkUrl ersetzt durch den aufgelösten URL für den Verweis, $LinkText wird ersetzt durch den zugehörigen Text und $LinkAlt wird ersetzt durch alle "title"-Informationen (alternativer Text), die mit dem Verweise zusammenhängen.

Siehe auch: MakeLink and Cookbook:Functions#MakeLink

MakeUploadName($pagename, $x)

MakeUploadName() nimmt einfach einen String $x (den Namen eines Anhangs) und wandelt ihn in einen gültigen Namen um, indem alle unerwünschten Zeichen entfernt werden. Der Name soll mit einem alphanumerischen Zeichen beginnen und enden. Seit Version 2.0.beta28, wird die Dateierweiterung in Kleinbuchstaben umgewandelt. Diese Funktion ist in scripts/upload.php definiert und wird nur angewendet, wenn Hochladen von Dateien aktiviert ist.

SessionAuth($pagename, $auth=NULL)

SessionAuth() bewältigt die Aufrechterhaltung der Authentifikation mit Cookie-Sitzungen. Die Sitzung enthält ein Passwort oder eine überprüfte ID und verbundene Gruppen von vorherigen Aufrufen. Es fügt der Sitzung Elemente, die von $auth übergeben werden, hinzu. Sie schreibt außerdem jedes Element, das in der Sitzung gesichert wurde, in $AuthPw(Passwörter) und $AuthList(IDs und Gruppen).

IsAuthorized($chal, $source, &$from)

IsAuthorized nimmt ein Seitenattribute-String (z. B. "id:user1 $1$Ff3w34HASH...") in $chal entgegen. $source wird einfach zurückgegeben und wird gebraucht, um die Auth-Kaskade (Seitenattribute - Gruppenattribute - $DefaultPassword) afzustellen. $from wird zurückgegeben, wenn $chal leer ist, weil es nicht vor dem Aufruf von IsAuthorized() überprüft wird. Das ist nötig für die Auth-Kaskade. IsAuthorized() gibt ein Array mit drei Werten zurück: $auth 1 - authenticated, 0 - not authenticated, -1 - refused; $passwd; $source von der Parameterliste.

CondAuth ($pagename, 'auth level')

CondAuth implementiert das ConditionalMarkup für (:if auth level:). Zum Beispiel ist CondAuth($pagename,'edit') wahr, wenn die Authorisierungsebene 'edit' ist. Benutzen Sie die Funktion in Konfigurationsdateien, um Bedingungen mit einer Überprüfung der Authorisierungsebenen aufzustellen, ähnlich des Gebrauchs von (:if auth level:) in Wiki-Seiten.

Anmerkung: CondAuth() sollte aufgerufen werden, nachdem alle Authorisierungssebenen und Passwörter definiert worden sind. Wenn Sie sie mit PmWiki.PmDrafts benutzen, sollten Sie das draft.php-Skript einfügen bevor sie CondAuth() aufrufen:

   $EnableDrafts = 1;
   $DefaultPasswords['publish'] = crypt('secret');
   include_once("$FarmD/scripts/draft.php");
   if (! CondAuth($pagename, 'edit')) { /* whatever */ }

Der beste Platz für den Aufruf von CondAuth() ist nahe dem Ende Ihres config.php-Skriptes.

RetrieveAuthPage($pagename, $level, $authprompt=true, $since=0)

Pm words as said in http://article.gmane.org/gmane.comp.web.wiki.pmwiki.user/12493/match=retrieveauthpage%% mit:

   $pagename   - Name der zu lesenden Seite
   $level      - erforderliche Autorisierungsebene (read/edit/auth/upload)
   $authprompt - wahr, wenn der Benutzer nötigenfalls zur Eingabe des Passwortes 
                 aufgefordert werden sollte
   $since      - wieviel vom Seitenverlauf gelesen werden soll 
                 0 == lies die komplette Seite einschließlich des ganzen Verlaufs ein
                 READPAGE_CURRENT == lies die Seite ein ohne den Verlauf zu laden
                 timestamp == lies den Verlauf nur zurück bis zum Zeitstempel ein

Der $since Parameter erlaubt PmWiki, das Einlesen zu beenden, sobald es die benötigte Information hat — d. h., wenn eine Operation wie Browsen den Seitenverlauf nicht braucht, kann die Angabe von READPAGE_CURRENT die Ladezeit merklich verkürzen. (Das kann insbesondere für so etwas wie Suchen und Seitenlisten wichtig sein.)

Wenden Sie zum Beispiel $page = @RetrieveAuthPage('Main.MyPage', 'read') an, um ein Seitenobjekt zu erhalten, das all die Informationen der korrespondierenden Datei in unterschiedlichen Schlüsseln enthält, $page['text'] beispielsweise enthält einen String mit dem aktuellen Inhalt (wiki markup) von Main.MyPage. Dieser Gebrauch ist der alternativen Funktion ReadPage($pagename, $since=0) vorzuziehen, da sie die Authorisierung des Benutzers berücksichtigt, d. h. sie überprüft die Authorisierungsebene vorm Laden der Seite, jedenfalls kann sie so eingestellt werden. ReadPage() liest eine Seite ohne Rücksicht auf die Rechte ein.

Übergibt man 'ALWAYS' als Authorisierungsebene (statt 'read', 'edit', etc.), veranlasst das RetrieveAuthPage, die Seite auf jeden Fall zu lesen, sogar, wenn sie mit einem Lesepasswort geschützt ist.

RetrieveAuthSection($pagename, $pagesection, $list=NULL, $auth='read')

RetrieveAuthSection extrahiert einen Textabschnitt aus einer Seite. Wenn $pagesection mit etwas anderem als '#' beginnt, holt sie den Text aus der Seite selbst. Andernfalls sucht RetrieveAuthSection in den Seiten, die durch $list vorgegeben sind oder in $pagename, wenn $list nicht angegeben wurde.

• Der ausgewählte Text wird in der globalen Variable $RASPageName gespeichert.
• Der Aufrufer ist selbst verantwortlich für den Aufruf von Qualify(), wenn das nötig ist.

Das bietet einen Weg, das von ReadPage zurückgegebene Array zu begrenzen, so dass es nur den Inhalt bis zu einer bestimmten Abschnittmarkierung herauszieht. Zum Beispiel, ziehe den Text zwischen dem Textbeginn und '##blogend' heraus:

function FeedText($pagename, &$page, $tag) {
  $text = RetrieveAuthSection($pagename, '##blogend');
  $content = MarkupToHTML($pagename, $text);
  return "<$tag><![CDATA[$content]]></$tag>";
}

Das '##blogend'-Argument jeißt, lies vom Beginn der Seite bis genau vor der Zeile, die die Markierung enthält. Siehe Einbinden anderer Seiten wegen weiterer Informationen über die Abschnittspezifikationen.

Diese Version liest keinen Text von Seiten, die lesegeschützt sind; wenn Sie Text auch von lesegeschützten Seiten haben wollen:

  $text = RetrieveAuthSection($pagename, '##blogend', NULL, 'ALWAYS');

UpdatePage($pagename, $old (page object), $new (page object));

weitere technische Anmerkungen

UpdatePage() erlaubt Kochbuchrezepten, das Verhalten des Bearbeitens einer Wikiseite mit dem Browser zu imitieren. Intern macht PmWiki einige haushälterische Arbeiten, die über diese Funktion erreichbar sind (Erhalten der Verlaufs-(diff)-Information, Erhöhen der Seitenrevisionsnummer, Auffrischen der RecentChanges-Seiten, Senden von E-Mail-Benachrichtigungen etc. )

• "Page objekt" bezieht sich auf ein Array, das von ReadPage($pagename); zurückgegeben wurde. Anmerkung: $new['text'] sollte alle Seitendaten für die neue Version der Seite enthalten.
• Wenn eine Seite nicht existiert, wird UpdatePage() versuchen, sie anzulegen.
• Weglassen von $old (also UpdatePage($pagename, '', $new);) wird alle Seitenverlaufsdaten löschen — ein tabula rasa.

UpdatePage() kann nicht direkt von config.php aufgerufen werden, weil es notwendige Initialisierungen gibt, die erst später in pmwiki.php gemacht werden. Es reicht nicht, stdconfig.php zu laden. Wenn Sie UpdatePage() nutzen wollen, müssen Sie es innerhalb eines 'custom markup's, eines custom markup expressions, oder einer benutzerdefinierten Aktion tun.

Categories: PmWiki Developer

Übersetzung von PmWiki.Functions Originalseite auf PmWikiDe.Functions - Rückverweise
Zuletzt geändert:
PmWikiDe.Functions am 23.09.2013
PmWiki.Functions am 22.02.2014