[pmwiki-devel] UpdatePage and HandleEdit

[Patrick R. Michaud]

On Mon, Dec 11, 2006 at 06:57:50PM +0000, Hans wrote:
> I am trying to understand the interaction of a few PmWiki bits:
> 
> The new UpdatePage function, so it says, calls all the EditFunctions
> in turn, which will do their respective bits. I can call it pretty
> well from a recipe script and have a new page created, updated and
> saved, without need for action=edit, or use of HandleEdit.
> 
> HandleEdit is called through action=edit, and will open a page, if
> allowed, in a textarea inside the edit form, templated by the EditForm
> page.
> 
> The Editfunctions array is defined thus:
> $EditFunctions = array('EditTemplate', 'RestorePage', 'ReplaceOnSave',
>   'SaveAttributes', 'PostPage', 'PostRecentChanges', 'AutoCreateTargets',
>   'PreviewPage');
> 
> So using UpdatePage from within a recipe script how can I trigger
> a page preview? 

UpdatePage itself doesn't preview a page -- the 'PreviewPage' 
function in $EditFunctions simply renders the current text into
$FmtV['$PreviewText'] so that it's easy for the caller (usually
HandleEdit) to display a preview.  The HandleEdit function is
actually responsible for displaying the edit page (including the
edit form and any preview if appropriate).

Put another way -- UpdatePage doesn't send any output to the browser,
it's entirely focused on doing the steps necessary to update a page
at a programming level.  Any browser interaction that needs to take
place has to be done by the caller(s) to UpdatePage.  UpdatePage
is really intended more to be "my scripts needs to update page
XYZ and we want the history, indexes, notifications, recent changes,
and other items to be performed for this update as well."

In short, if you want to be doing page preview to the browser, you 
have to either use HandleEdit or write your own handler that does it.

> And how can I direct the new page (before it is saved)
> to the EditForm textarea instead of saving it? 

FWIW, PITS (which has a form that then becomes an edit page) simply
manipulates fields into $_POST['text'] and then calls HandleEdit().

> How do HandleEdit and UpdatePage link?

The basic flow of HandleEdit:
  1. Retrieve existing page and check permissions
  2. Update new version of page with fields from $_POST
  3. Call UpdatePage() to update page
  4. If page was successfully posted, redirect browser to view page (and exit)
  5. If page wasn't posted, then display the edit form (including any
     preview) and exit

Pm