UpdatePage

für die Liste aller Seiten

Diese Seite ist ein Sammlung technischer Anmerkungen und Hinweise bezüglich der Funktion UpdatePage(). Man kann die ganzen Informationen auch bekommen, indem man den Kode in pmwiki.php liest, aber diese Seite fasst die Dinge in einer etwas besser lesbaren Form zusammen.

Sie ist aktuell bis 2.2.0.beta65.

UpdatePage(⚠ $editPageName, $old (page object), $new (page object));

UpdatePage() erlaubt Kochbuchrezepten das Verhalten des Bearbeitens einer Seite in einem Browser nachzuahmen. Es nimmt ein Seitenobjekt (array) mit Seitendaten entgegen, dann führt es alle die üblichen PmWiki-Haushalts-Tätigkeiten durch, die abgearbeitet werden, wenn ein Text über ein Bearbeiten-Fenster im Browser abgeschickt wird, als da sind history/diff-Informationen retten, Seitenrevisionsnummer hochzählen, RecentChanges-Seiten updaten, Email-Benachrichtigung senden etc.:

• "PageObjekt" bezieht sich auf ein Array, das mit RetrieveAuthPage($NameDerBearbeitetenSeite, $level, $authprompt=true, $since=0); (bevorzugt) oder mit ReadPage($Pagename) (missachtet die Sicherheit der Seite) geholt worden ist. Beachten Sie, dass $new['text'] alle Seiten-Daten für die neue Version des Textes enthalten sollte. Siehe Seiten-Dateiformat für weitere Informationen über den Typ der Informationen, die Sie über dieses Array erreichen.
• Wenn eine Seite nicht existiert, wird UpdatePage() versuchen, sie anzulegen.
• Wenn Sie ⚠ $old abgefragt haben, indem Sie %hlt php%@@RetrieveAuthPage($editPageName,⚠ $auth,$prompt,READPAGE_CURRENT) benutzten und ⚠ $new=$old setzten, wird UpdatePage() oder WritePage()@@ auch alle Versionsdaten löschen (weil READPAGE_CURRENT nur die aktuelle Version der Seite liest und zurückgibt ohne jegliche Versionen; das Gleiche passiert mit ReadPage($pagename, READPAGE_CURRENT)).

Vorsicht

Inkorrekt benutzt kann UpdatePage() nicht nur Seiteninhalte löschen, sondern kann auch den kompletten Verlauf (alle Versionen) einer Seite vernichten – PmWiki kann eine ältere Version nicht wiederherstellen, wenn Sie versehentlich den Verlauf beim Lesen oder Speichern einer Seite fallen lassen.

Aufruf von UpdatePage()

UpdatePage() kann nicht von config.php oder einem eingefügten (include()d) Rezept direkt aufgerufen werden, weil es notwendige Initialisierungen gibt, die erst später in config.php erscheinen. Wenn Sie UpdatePage() benutzen, dann innerhalb von eigenen Auszeichnungen, eines eigenen Markup-Ausdrucks oder einer eigenen Aktion.

UpdatePage() macht selbst nicht viel außer ⚠ $EditFunctions zu traversieren und jede darin enthaltene Funktion aufzurufen. ($EditFunctions kann überschrieben werden durch ein viertes Argument $fnlist, aber das ist ziemlich selten).

Die globale Variable $IsPagePosted wird zum Start von UpdatePage() auf FALSE gesetzt und dann am Ende dieser Funktion zurückgegeben. Jede der eingreifenden Funktionen kann sie auf TRUE setzten (um anzuzeigen, dass das Veröffentlichen/Speichern erfolgreich war), aber normalerweise ist das der Job der Funktion PostPage().

Die globale Variable $EnablePost wird am Beginn von pmwiki.php auf 1 gesetzt und kann jederzeit vor PostPage() auf 0 oder false geändert werden, wodurch die meisten Bearbeitenfunktionen (EditFunktions) am Fortfahren gehindert werden und die Seite wird dann auch nicht gespeichert.

The global $EnablePost is set to 1 at the start of pmwiki.php, and can be changed to 0 or false at any time before PostPage() which would block most EditFunctions from proceeding, and the page will not be saved.

Hier ist die Definition von $EditFunctions aus pmwiki.php:

