[Pmwiki-users] skins

[Nathan Jones]

Hi Patrick,

I really struggled with the $PageTemplateFmt scheme in PmWiki1.
Specifying a path to a .tmpl file drove me nuts, and so did the fact that
some CSS was in pub/skins (eg. pmwiki.css) and some was in pub/css (eg.
stdlayout.css).

All I wanted was to make a new directory for all layout and CSS stuff for
my site, then refer to it by one name (ie. "custom" instead of
"pub/skins/custom/template.tmpl").

>The $PageSkinFmt approach (PmWiki 2.0.devel16)
>----------------------------------------------
>
>Q1: The problem still exists that an administrator cannot modify files
>    "in place" but must make a copy.

Hmm. Is it feasible to have an equivalent of what happens with wiki.d and
wikilib.d? That is, the default that is installed at installation time
is only used if no customised version exists. The tricky part is
figuring out how to implement this, given that the CSS files must be
accessible via a URL. Also, you want pub/skins/pmwiki to be created up
front so that admins have something to copy...

>    put it in the correct location (pub/skins/myskin), and set $PageSkinFmt
>    to the correct name (i.e., without the 'pub/skins/' prefix).

This is not any harder than setting $PageTemplateFmt to a path and
filename. As long as documentation says that $PageSkinFmt is just for the
skin name (not full path) and shows an example, admins will cope.

>    Note that many people who know how to copy individual files can get
>    easily stumped when it comes to copying directories, especially if
>    they don't have shell/command line access to their server.

I don't have shell access. In my FTP client, I don't know how to make a
copy of a file on the remote system: I'd have to download it and upload
it with a different name. I don't believe that doing the same for a
whole directory is significantly more dificult in most FTP software.

Additionally, I think that (for me at least), anxiety is reduced by not
messing around in pub/skins/pmwiki at all.

>Q3: The variable used to specify the skin ($PageSkinFmt) doesn't seem
>    to have any direct correspondence to the name of the template file
>    used to control the layout (screen.tmpl).

Why should it? I find it comforting to know that there is a default name
for the template file, so all I have to deal with is the directory name.
Even with PmWiki1, I was a bit confused about this. I expected the
template name to be fixed so I only had to think about the skin name.

Also, to my mind, a skin is not just a template, but a complete layout,
with template, CSS and logos.

>(One possible exception is that installing cookbook skins may be
>somewhat easier in this approach.)

I've never installed a Cookbook skin, but I remember feeling unsure about
how I would. A standard instruction of "upload the files to a
directory and set $PageSkinFmt to the skin name" sounds like a big
advantage to me.

>I really noticed this issue when trying to write the LayoutBasics
>documentation--everything is okay until you get to the steps that say
>"make a copy of the pub/skins/pmwiki directory" and "set $PageSkinFmt to
>point to your new directory".  For example, if someone copies 
>pub/skins/pmwiki to pub/skins/myskin (and a new admin may say "uhhh,
>how do I do that anyway?), then sets $PageSkinFmt to 'pub/skins/myskin',
>then things don't work and it's not terribly obvious why.

This is an argument for more explanatory documentation, not for a
different scheme. The solution is to explain the basic steps (copy
directory, modify contents, set variable), then elaborate by showing how
to copy a directory, what files the admin may want to change, and what
needs to go in config.php.

I wrote a draft, but it's too big to post here, so I changed
Pmwiki/LayoutBasics. Feel free to restore old version, or edit as
desired.

>So, I think some other approach is needed.  A big part of the confusion
>is that PmWiki has to read templates in terms of *filenames* while the
>template has to specify the locations of graphic elements and CSS files
>in terms of URLs, and so names that work for one don't always directly
>map to the other.

This was also a possible cause for confusion in PmWiki1 and is not easily
avoidable. However, explanations in the documentation should help. Also,
admins who know enough HTML to modify a template file should be able to
understand such an explanation fairly quickly.

-- 
Nathan Jones