[Pmwiki-users] page format variable redesign

[Patrick R. Michaud]

As I've mentioned to a few others in the past several weeks, I've been
planning a substantial redesign of the way that page layouts are created
in PmWiki.  I'm getting ready to start implementation of the new layout
features, but wanted to share the design with others to provide an
opportunity for reaction and comments.  I'll warn in advance that this
is a long and detailed message.

To alleviate any fears that might arise from reading this, I should
state up front that I'm expecting the new design to be fairly compatible 
with most existing PmWiki installations.  Part of the reason for me
putting this message out is to gauge if this is true or not and see if
anyone says "hey, that won't work for me!"  However, the new design 
uses a few simple rules to generate some fairly complex results, so 
it may be a bit difficult to follow parts of my description below.  
If so, just bear with me and trust me that the existing configuration
variable scheme will still be supported with the new design, even though
it make look very different as described below.

To begin with, I'll describe what I'm intending to do with the variables
that specify output, such as $PageHeaderFmt, $PageFooterFmt, $HTMLHeaderFmt,
etc.  Currently, each of these variables are strings that are to be
output for different components of a wiki page.  At present there is
one special case:  when displaying a wiki page one can set 
$PageHeaderFmt and $PageFooterFmt to be function names to be called 
to generate the headers.  Except for this special case, each of the 
"Fmt" variables is output after substituting certain $-sequences
such as '$Group', '$Title', '$Titlespaced', '$PageUrl', '$ScriptUrl', etc.

This approach has worked well, but people often want a bit more
flexibility and to be able to do things such as:
  - display multiple wiki pages in a single HTML document, e.g., to have 
    navigation menus and footer content stored as wiki pages,
  - use the contents of local .html or .php files, rather than storing the
    HTML as text strings in variables,
  - create custom output functions, and
  - combinations of the above.

Thus, I'm proposing to change the processing of the $...Fmt output variables
so that the values (after $-substitutions) can be any of:
  - HTML text to be output, such as '<h1>$Group</h1>',
  - "file:filename.ext" to output the contents of filename.ext,
  - "function:SomeFunction" to call SomeFunction() to generate output,
  - "wiki:Group.PageName" to output Group.PageName in HTML, or
  - an array containing any sequence of the above (or other arrays).

Thus, for example, a simple page header could be done the same as now, by
specifying::
    $PageHeaderFmt = '<h1>$Group / $Title</h1>';

However, to generate a header from an HTML file on disk (e.g., as created
by an HTML editing package):
    $PageHeaderFmt = 'file:path/to/myheader.html';

Or, to call a special PHP-function to output the header:
    $PageHeaderFmt = 'function:MyHeaderFunction';

And to add the contents of a 'LeftMenu' page in a table cell to the left
of the standard wiki content:
    $PageHeaderFmt = array(
      '<h1>$Group</h1><table><tr><td width="20%">',
      'wiki:$Group.LeftMenu',
      '</td><td>');
    $PageFooterFmt = '</td></table>';

That's the basic model.  Thus, formatting variables will continue to work 
as they have before, but the administrator will also have the option of 
specifying files, functions, and other wiki pages that should be included
in the output.

----

>From here I'll describe how this basic model can be expanded to allow
extensive customization for all pages PmWiki produces, including the
edit forms, search result pages, etc.  The explanation gets a bit 
complex and technical here, and is really intended for administrators 
who might need even more control over the page layout process than what
PmWiki's existing variable structure allows.  So, don't worry too much 
this starts looking really complex--for most situations you'll never
have to deal with the things I'm describing below.

To look at page generation as a whole, I'll begin with a brief review 
of the structure of any HTML document.  A script creating an HTML document
must basically produce the following parts:

HTTP Headers		Content-type:, etc.
document type		<!DOCTYPE ...>
header			<html><head>
  document titl   	  <title>...</title>
  stylesheets		  <style>...</style>
  other header tags	  <meta ...>
body			</head><body ...>
  HTML markup		  <table>, text, <a>, etc.
end of document		</body></html>

PmWiki has traditionally allowed specification of the document output
using a set of configuration variables for each section.  For
example, to display a wiki page (?action=browse):

HTTP Headers		Content-type:, etc.		$HTTPHeaders
document type		<!DOCTYPE ...>			$HTMLStartFmt
header			<html><head>			     "
  document title   	  <title>...</title>		$HTMLTitleFmt/$WikiTitle
  stylesheets		  <style>...</style>		$HTMLHeaderFmt
  other header tags	  <meta ...>			     "
body			</head><body ...>		$HTMLBodyFmt
  header		  <table>, text, <a>, etc.	$PageHeaderFmt
  wiki content                 "			  PrintText() function
  footer		       "			$PageFooterFmt
end of document		</body></html>			$HTMLEndFmt

The other actions such as ?action=edit, ?action=search, etc. follow this
same model except that the body is generated from different configuration
variables such as $PageEditFmt, $PageSearchFmt, etc.  In fact, PmWiki
has a special function called StartHTML() that it uses to generate
the beginning of any HTML document from the $HTMLxxxFmt variables.

However, with the new model this can be greatly simplified because of
the array structuring feature I described above.  For example, the 
beginning of an HTML document can be specified as (if you don't 
understand the ampersands below just pretend they aren't there):
    $StartHTMLFmt = array(
      &$HTMLStartFmt, &$HTMLTitleFmt, &$HTMLHeaderFmt, '</head>',
      &$HTMLBodyFmt);

Thus, the variable $StartHTMLFmt would be used to output the "header"
for any HTML page, including the title, style sheets, meta tags, etc.
As described above, each of the $HTMLxxxFmt variables could be arrays
or use the "file:" and "function:" semantics described above.

However, if an admin doesn't like the way PmWiki has organized its 
variables for producing the header, she can always define her own.  
For example, to completely customize the headings with a MyStartHTML()
function, she can simply set:
    $StartHTMLFmt = 'function:MyStartHTML';

If the admin just wants to generate the header from another php or 
html file, she can do:
    $StartHTMLFmt = 'file:htmlheader.php';

Finally, this whole concept could be generalized still further, to allow
an administrator to take over the entire page generation process.
For example, the default value for displaying wiki pages could be:
    $PageBrowseFmt = array( &$StartHTMLFmt, &$PageHeaderFmt, 'wiki:$PageName',
      &$PageFooterFmt, &$EndHTMLFmt);

However, if the admin wants to have her own function called 
MyPageOutput() that completely takes over the process of displaying 
a wiki page, including the headers and footers, she can specify this with:
    $PageBrowseFmt = 'function:MyPageOutput'

Or, to make use of the standard HTML headers but call the function
to generate the rest:
    $PageBrowseFmt = array( &$StartHTMLFmt, 'function:MyPageOutput' );

----

Anyway, that's the direction I'm thinking of heading.  If it looks
really complex--don't worry, it's a lot harder to explain the idea
than it will be to use, and I'm planning to generate lots of 
customization examples.  One of the most frequent requests I get
is "can I see some examples of customization", and I'm hoping to
create lots of examples but want to make sure I have the basic model
down first.

Also, I'm sure there will be some changes to the overall scheme as I
get into the implementation details, so don't hold me too strictly
to what's I've outlined above.  It's just a design outline at this
point.  But ultimately I think this approach will provide greater 
ease and flexibility for customizing PmWiki's output.

As usual, I'm eager to hear comments, questions, and other opinions.

Pm