$EditFunctions = array('EditTemplate', 'RestorePage', 'ReplaceOnSave',
  'SaveAttributes', 'PostPage', 'PostRecentChanges', 'AutoCreateTargets',
  'PreviewPage');

Es gibt seit 2.3.x. weitere Funktionen UpdateMe.

Rezepte ändern, wie Bearbeiten wirkt

Kochbuchautoren können ihre eigenen Funktionen zu $EditFunctions hinzufügen, wenn sie welche benötigen.

Nehmen Sie zum Beispiel einmal an, Sie müssen aus bestimmtem Gründen den Seitennamen ($pagename) der gerade bearbeiteten Seite wissen (Mag sein, Sie haben $ROSPatterns erweitert):

  InsertEditFunction('GetEditPagename', '<'); # am Beginn anfügen
  # oder möglicherweise: array_unshift($EditFunctions, "GetEditPagename");

  function GetEditPagename($pagename, $p, $n) {
    global $EditPagename;
    $EditPagename=$pagename;
  }

Oder Sie müssen noch etwas abarbeiten, nachdem eine Seite gespeichert wurde:

  InsertEditFunction('MyPostEditProcessing', '>'); // Anfügen ans Ende von $EditFunctions
  # oder möglicherweise: $EditFunctions[]= "MyPostEditProcessing";

  function MyPostEditProcessing($pagename, $p, $n) {
    // Seite auf eine andere Site spiegeln, E-Mail senden, irgendwo Seitenlisten updaten, etc
    // Könnte global $EnablePost und $IsPagePosted prüfen
  }

Oder Sie müssen noch letzte Überprüfungen machen, kurz bevor die Seite im Dateisystem gespeichert wird:

  InsertEditFunction('MyLastChecks', '<PostPage'); // genau vor PostPage()
  # oder möglicherweise: array_splice($EditFunctions, array_search('PostPage', $EditFunctions), 0, 'MyLastChecks');

  function MyLastChecks($pagename, $p, $n) {
    global $EnablePost;
    if(! $EnablePost) return;

    // tue etwas
  }

Standardfunktionen von $EditFunctions

EditTemplate

Diese Funktion erlaubt neue Seiten mit dem Inhalt einer Vorlagenseite vorzubelegen. Wenn der $new['text'] irgendetwas enthält, tut diese Funktion nichts.

Der Seitenname der Vorlage kann in $_REQUEST['template'] übergeben werden.

Andernfalls wird das $EditTemplatesFmt-Array traversiert und jede Seite gelesen bis ein Text aufgetrieben wird, der dann der Text für $new['text'] wird.

RestorePage

Beim normalen Speichern einer Seite macht diese Funktion nichts.

Der Wert für $Restore kann als Argument an die Funktion übergeben werden, aber das passiert nicht im Kontext von UpdatePage(). Der Wert wird vielmehr von $_REQUEST['restore'] geholt. Wenn dieser Wert nicht gesetzt ist, dann macht die Funktion nichts. Wenn der Wert auf einen Zeitstempel gesetzt ist, wird die PageHistory traversiert und die Seitenänderungen werden in umgekehrter Reihenfolge rückgängig gemacht, bis der übergebenen Zeitstempel erreicht ist.

ReplaceOnSave

Es gibt zwei Arrays: $ROEPatterns und $ROSPatterns. In jedem Array ist der Schlüssel dieser assoziativen Arrays das Suchmuster und der assoziierte Wert ist der Ersatz dafür. $ROEPatterns wird bei jeder Bearbeitung ersetzt, $ROSPatterns nur wenn $EnablePost gesetzt ist.

SaveAttributes

