Technical notes on the UpdatePage() function. It is updated as of 2.2.0 Beta65.

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

UpdatePage() is a code hook allowing cookbook recipes to mimic the behavior of editing wiki pages via the browser. It accepts a page object (array) of page data then performs all the usual PmWiki housekeeping tasks that would be performed on text submitted by the edit form in a browser window i.e. it preserves history/diff information, updates page revision numbers, updates RecentChanges pages, sends email notifications, etc.

• "Page object" refers to an array pulled from RetrieveAuthPage($pagename, $level, $authprompt=true, $since=0); (preferred), or ReadPage($pagename); (disregards page security). Note that $new['text'] should contain all page data for the new version of the page. See PageFileFormat for more information on the type of information you may be able to access in the array.
• 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.

Calling UpdatePage()

UpdatePage() cannot be called directly from config.php or an include()d recipe because there are necessary initializations which occur later in pmwiki.php. To use UpdatePage(), do it within a custom markup, a custom markup expression, or a custom action.

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 FALSE at the start of UpdatePage() and then returned at the end of this function. Any of the intervening functions can set it to TRUE (indicating successful posting/saving) but normally this is the job of the function PostPage().

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.