De Redes de Computadores

PmWiki: UpdatePage

This page is a collection of technical notes regarding UpdatePage(). You can get all the same information by code-reading in pmwiki.php, but this page summarizes things in a slightly more readable form...

It is updated as of 2.2.0 Beta65.

UpdatePage() allows cookbook recipes to mimic the behavior of editing wiki pages via the browser. Internally, PmWiki does several house keeping tasks which are accessible via this function (preserving history/diff information, updating page revision numbers, updating RecentChanges pages, sending email notifications, etc._

• "Page object" refers to an array pulled from ReadPage($pagename); Note that $new['text'] should contain all page data for the new version of the page.
• If a page doesn't exist, UpdatePage() will attempt to create it.
• Ignoring $old (e.g. UpdatePage($pagename, '', $new);) will erase all historical page data---a tabula rasa.

UpdatePage() does very little itself other than traverse $EditFunctions and call each function contained there. ($EditFunctions can be overridden by the 4th argument $fnlist, but this is fairly rare).

The global $IsPagePosted is set to true at the start of UpdatePage() and then returned at the end of this function. Any of the intervening functions have the potential of setting it to false if an error condition occurs.

Here is the definition of $EditFunctions from pmwiki.php:

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

EditTemplate

This function allows pre-populating new pages with the contents of a template page. If the $new['text'] contains anything then this function does nothing.

The pagename of the template can be passed in the $_REQUEST['template'].

Otherwise the $EditTemplatesFmt array is traversed and each page read until obtaining some text which then becomes the text of the $new['text'].

RestorePage

On a normal save of a page this function does nothing.

The value for $Restore can be passed by argument to the function, but it will not in the context of UpdatePage(). The value will be obtained instead from $_REQUEST['restore']. If this value is not set then this function will do nothing. If this value is set to a timestamp then the page history will be traversed and the various diff's in page history will be reverse applied until the requested timestamp.

ReplaceOnSave

There are 2 arrays: $ROEPatterns and $ROSPatterns. In each array the key to the hash is the search-pattern and the value to the hash is the replace-pattern. $ROEPatterns is replaced on each edit, $ROSPatterns only if $EnablePost is set.

SaveAttributes

Several different attributes are calculated to become one of the keys of the $new[] page array. (Each of these will then become their own line in the pagefile.) Targets are calculated as a space-separated list of pages which are linked to from this page. Properties held in the global $SaveProperties are copied from the $page[] (old page) array.

PostPage

$IsPagePosted is set to false.

If $EnablePost is true then these steps occur:

• Attributes such as 'charset' ($Charset), 'author' ($Author), 'author:<timestamp>' ($Author), and 'host:<timestamp>' ($_SERVER['REMOTE_ADDR']) are set.
• A diff is done between the previous text and the current text and the result stored as a '<timestamp>' key.
• If the text matches the global $DeleteKeyPattern then the page is deleted.
• WritePage() is called
• $IsPagePosted is set to true.

PostRecentChanges

If $IsPagePosted is NOT true then do nothing.

The global array $RecentChangesFmt[] is traversed with the KEY to the hashed array being the pagename where the changes should be written to and the VALUE of the hashed array being the text to be written to the end of that page.

If the number of lines in the recentchanges page exceeds the global $RCLinesMax then the page is chopped appropriately.

The recentchanges page is written via WritePage().

AutoCreateTargets

If link targets within the page match some global and they do not exist then they will be automatically created. See also AutoCreatePages.

PreviewPage

This function does nothing if you're not doing a preview.

Notes

Can I call UpdatePage() directly from config.php?

No. As stated on the PmWiki/Functions: UpdatePage() cannot be called directly from config.php because there are necessary initializations which occur later in pmwiki.php. It is not enough to just load stdconfig.php. If you want to use UpdatePage() you will need to do it within a custom markup, a custom markup expression?, or a custom action.

Category: PmWiki Internals PmWiki Developer