Mehrere unterschiedliche Attribute werden berechnet als neue Schlüssel für das ⚠ $new[]@@-Seiten-Array. (Jedes davon wird dann zu einer eigenen Zeile in der Seitendatei (siehe [[PageFileFormat|+]]). "Targets" wird zusammengestellt als leerzeichenseparierte Liste von Seiten, auf die von dieser Seite verwiesen wird. Eigenschaften, die in der globalen Variablen <code class='escaped'>$SaveProperties</code> gehalten werden, werden aus dem @@$page[] (old page)-Array kopiert.

• Anmerkung: SaveAttributes ruft MarkupToHTML() für den Seitentext auf. Das setzt Seitenvariablen, kann aber Seiteneffekte haben (wenn Sie einen Zähler für Ihr Markup pflegen, die jedesmal in Dateien schreibt, wenn eine Seite angesehen wurde, etc.).

PostPage

$IsPagePosted wird auf FALSE gesetzt.

Wenn $EnablePost wahr ist, dann ereignen sich folgende Schritte:

• Attribute wie 'charset' ($Charset), 'author' ($Author), 'author:<timestamp>' ($Author), und 'host:<timestamp>' ($_SERVER['REMOTE_ADDR']) werden gesetzt.
• Ein 'diff' wird bestimmt zwischen dem vorherigen und dem neuen Text und das Ergebnis wird gespeichert als ein '<timestamp>'-Schlüssel.
• Wenn der Text auf die globale Variable $DeleteKeyPattern passt, wird die Seite gelöscht.
• WritePage() wird aufgerufen.
• $IsPagePosted wird auf TRUE gesetzt.

PostRecentChanges

Wenn $IsPagePosted NICHT TRUE ist, dann tue nichts.

Das globale Array $RecentChangesFmt[] wird traversiert, wobei der Schlüssel zum assoziativen Array der Name der Seite ist, in die die Änderung eingetragen werden soll, und der assoziierte Wert der Text ist, der in die Seite am Ende einzutragen ist.

Wenn die Zeilenzahl in der RecentChanges-Seite den Wert der globalen Variable $RCLinesMax übersteigt, wird die Seite angemessen gekürzt.

Die RecentChanges-Seite wird per WritePage() geschrieben.

AutoCreateTargets

Wenn Verweisziele in der Seite auf bestimmte Globale passen und die Ziele existieren noch nicht, werden sie automatisch angelegt. Siehe auch AutoCreatePages.

PreviewPage

Diese Funktion tut nichts, wenn Sie keine Vorschau machen.

Weitere Funktionen von $EditFunctions

Es gibt noch weitere Funktionen von $EditFunctions in PmWiki, sie sind aber nicht Teil der Basisfunktionalität:

author.php

array_unshift($EditFunctions,'RequireAuthor'); // Stellt sicher, dass der Autor gesetzt ist, bevor die Seite bearbeitet werden darf.

blocklist.php

array_unshift($EditFunctions, 'CheckBlocklist');

draft.php

array_unshift($EditFunctions, 'EditDraft'); // Prüfe, ob im Entwurf gespeichert wird und wenn, ändere Namen und leite um zur Entwurfseite für die weitere Bearbeitung.

• Anmerkung: Dies kann den Seitennamen $pagename unerwartet ändern.

notify.php

$EditFunctions[] = 'PostNotify'; // Füge 'PostNotify' hinzu um eine E-Mail zu versenden, wenn die Bearbeitung erfolgreich abgeschlossen ist.

pagelist.php

$EditFunctions[] = 'PostPageIndex'; // behandle (:pagelist:)-Funktionalität, nachdem eine Seite geändert wurde.

simuledit.php

array_unshift($EditFunctions,'MergeSimulEdits'); // Wenn mehr als eine Bearbeitung seit dem Laden der Seite erfolgte, pflege die Änderungen ein, bevor die Seite gespeichert wird.

• Siehe Gleichzeitig bearbeitete Seiten

transition.php

Behandelt Übergänge zwischen Versionen. Wird für 'GUI Edit buttons' genutzt.

urlapprove.php

array_splice($EditFunctions, array_search('PostPage', $EditFunctions), 0, 'BlockUnapprovedPosts');

Setzt die BlockUnapprovedPosts()-Funktion direkt vor PostPage()

Hinweise

Kann ich UpdatePage() direkt in der config.php-Datei aufrufen?

Nein. Wie schon bei den Funktionen festgestellt: UpdatePage() kann nicht direkt in config.php aufgerufen werden, weil es notwendige Initialisierungen gibt, die erst später passieren in pmwiki.php. Es reicht nicht, nur stdconfig.php zu laden. Wenn Sie UpdatePage() benutzen wollen, müssen Sie es innerhalb eines eigenen Markups, eines 'custom markup expression' oder einer eigenen Aktion tun.

Kategorien: PmWiki Internals PmWiki Developer für die Liste aller Seiten