[Pmwiki-users] Modular configurable skin

Sat Jan 8 21:58:20 CST 2005

I was playing with templates today, and got a really cool idea, but I
can't implement it without help.

What if the new default skin for PmWiki2 was modular, that is, lots of
little CSS files that got linked or imported according to what the
site admin wanted, instead of a monolithic lump?  That would make it
ridiculously easy to customize PmWiki's look without knowing a scrap
of HTML or CSS.  Problem: how does the admin find out what options are
available, and select what they want?

The simple, and bad way: have the admin comment or uncomment the <link
/> and @import rules in the skin's .tmpl or .php file, and caution him
never to delete any lines.  This is bad because:
1. his changes get overwritten when he upgrades PmWiki.
2. having to edit files by hand is a little intimidating for our
target market.

Better way: use a wikipage. This would be a good storage mechanism because:
-existing skin options will not be overwritten when PmWiki is updated,
but the default config will be updated (in wikilib.d) and is available
if needed or wanted
-version history makes mistakes easy to undo
-no shell or ftp access is required, just the ability to edit the wiki
-less intimidating to target market

I tested my idea to (ab)use  to suck data from a
wikipage into the template's <head> tag:
1.  Into marathon.tmpl, I put  where
the stylesheet link used to be, followed by <style
type="text/css"> --> </style>, for
drop-in styles.
2. I filled in the relevant pages such that I should have been able to
tell what worked and what didn't. I made sure to surround the text
with [==] to keep PmWiki from changing it.
3. I changed the wiki's skin, and lo, it did not work. My stylesheet
links in Skin.MarathonConfig did not work because the <>s had become
&lt;s and &gt;s.  My @import and style rules in Skin.AddStyle didn't
work because of the <p></p> tags that got added.

So, if my modular default skin idea is to fly, I need your help -- I
need a magic routine that puts the style information from the
wikipages into the template correctly.  But I am ambitious; if we have
to have a magic routine then we ought to make this system even better.
Naive admins could make mistakes when commenting or uncommenting
lines, because both HTML () and CSS (/* comment */)
comments are surrounded, not just prefixed with #.  That's big, stupid
pitfall.  Besides which, an options list like this is unnecessarily
repetitive and intimidating for non-coders:

/* <link rel="stylesheet" type="text/css" href="font-face-verdana.css" /> */
/* <link rel="stylesheet" type="text/css"
href="font-face-times_new_roman.css" /> */
<link rel="stylesheet" type="text/css"
href="font-face-h_georgia-b_verdana.css" />
<link rel="stylesheet" type="text/css" href="sidebar-orientation-left.css" />
/* <link rel="stylesheet" type="text/css"
href="sidebar-orientation-right.css" /> */

I think they'd find this much easier to understand, and there's a lot
less to mung:

OFF link "font-face-verdana.css"
OFF link "font-face-times_new_roman.css"
link "font-face-h_georgia-b_verdana.css"
link "sidebar-orientation-left.css"
OFF link "sidebar-orientation-right.css"

You can see that there's three parameters:
1. comment out options preceded by "OFF "
2. link for a <link rel="stylesheet" type="text/css" href="something"
/> tag; import for a <style type="text/css"> </style>
3. "filename.css" to be subbed in (without quotes) where the
"something" is in #2.  The quotes are there to make life easier when
someone eventually uses filenames with spaces in this system.

Having a magic routine not only lets us have friendlier options lists,
it lets the skin's config wikipage begin by telling people what this
page does, how to use it, and linking to whatever documentation there
is about what the individual options do.  Then there should be a
separator of some kind, and an anchor to show where the options list
proper begins.  The anchor will allow the magic routine to behave like
(:include:) and fetch just the relevant chunk when I put
 into my template.

We could get two other nifty features as a (free?) side effect:
1. skin options system: if a skin author wants to provide togglable
options of the sort I'm proposing, there will be a standard, friendly
method of listing and toggling them.
2. add whatever CSS you like, without editing stylesheets or
templates, by adding it to a designated wikipage, e.g. Skin.AddStyle. 
(I vaguely remember someone complaining on the list about not being
able to do this, but I can't find the reference.)  This can be
implemented as:
     -a PmWiki feature (have the magic routine add <style
type="text/css"><!-- <!--wiki:Skin.AddStyle--> --> </style> to the
<head> tag automatically after all the other style information)
     -a skin-specific feature (skin author must include <style
type="text/css"><!-- <!--wiki:Skin.AddStyle--> --> </style> in his
<head> tag)

Off the top of my head, these are the options I think enough people
would want to justify their existence:
-base font size (scales all text in skin up or down)
	-small
	-normal
	-large
-font face combinations (prepackaged)
-colour schemes (prepackaged)
-page width
	-narrow
	-medium
	-full
-sidebar display
	-on
	-off
-sidebar orientation
	-left
	-right
-sidebar width
	-narrow
	-wide
-masthead type
	-logo, sitename
	-none

For extra credit, I think people would like having these too, but
they'd need special treatment by the magic routine:
-custom background colour, overriding the colour scheme previously specified
-custom background image, for which the user specifies an image file
and attaches it to the page, or puts the image file in an appropriate
directory and provides a path or url.
-masthead with logo, sitename, and tagline
-masthead with larger image, and sitename (and possibly tagline) as alt text

The many options I'm thinking of provide built-in CSS examples for
people making their own skins, and it should be easier to find the
exact rule that produces a specific effect.  I admit that it might
make the copy-and-tweak method of skin creation a little more
difficult, though.

Anybody got improvements to suggest?  Volunteers for the magic routine
that makes it all possible?  I can do a modular stylesheet.

Bronwyn