[Pmwiki-users] SHTML-like templates for PmWiki

Patrick R. Michaud pmichaud at sci.tamucc.edu
Sat Dec 14 09:56:34 CST 2002

I'm not exactly sure I understand all of the details of Niall's modification--
it sounds to me like he's making it possible to set the PmWiki headers/footers
without having to embed HTML within PHP variables (e.g., $PageHeaderFmt,
$PageFooterFmt, etc.).  I had been thinking of doing something along this
lines but in a slightly different form...

Right now $PageHeaderFmt (and many of the other similar variables) can 
contain either HTML text to be printed or the name of a PHP function to be 
called to generate the header.  As Niall has noted, this can be a bit
cumbersome because a site administrator has to know a little bit about
PHP to be able to customize the look/feel of PmWiki.  

So, I was going to propose that the variables such as $PageHeaderFmt
and $PageFooterFmt be allowed to contain one of:
  1. the name of a PHP function to be called to generate the header,
  2. (new) the name of a file to be output to generate the header, or
  3. a string containing HTML to be printed.

The addition of the 2nd option means that someone could put in local.php:

    $PageHeaderFmt = "myheader.html";
    $PageFooterFmt = "myfooter.html";

and the contents of myheader.html and myfooter.html on the local filesystem
would be output for the header and footer respectively.  Of course, the
files could also be PHP files containing PHP commands and variables to be

There are some differences between this and what Niall has suggested,
so comments are very welcome.  I like Niall's idea of being able to describe
the entire output page layout in a single HTML-like file and would like
to pursue that (perhaps with a slightly different syntax).


On the <--#pmwiki var="ScriptDir"--> syntax, I'm not so sure this is the
right way to go about it.  Rather than introduce the SHTML syntax
into PmWiki and force PmWiki to parse/process it, let's find a way to 
just drop directly into PHP again somehow.  I.e., I think that writing

	<?php echo $ScriptDir; ?>

is as easy to learn as writing

        <!--#pmwiki var="ScriptDir"-->

even for someone who is unfamiliar with PHP.  For those with more
familiarity with PHP this would be a huge win, because they can embed
expressions and entire PHP statements.


As long as we're doing it this way, why not just use the PHP syntax
for Niall's proposal from the outset?  Let the administrator create
an HTML file containing embedded PHP instead of SHTML.  This results
in the following replacements for Niall's directives:

    <!--#include file="foo.inc"-->
    <?php include("foo.inc"); ?>

    <!--#pmwiki body-->
    <?php PrintWiki(); ?>

    <!--#pmwiki var="ScriptDir"-->
    <?php echo $ScriptDir ?>

This has the *huge* advantage that we don't ever have to parse the
text looking for the directives, since PHP already has this built-in.


Continuing from here, would anyone object loudly if I placed the
per-group/per-page customization semantics directly into PmWiki,
rather than leaving it up to the administrator to do via local.php?
How this would work:  PmWiki will load local.php, followed by
either local/Group.PageName.php or local/Group.php if they exist.

Building from this, we can then allow any of the localization files
to be an HTML template file for the page layout (possibly containing
the <?php...?> directives I gave above), instead of containing only
PHP variable settings.  Thus, if the file local/FooGroup.php contained:

	<h1>My custom header!</h1>
	<?php PrintWiki(); ?>

then all pages in FooGroup would be printed according to this template.
Of course, the localization file could contain other php directives;
e.g. to print global variables, include other files, and the like.  
If the combination of localization files didn't generate any (HTML) 
output then PmWiki would proceed to generate the page using its 
internal default header/footer scheme.  

I like it.  I like it lots.  

Niall--can I get a copy of the local modifications you created to take a 
look and possibly steal some ideas?


On Fri, 13 Dec 2002, niall b durham wrote:
> Hey guys,
> For what its worth, I recently made a new local modification for
> PmWiki.  I figured I would describe it on this list in case anyone
> else was interested in it or had any comments.
> The gist of it is that it is a SHTML-like template system for the
> PmWiki pages.  Currently, it supports a default, group-specific, or
> page-specific templates (just like pgcust.php) with the more specific
> template overriding the less specific (if any).
> The template files contain HTML and support a few simple directives.
> The SHTML file inclusion directive:
>     <!--#include file="foo.inc"-->
> [It doesn't support the 'virtual=' argument, though.]
> It has a means to substitute in the values of PmWiki variables (any 
> global variable is fair game--I don't know whether or not this is a 
> good idea, but that's the current implementation):
>     <!--#pmwiki var='ScriptDir'-->
>     <!--#pmwiki var='HTMLHeaderFmt'-->
> The page is divided into the header/footer around the PmWiki page,
> using the following tag:
>     <!--#pmwiki body-->
> This is (obviously) nothing that couldn't be done before.  I wrote
> it because I was interested in a means to easily control all the 
> surrounding layout/HTML of the PmWiki pages that did not require PHP 
> coding.
> Just in case it isn't apparent, the template files are not editable
> via the PmWiki mechanism and are off in a separate directory (not
> world-writeable).  
> I figured I'd offer it back to the collective in case anyone is 
> interested.
> Any feedback (heh, even if its just to say this is a lame idea :) 
> appeciated.  Especially w/ regard to syntax.  I'm uncertain about the 
> variable substitution markup.  However, something less-explicit (e.g., 
> '$ScriptDir') seems too open to mis-interpretation.
> Hasta,
> Niall
> p.s. I'm going out of town tomorrow (Sat., 14th), so if I don't reply
> promptly don't take it the wrong way.

More information about the pmwiki-users mailing list