[pmwiki-users] EditingAPI for timestamps

[Patrick R. Michaud]

On Mon, Feb 12, 2007 at 08:30:40PM +0100, Lukasz Stafiniak wrote:
> Hi,
> 
> Could someone write about the API used to resolve editing conflicts?
> For example here:
> 
> http://www.pmwiki.org/wiki/PmWiki/EditingAPI

I'll write about it here for now, perhaps someone can update
the EditingAPI page.

Posting a page is done via an HTTP POST request.  The fields that
PmWiki expects the client to send at minimum are:

    n=Group.PageName
    action=edit
    text=text to be posted
    post=1

If an author name is to be associated with the post, it comes in 
the 'author' field:

    author=Alice

Minor edits are indicated by the diffclass field:

    diffclass=minor

If the page is password protected, the browser must either have been
previously authenticated (via a PHP session cookie) or otherwise send
the appropriate credentials to allow edit access to the page.
Normally the credentials are given by the 'authpw' and 'authid'
fields:

    authid=alice
    authpw=alicepassword

Simultaneous edits are handled by the 'basetime' field.  When a browser
requests an edit form using ?action=edit, PmWiki includes a hidden
'basetime' field in the edit form that holds the time the form
was sent.  When the form is submitted, if the page's last modification
time is greater than the basetime in the form, we know that the
page changed somehow after the author requested the edit form.
(The basetime also tells PmWiki which version of the page was "current"
when the edit form was requested, so it can figure out how to merge
the changes together.)

If a page is changed after a form's basetime, then instead of saving
the page PmWiki sends back a new edit form with any merged changes
and a note to the author to review the page for conflicts and
submit again.

If a client sends a post request that doesn't include a 'basetime'
field, then no simultaneous edit checking is performed, and the
contents of the 'text' field replace any existing content.

A successful request to save a page generally results in a 302
HTTP response, telling the browser to view the (newly saved) page.
If a request to save a page fails, generally PmWiki returns a
new edit form along with messages indicating why the page could
not be saved.

Hope this helps -- if I've left anything out or unclear then
let me know.

Pm