[pmwiki-users] variables for customization

[Joachim Durchholz]

Patrick R. Michaud wrote:
> PmWiki centralizes all of that substitute-a-dynamic-value-in-a-string 
> into the FmtPageName() subroutine.  Because some things are extremely
> dynamic, such as the url or group for an arbitrary page that
> is not the current one, those things cannot be simple global PHP 
> variables.  Or, if they do become global variables, they're 
> variables that cannot be trusted to hold a value for very long 
> because some other routine (that may happen to be formatting a
> string for a different page) will come along and change that
> global variable for whatever it happens to be doing.

I agree that globals (if they are used at all) should have a single, 
constant meaning.

In other words, any PHP variable that's visible to config.php or or 
recipe code (that is: PHP globals) should refer to the current page.

I agree that there's confusion potential for placeholders used in 
FmtPageName strings. However, I don't draw the conclusion that the 
situation should be left as is; rather, I'd suggest that different 
placeholders be used. Something akin to
   $PageName - current page name (equivalent to PHP $pagename)
   $LclPageName - the page name from local context
     (i.e. the page name that's submitted as parameter to FmtPageName)
Notes:
1) The core of this proposal is that there are two variables: one for 
accessing the value in the PHP global, and one for accessing the 
parameter value submitted to FmtPageName. The actual names used for the 
placeholders isn't too important, other than that it should match the 
names used in the PHP code (to prevent the obvious confusion potential).
2) It's debatable whether FmtPageName even needs access to PHP globals. 
PmWiki has done fine without it. However, I'd still advocate doing it: 
first, it may allow people to do novel and wonderful things, second, it 
makes using format strings easier to use, because we don't have to 
remember (or even know) the differences between globals and placeholders 
anymore. We still have to remember that many globals aren't available as 
placeholders (that difference is unavoidable), but if we see a 
placeholder used in a format string, we can be sure that our knowledge 
about the corresponding PHP variable is transferrable to the placeholder.

> In chosing the syntax for FmtPageName(), it seemed pretty obvious 
> that to substitute the values of global variables we should use 
> something like $VarName.  It also made good sense to use $[phrase] 
> to indicate an internationalization substitution.

I have no problems with using $ as a placeholder indicator. The analogy 
is good enough to make that a useful convention, and I fully agree with 
your reasoning that it's the Right Choice.

I don't think that consistency is a bad thing. It's just that half a 
consistency leads to more confusion than being inconsistent in the first 
place :-)
In other words: if it looks the same, it should mean the same. If I find 
$PageName in a format string, the naming is consistent with 
(case-insensitive!) $pagename in the PHP code, so we expect the 
semantics to be consistent. It can take a dozen exchanges if such a 
misunderstanding isn't immediately detected, and with associated 
confusion. (The problem is enlarged in my personal case because 
confusion leads to frustration, and frustration to red-hot anger. I'm 
trying to tone that down, but I'm pretty sure it still leaks. Which, in 
turn, invites anger on the other side - my apologies for that, I know 
it's a bad habit but unfortunately it seems to be hardwired in my 
personality. I hope everybody will bear with me.)

> As far as keeping thing straight for those who need to understand
> the differences, there are really only three things to know.  
> 
> 1.  Things like "{$Group}" and "{$LastModified}" are *markup*.  
>     You can call them "variables" or "markup variables" if it pleases 
>     you, but they don't really exist as variables anywhere in the 
>     PmWiki code, nor is there an enforced correspondence between them
>     and any PHP variable.  They're just substitutions in the Markup() 
>     sequence, the same as [=...=] or (:include:) or (:table:) or 
>     any other markup.

My suggestion is to establish such a correspondence. If there isn't a 
PHP global, create one and fill it with the data. Since it's markup, it 
should be constant enough that initialising it once before invoking 
config.php should be possible.

> 2.  A limited set of $-substitutions -- basically anything that 
>     corresponds to a page attribute -- are not PHP variables and 
>     are only available through the FmtPageName() subroutine.  
>     The complete set of these special substitutions is $Group, 
>     $Name, $FullName, $PageUrl, $Title, $Titlespaced, $Namespaced, 
>     $Groupspaced, $LastModifiedBy, $LastModifiedHost, and $LastModified.  
>     These items cannot just be standard PHP variables because often
>     PmWiki needs to obtain the url, name, group, title, etc. of a page 
>     other than the one currently being viewed by a browser.

Here my suggestion is to make this data available as PHP globals. It's 
too useful in config.php and module/recipe code, and PmWiki knows best 
how to compute them.

To avoid confusion, there's the further suggestion that the FmtPageName 
substitutions that refer to the page name as given in a parameter should 
be named differently.
It could be a prefix to the placeholder name, be it $LclPageName or 
$XPageName or whatever.
I'm aware that such a change requires going through all of PmWiki and 
maybe even some recipes, so it's nontrivial and tedious work. However, I 
think it's worth the effort - it makes finding one's way in the PHP code 
much easier.

> 3.  With minor exceptions, basically everything else you see that
>     looks like $VarName is a PHP variable.

No suggestions here :-)
... well, except that that "with minor exceptions" bit makes me raise an 
eyebrow. Which exceptions? How do I identify them if I happen to stumble 
over one?

Regards,
Jo