[pmwiki-users] Problems with the embedded CSS in pmwiki.php

[marc]

Patrick R. Michaud said...
> On Fri, Oct 27, 2006 at 04:17:49PM +0100, marc wrote:
> > Something that's been bothering me for a while, but might be the result
> > of misunderstanding something is the CSS and style ordering.
> > 
> > Currently, in a skin template,
> >   <!--HTMLHeader-->
> > must come after the skin's
> >   <link rel='stylesheet' ... skin.css
> > because HTMLHeader adds local.css - and other CSSs that might be listed
> > in $PageCSSListFmt.
> 
> Yes, this is the preferred mechanism.

Okay, I'm going to attempt to convince you that we need a little
movement on this :-) 

Just to be clear, the recommendation is (something like):

<link rel='stylesheet' title="Skinname" href='$SkinDirUrl/Skinname.css' 
type='text/css' />
<!--HTMLHeader-->
</head>

This means that the skin template is always overridden by PmWiki's
embedded styles. This wouldn't be a problem were PmWiki's embedded
styles restricted to classes or ids, but they include ul, ol, pre, dl
and p. In addition, some classes are intrinsic to PmWiki, and these too
can be added to the list - e.g. .vspace, .indent, .outdent).

This presents a problem where the "design" task is performed by someone
other than a PmWiki admin, since it means that the output produced by
the template might be other than as defined in the template. (I know
that all of us here can deal with, but that's not the general case.)

For completeness, HTMLHeader also outputs the embedded styles (and JS,
etc.) from recipes, and other local CSS customization files. As I
understand it, the contents of the following arrays:

$HTMLStylesFmt
$HTMLHeaderFmt
$PageCSSListFmt

What I suggest is that the skin template should always "win". Now, that
probably means that it should come after all styles and JS, but before
local customizations.

Can PmWiki facilitate this? As you point out below, it can.

> > The problem with this order is that the pmwiki.php embedded
> >   $HTMLStylesFmt['pmwiki'] = "
> > then overrides some elements in the skin template. The problems this
> > introduces then have to be fixed in pub/local.css
> 
> As one might expect with PmWiki, there are other options... :-)
> 
> Short answer:  The short answer is that a skin that wants to 
> override the pmwiki.php embedded styles can do the following 
> in skin.php:
> 
>     global $HTMLStylesFmt;
>     $HTMLStylesFmt['skin'] = "...css overrides here...";

Yes, but then the skin CSS is in two locations. It's not the end of the
world, of course, but it is an inelegant solution and it's a little 
error prone. And the embedded styles are still there.
 
> These definitions will come after the pmwiki defaults, but before
> pub/css/local.css and other administrator-defined styles.
> 
> A skin that wants to completely replace the pmwiki.php defaults
> with its own can do the following in skin.php:
> 
>     global $HTMLStylesFmt;
>     $HTMLStylesFmt['pmwiki'] = '';

This method has the problem that future addition or amendments to
PmWiki's embedded styles are lost. I started down this route and
disliked it because odd embedded styles would pop up from time to time;
say, with the FAQ. The problem being that PmWiki's embedded styles
aren't in a single location, and can't easily be listed.

If all the PmWiki styles were in a single CSS, then it would be easy to
check for clashes and make adjustments. In addition, it's easy to spot
when this file changes, either by a simple diff, or, with something like
Subversion, by being automatically notified.
 
> A skin can also insert its definitions between the default
> styles and administrator styles by using:
> 
>     global $HTMLHeaderFmt;
>     $HTMLHeaderFmt['skin'] = 
>       "<link rel='stylesheet' href='\$SkinDirUrl/skin.css' type='text/css' />";

Ah! I had tried this, but didn't realise I needed the global. Instead, I
had added it to my farmconfig.php (for testing).

This is certainly the best solution in the current setup, imo, but as
I've mentioned, I would prefer to have all PmWiki's styles in one core
CSS.

> > Nevertheless, what I'd like to see is the removal of the embedded
> > CSS in pmwiki.php. Knowing Patrick, I'm sure it's there for a
> > reason, but it sure don't seem purty.
> 
> Long answer:  The reason why pmwiki.php embeds the CSS is to reduce
> the overhead on skin authors and to preserve an upgrade path.

Absolutely. And this is a very good thing.
 
> The styles defined by $HTMLStylesFmt['pmwiki'] are really the
> essential ones that are needed for several of PmWiki's core markups.
> Without these in place, a number of PmWiki's built-in features simply
> won't work.

Yes, I understand.

> In the past many have indicated that we should "dis-embed" the CSS
> from pmwiki.php, and require every skin author to include these
> minimal definitions (possibly modified) in the skin's .css file.

Would it not be better to do as you've noted above and simply add a
<link rel='stylesheet'> for the proposed "core" CSS file to, say,
$HTMLStylesFmt? That way there is no onus on the skin author to do
anything.

> This slightly increases the work required to develop a skin, because
> the skin author has to copy the definitions somewhere.  But more
> importantly, moving all of PmWiki's CSS properties into the skins can
> make future PmWiki upgrades a bit of a pain, because when a style
> definition is added or changed in the core, every existing skin would
> then need to be modified to incorporate the new minimal specification.
> I prefer to avoid that level of coupling between core and skins.

Yes, I can understand that, but that wouldn't be the case with a core
CSS file. At least, as far as I can see... which might not be far
enough.

> The current approach allows skin CSS properties to be completely
> decoupled from CSS properties needed for core and recipe markups.

Absolutely. I wholeheartedly support that statement. Indeed, what I have
suggested increases the decoupling.

I hope I have made a decent case for an alternative approach that
retains this ideal and provides more visibility of what comprises the
core styles, and is, imo, a lot easier to manage. (It is also a little
more efficient - less code generated per page, CSS cached client-side -
and diff'ing PmWiki's embedded style changes from version to version is
simplified.) 

> In fact, in this sense pmwiki.php uses $HTMLStylesFmt[] in exactly the
> same way that recipes do.  $HTMLStylesFmt[] allows module-specific CSS
> properties to be injected into the output without the skin ever having
> to be aware of them, while preserving the capability for skins and/or
> administrators to override the module-specific properties if they wish
> to do so.

Yes, but I, and I suspect other, have no compunction about hacking a
recipe to fit, but simply don't want to do that with the core - it's 
too much work to maintain, especially with multiple sites.

-- 
Best,
Marc