Technical notes on the UpdatePage() function. It is updated as of 2.2.0 Beta65.
UpdatePage($editPageName, $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($somePageNameYouAreEditing, $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.
- If you retrieved $old using
RetrieveAuthPage($editPageName,$auth,$prompt,READPAGE_CURRENT) and set $new=$old, then UpdatePage() or WritePage() will also erase all historical data (because READPAGE_CURRENT only reads and returns the current version of the page without any history; the same happens with ReadPage($pagename, READPAGE_CURRENT)).
Caution
If used incorrectly, UpdatePage() can not only blank pages, but can wipe entire histories of pages - PmWiki cannot recover an old version if you accidentally drop the page history when you read or save a page.
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 $IsPagePostedUpdatePage() 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().
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.
Here is the definition of $EditFunctions from pmwiki.php:
$EditFunctions = array('EditTemplate', 'RestorePage', 'ReplaceOnSave',
'SaveAttributes', 'PostPage', 'PostRecentChanges', 'AutoCreateTargets',
'PreviewPage');
There are other functions as of 2.3.x. UpdateMe.
Recipes can change how edits work
Cookbook Authors can add their own functions to $EditFunctions as needed.
As an example, suppose you need to know the $pagename of the page being edited for some reason (Maybe you've added to $ROSPatterns):
InsertEditFunction('GetEditPagename', '<'); # add at the start
# or possibly: array_unshift($EditFunctions, "GetEditPagename");
function GetEditPagename($pagename, $p, $n) {
global $EditPagename;
$EditPagename=$pagename;
}
Or if you need to do processing after a page has been saved:
InsertEditFunction('MyPostEditProcessing', '>'); // Add to end of $EditFunctions
# or possibly: $EditFunctions[]= "MyPostEditProcessing";
function MyPostEditProcessing($pagename, $p, $n) {
// mirror page to another site, send an email, update page lists somewhere, etc
// Might check global $EnablePost and $IsPagePosted
}
Or if you need to do some last checks just before the page is saved to the filesystem:
InsertEditFunction('MyLastChecks', '<PostPage'); // just before PostPage()
# or possibly: array_splice($EditFunctions, array_search('PostPage', $EditFunctions), 0, 'MyLastChecks');
function MyLastChecks($pagename, $p, $n) {
global $EnablePost;
if(! $EnablePost) return;
// do something
}
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 diffs 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.
- Note:
SaveAttributes runs MarkupToHTML() on the page text. This sets page variables, but may have side effects (if you are keeping a count of your markup, writing to files every time a page is viewed, etc).
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.
There are other $EditFunctions that come with PmWiki but that are not part of the basic functionality:
author.php
array_unshift($EditFunctions,'RequireAuthor'); // Makes sure an author is specified before allowing page to be edited
blocklist.php
array_unshift($EditFunctions, 'CheckBlocklist');
draft.php
array_unshift($EditFunctions, 'EditDraft'); // Check if saving to the draft file and if so, change names and Redirect to the draft page to continue edit.
notify.php
$EditFunctions[] = 'PostNotify'; // Add 'PostNotify' to send an email after edit successfully done
pagelist.php
$EditFunctions[] = 'PostPageIndex'; // handle (:pagelist:) functionality after a page is updated
simuledit.php
array_unshift($EditFunctions,'MergeSimulEdits'); // If more than one edit happened since page load, merge the changes before saving
transition.php
Handles transitions between PmWiki versions. Used for GUI Edit buttons.
urlapprove.php
array_splice($EditFunctions, array_search('PostPage', $EditFunctions), 0, 'BlockUnapprovedPosts');
Puts the BlockUnapprovedPosts() function right before PostPage()
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