version=pmwiki-2.2.0 ordered=1 urlencoded=1
agent=Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.8.1.19) Gecko/20081216 Ubuntu/8.04 (hardy) Firefox/2.0.0.19
author=Petko
charset=ISO-8859-1
csum=revert
ctime=1148849595
host=81.65.14.164
name=PmWiki.EditingAPI
rev=52
targets=Profiles.Smc
text=(:Summary:This page documents the API for modifying PmWiki pages via the wiki engine:)%0aThis page documents the API for modifying PmWiki pages via the wiki engine (i.e. via @@pmwiki.php@@).%0a%0a!! Sending a request to write to a page%0a%0aThe following fields may occur in a request to write to a wiki page.%0a%0a(:table cellspacing=5px:)%0a(:cellnr width=15%25:)'''Field=%3cvalue>'''%0a(:cell width=15%25:)'''Example'''%0a(:cell width=70%25:)'''Note'''  \%0a%0a(:cellnr:)@@n=%3cGroup>.%3cPageName>@@%0a(:cell:)@@n=PmWiki.SandBox@@%0a(:cell:)''Mandatory''. \%0aThe name of the destination page of the write request. \%0a%0a(:cellnr:)@@text=%3cpage-text>@@%0a(:cell:)@@text=Hello%2520World@@%0a(:cell:)''Mandatory''. \%0aThe text that is requrested to be written to the page. %0a%25red%25 Does the encoding matter? Must it be UTF-8? \%0a%0a(:cellnr:)@@action=edit@@%0a(:cell:)@@action=edit@@%0a(:cell:)''Mandatory''. \%0aOne of the two fields that signals that this is a write request. \%0a%0a(:cellnr:)@@post=1@@%0a(:cell:)@@post=1@@%0a(:cell:)''Mandatory''. \%0aThe other of the two fields that signals that this is a write request. \%0a%0a(:cellnr:)@@author=%3cauthor>@@%0a(:cell:)@@author=alicia@@%0a(:cell:)Usually not required. \%0aIf supplied, @@%3cauthor>@@ is considered the name to be assocated%0awith this change.  \%0a%0a(:cellnr:)@@diffclass=minor@@%0a(:cell:)@@diffclass=minor@@%0a(:cell:)Not required.%0aIf present, this field and argument indicates that the change is a minor%0achange. \%0a%0a(:cellnr:)@@authid=%3cuser-name>@@%0a(:cell:)@@authid=alicia@@%0a(:cell:)Usually not required. \%0aFor a password protected page, the client must either already have been%0apreviously authenticated (via a PHP session cookie), or otherwise send%0athe appropriate credentials. The field @@authid@@ is normally used for%0athis together with the field @@authpw@@.  \%0a%0a(:cellnr:)@@authpw=%3cpassword>@@%0a(:cell:)@@authpw=quick@@%0a(:cell:)Usually not required, see @@authid=%3cuser-name>@@ above.  \%0a%0a(:cellnr:)@@basetime=%3cnnnnn>@@%0a(:cell:)@@basetime=????@@%0a(:cell:)Not mandatory. \%0aNote that if this field is ''not'' present, there will be ''no''%0achecking for simultaneous edits. See further down for more details.%0a%25red%25Patrick, can you give an example? What is the format? Meaning? \%0a%0a(:tableend:)%0a%0aSummarizing the requirements to post an update to a page.%0a%0aWriting a page to the wiki via the wiki engine, i.e. via @@pmwiki.php@@ is%0adone via an @@HTTP POST@@ request. At a minimum, the following fields are%0arequired:%0a%0a* @@n=%3cGroup>.%3cPageName>@@%0a* @@text=%3ctext to be posted>@@%0a* @@action=edit@@%0a* @@post=1@@%0a%0aThe two fields @@action=edit@@ and @@post=1@@ together signals that the%0arequest is to write the content of the field @@text@@ to the the destination%0apage, i.e. as specified by the field @@n@@.%0a%0aAdditional fields such as @@author=%3cauthor>@@ and @@diffclass=minor@@ can be%0agiven, see the table of fields for an explanation.%0a%0aIf the page is password protected, the browser must either have been%0apreviously authenticated (via a PHP session cookie) or otherwise send the%0aappropriate credentials to allow edit access to the page.  Normally the%0acredentials are given by the 'authpw' and 'authid' fields:%0a%0a* @@authid=%3cuser-name>@@%0a* @@authpw=%3cpassword>@@%0a%0aSimultaneous edits are handled by the field '@@basetime@@'.  When a browser%0arequests an edit form using @@?action=edit@@, PmWiki includes a hidden field%0a'@@basetime@@' in the edit form that holds the time the form was sent.%0a%0aWhen the form is submitted, if the last modification time of the page is%0agreater than the basetime in the form, we know that the page changed somehow%0aafter the author requested the edit form.  (The basetime also tells PmWiki%0awhich version of the page was "current" when the edit form was requested, so%0ait can figure out how to merge the changes together.)%0a%0aIf a page is changed after a form's basetime, then instead of saving the%0apage PmWiki sends back a new edit form with any merged changes and a note to%0athe author to review the page for conflicts and submit again.%0a%0a-> I think this "note" should be accompanied with something that's well%0a   specified, so as to make it easier for an external script to handle%0a   this situation. /Christian%0a%0aIf a client sends a post request that doesn't include a '@@basetime@@'%0afield, then no simultaneous edit checking is performed, and the contents of%0athe field '@@text@@' replace any existing content.%0a%0aA successful request to save a page generally results in a 302 HTTP%0aresponse, telling the browser to view the (newly saved) page.  If a request%0ato save a page fails, generally PmWiki returns a new edit form along with%0amessages indicating why the page could not be saved.%0a%0a-> I think some formal method is needed to report that a save has been%0a   blocked.  The reason for the block might be a requirement for an author%0a   name, or that blocklist don't like it. There should be an API to detect%0a   this in any case. /Christian%0a%0a%0aChristian's questions:%0a* Can authpw/authid be used to satisfy Apaches Basic Authenticiation as well?%0a%0a!! Sending a request to upload a file to a page%0a%0aThe following fields may occur in a request to upload a file attachment to a wiki page.%0a%0a(:table cellspacing=5px:)%0a(:cellnr width=15%25:)'''Field=%3cvalue>'''%0a(:cell width=15%25:)'''Example'''%0a(:cell width=70%25:)'''Note'''  \%0a%0a(:cellnr:)@@n=%3cGroup>.%3cPageName>@@%0a(:cell:)@@n=PmWiki.SandBox@@%0a(:cell:)''Mandatory''. \%0aThe name of the destination page of the write request. \%0a%0a(:cellnr:)@@action=postupload@@%0a(:cell:)@@action=postupload@@%0a(:cell:)''Mandatory''. \%0aOne of the two fields that signals that this is an upload file request. \%0a%0a(:cellnr:)@@uploadfile=%3cfilename.ext>@@%0a(:cell:)@@uploadfile=/c/myfile.gif@@%0a(:cell:)''Mandatory''. \%0aThe name of the file to be uploaded in the POST request sent to PmWiki. \%0a%0a(:cellnr:)@@upname=%3cfilename.ext>@@%0a(:cell:)@@upname=altfilename.gif@@%0a(:cell:)''Optional''. \%0aThe uploaded file will be called this name within PmWiki. \%0a%0a(:tableend:)%0a%0a%0a!! Real-world examples%0a%0a!!! Using curl%0a%0aUsing curl to create a wiki page one would:%0a%0a[@%0acurl -d "?n=Main.WikiSandbox&text=TestingWiki&action=edit&post=1&author=AuthorName" http://localhost/pmwiki.php/Main/WikiSandbox%0a@]%0a%0aNote: the value for 'text' is assumed to already be urlencoded e.g. [=%2520=] for space.%0a%0aUsing curl to upload a file called testing.txt to the SandBox page one would:%0a%0a[@%0acurl -F n=Main.WikiSandbox -F action=postupload -F uploadfile=@/c/testing.txt -F upname=alt-name.txt http://localhost/pmwiki.php/Main/WikiSandbox%0a@]%0a%0aNote: The AT (@) character before the file is required.%0a%0a!! Notification of problems%0a%0aIn response to a post by Christian, Patrick wrote on 2006-03-09%0a--> [@%0a%0a> As an aside, I was using pmwiki-mode for Emacs, which unfortunately meant%0a> that I got no warning that the the edit post was blocked :-(%0a> %0a> That finally leads me to the following suggestion: Could PmWiki output%0a> some kind of error message relatively early in the HTML which you get%0a> after an unsuccessful post? This message could simply be an embedded%0a> HTML-comment as far as I'm concerned.%0a@]%0a%0a-> Sure, I can probably add that somewhere -- likely a comment in the %3chead>%0a   section.%0a%0a   The other thing to look for is that a successful post always results in a%0a   redirect (i.e., status 302 or 301 or something), while an unsuccessful%0a   post results in a 200.%0a%0aChristian's comment:%0a* A redirect does unfortunately not give an indication as to why the save%0a  didn't work.%0a%0a!! Accessing a password protected page%0a%0aFrom Patrick in post on the PmWiki user's list on 2007-06-28.%0a-> [@%0a> If you're using curl as a command-line tool, try the -d option:%0a>%0a>    curl -d authpw=banana http://my.wiki.org/ProtectedGroup.DataPage%0a>%0a> This generates a POST request for the page, exactly as if someone%0a> had filled in the authorization form.%0a@]%0a%0a!! Contributors%0a%0a*%0a*  [[~Smc]] - Added file upload details and real-world examples using curl.
time=1236188487