[pmwiki-users] 2.2.0: add Site.SiteHeader and Site.SiteFooter

Mon Jun 18 13:54:05 CDT 2007

On Mon, Jun 18, 2007 at 10:00:06AM -0400, Ben Wilson wrote:
> Having combed through the recent message traffic, I see no clear
> consensus. Is there a PITS where the various options can be listed and
> voted/commented upon? There appears to be interest in _some_ site-wide
> group (I join that crowd). However, the obvious problem lies in how it
> is named.

You're correct that there doesn't seem to be much consensus, but part
of that is due to confusion arising from the varying interpretations 
available (which I failed to recognize in my original post).

So, I'll try to summarize the thread here, provide some options,
and we can all reflect on those.  Also, to avoid having to say
things like "GroupHeader and GroupFooter" throughout the document,
I'll speak only of headers here with the understanding that the
same rules apply for footers.

Currently, PmWiki defaults to having a GroupHeader page in every 
group; the contents of the group's GroupHeader page is automatically 
added to the top of the page's markup when the page is displayed.  
This is useful for having content automatically added to every page
in a group.  There's also a (:nogroupheader:), which allows a
page to prevent the GroupHeader being added.

There are a couple of recipes that allow this capability to
be extended on a site-wide basis -- i.e., to have a special page
that is automatically added to the markup for all pages on a site,
as opposed to just within a group.  I was looking to adopt one
of these as a PmWiki core default.  As Ben mentions, there's
widespread interest in this.

There are two major models we can follow here, which I'll describe
below.  Keep in mind that regardless of which model PmWiki chooses
as an out-of-the-box default, it will always be possible for a
site administrator to choose a different one.

-----

Option 1:  A page that acts as a "fallback GroupHeader" when
a group doesn't have one.  In this scenario, when viewing a page,
we first look for a page named GroupHeader in the current group,
if that exists we use it, otherwise we use the "fallback" page
if it exists.

A group that didn't want to use the fallback page would simply
create its own GroupHeader page.  A group that wanted to add
markup from both the fallback page and the group's GroupHeader
would use an (:include:) directive to include the fallback page.

The (:nogroupheader:) directive would suppress the header text
altogether -- neither a per-group GroupHeader nor the fallback
page would be added.

There's substantial precedent for an approach like this one...
most skins display group-specific SideBar pages, and fall 
back to Site.SideBar if a group-specific page doesn't exist.

-----

Option 2:  A page that is automatically added to the beginning
of every page's markup, regardless of any group-specific GroupHeader
page -- i.e., a "site-wide header".  

If this approach is taken, then there as question as to whether 
the site-wide header should be affected by (:nogroupheader:),
or if it should have its own (:nositeheader:) directive.

If we use (:nogroupheader:) to control the site-wide header text,
it then becomes difficult for a group to suppress the site-wide
header.

If we introduce a separate (:nositeheader:) directive, then
there's a question (and potential confusion) as to the sequence
of processing -- should a group be able to suppress the site-wide
header with (:nositeheader:), or should the site-wide header be
able to suppress the per-group header with (:nogroupheader:)?
(We can't do both.)

-----

To try to add some further clarity, my use of the term "header"
here is meant to strictly refer to "markup that is automatically
added to the beginning of a page's text when it is displayed
using ?action=browse".  I'm not referring to the masthead, logos,
title, or other items that are typically provided by a page's skin.
(But see my postscript below for a related topic.)

Along these lines, several people have suggested using the
name "PageHeader" instead of GroupHeader or SiteHeader, but
I'm *very* disinclined to do this.  In the code and documentation, 
PmWiki has consistently used the phrase "page header" to refer to the
portion of the skin template that appears at the beginning
of the <body> section of an HTML page.  For example, templates
use , , ,
etc.  I don't want people to be somehow confused into thinking
that pages named "PageHeader" are somehow related to 
 in skin templates.

Similarly, I'm very disinclined to any proposals that 
greatly increase the number of pages involved or that an
author might need to be familiar with to make things work.
So, rather than introduce a plethora of pages to try to handle
every conceivable situation, I'd rather keep the defaults
very simple and complexity for recipes for those who want/need it.

So, that's where I see things standing.  What we have left to do
is to decide which option above (if any) we might consider using 
as a PmWiki default, and then how to name the sitewide header
page so that it makes sense within that option.

Comments welcomed.  I've put up a voting page at 
http://www.pmwiki.org/wiki/Test/VoteOnSiteHeader
where people can indicate their preferences on the various
options available.

Thanks,

Pm