[pmwiki-users] Page file formats

[Patrick R. Michaud]

On Thu, Aug 24, 2006 at 02:20:38PM -0400, The Editor wrote:
> Thanks for the info Patrick!  A few additional questions though...
> 
> On 8/24/06, Patrick R. Michaud <pmichaud at pobox.com> wrote:
> > > 1)  How does one use page variables in recipes.  For example I'm wanting to set
> > >
> > >       version={$version} ordered=1 urlencoded=1
> >
> > Use the FmtPageName() function, or the PageVar() function.
> 
> Sorry to be dense but after several tries could not figure out how to
> extract the version # so I could set it via my recipe. After looking
> at the docs, my best try was:
> 
>         $myversion = PageVar($datapage, $version, $myversion = ' ');

Ok, I'm confused.  What is you're looking for?

    1. The version of PmWiki being run?  -->  $Version
    2. The version of PmWiki that was used to save the page?
       Not currently available, but can be added if you really need it.
    3. To be able to save a page with a correct PmWiki version number?
       Use WritePage(), or use "version=$Version ordered=1 urlencoded=1".
    4. To be able to save a page with a different PmWiki version number?
       You can write whatever you want, as long as it starts with "version=".

> > > 5) How do you retrieve the page creator's "host" ip address in a
> > > recipe function?
> >
> > The page variable {$LastModifiedHost} returns the ip address.
> > Or, use the 'host' page attribute for a page.
> 
> Actually, I'm wanting to put the ip address into a new page that is
> being constructed.  I need something like
> 
>        $MyIP = $GET[ip address];

PmWiki's WritePage() does this already.  However, you can get the
IP address of the current visitor by using $_SERVER['REMOTE_ADDR'] .

> > > 6) There does not seem to be any indication of the order of parameters
> > > in the Pmwiki/PageFileFormat documentation.
> 
> Guess that explains what ordered means!  :)  Of course I noted even
> with ordered=1 the title tag seems to work out of order.

It's probably okay for the attributes to be in non-alphabetic order
as long as they all appear before any of the page history items.
However, if you aren't saving any page history into the page
file, I suggest being on the safe side and just using ordered=0
in case the alphabetic order requirement is needed in the future.
(The ordered=1 is used to optimize page reads by not reading in
parts of the page history that isn't needed.  But if there's no
page history, then the value of ordered= doesn't currently make
a significant difference, so ordered=0 will be safer in the long
run.)

> > > 7) The docs say that in the text string, newlines must be converted to
> > > %0a and %'s to %25.  Is there a pmwiki function that automatically
> > > does that?
> >
> > I simply use . . .
> 
> Great, that should solve some data entry problems.  I know line breaks
> break the recipe.  Haven't noticed problems with %'s or <'s.  Will
> test some more just to see.

We have to encode % so that we know the difference between %0a
and a normal percent sign.  And we encode < because otherwise
people can embed executable <?php tags into data files that
might be directly accessible from a browser (and would therefore
allow arbitrary code execution on the server).

> My hesitation to switching over to WritePage() is mostly having to
> change everything when it is all working so well...  But on a
> practical note--one feature I wanted was to be able to have users
> write data to a wiki page they could not edit or read.  (I used wiki
> pages so admin's could edit--but users shouldn't mess with them). I
> suspect WritePage() requires authorization to work.  Is there a way
> around that?

ReadPage() and WritePage() are "low-level" calls, they read or
write the page, and that's it.  Authorization is handled by the
individual HandleXYZ actions.  For example, the check for an
author's ability to edit or save a page is performed in HandleEdit().

> Assuming there was a way to do it, and assuming I had the text value
> of the page prepared as string $data, would the format be as simple
> as:
> 
>          WritePage($datapage, $data);

More like:

    Lock(2);
    $page = ReadPage($datapage);
    $page['text'] = $data;
    WritePage($datapage, $page);

> This would automatically clearstatcache, do the pageindexing, set the
> title, and pull in all required page formatting values?  

It currently doesn't set the title or update the pageindex.  
That would be done with:

    Lock(2);
    $page = ReadPage($datapage);
    $page['text'] = $data;
    $page['title'] = $title;
    WritePage($datapage, $page);
    PageIndexUpdate($datapage);

The things that WritePage *does* do for you:

    - call clearstatcache
    - write pages in the correct format
    - adjust file permissions as needed
    - create needed intermediate directories (e.g., for sites
      that have pagefiles separated into per-group directories)
    - gracefully handle disk full or other write errors
    - verify that the file was written okay
    - prevent writing into a pagefile while another 
      process may be reading it

Pm