TWiki Using CSS

This is a springboard topic to address the broad area of TWiki and CSS - stylesheets - and overall Web standards compliance. It's long ranging topic, having started in September 2001. The underlying assumption is that it is a good idea to create a complete set of TWiki templates which use Cascading Style Sheets for their presentation and layout definitions. This topic is about how to proceed. For justification (or not) of this project see WhyUseCSS.

If it reads a little strangely right now, it's because it has only been partly refactored. If you see some redundancies, please feel free to remove them, they are after all redundant, and who needs even more redundancies to get in the way? If you see some redundancies, please feel free to remove them, they are after all redundant, and who needs even more redundancies to get in the way? Do remember to be careful about changing the intent of the original author (even, make that especially, if you don't know who that might have been).

Existing TWiki+CSS solutions

Listed by age, eldest first; Status notes current as of May 2004. List is not exhaustive (some other skins also use CSS): please add.

KoalaSkin

tables and CSS hybrid, has been in extensive use on many sites for a few years, known to play nicely with NS4, still developed and supported

SeeSkin

wholly CSS and structural html based, uses SavemultiCgiScript from KoalaSkin, development is stalled, can be used as is on twiki versions older than Jan2004 (newer ones need to patch savemulti)

PatternSkin

wholly CSS and structural html based, incomplete but under active development, prime candidate for TWiki Core default skin (and is available in TWikiAlphaRelease); cann be used as is but some assembly required

FreeSkin

wholly CSS and structural html based, under active development, multilingual, docs and sample CSS are available in portuguese though not on twiki.org (english version is forthcoming)

How to get There from Here

• CssClassNames - towards a canonical list of class and ID names which could be used by all css using skins.

---

TWiki look and feel should be almost entirely (if not completely) driven by INCLUDES from editable TWiki topic pages, ala FlexibleSkin/Plugins.FreeSkin. This may result in the concept of Templates being refactored out of the system or into Topics rather than files. Skins would now become bundles of topics.

TWiki should clearly separate the rendering of pages between the following functions: structure/layout, branding, navigation and content. Any of those items should be configurable and Skin driven. This could result in site administrators combining Layout Skins, Navigation Skins, Content Skins and Branding Skins to create their site experience.

CSS support can be then be applied in varying degrees for all of the above categories. TWiki would not require/dictate any standards for the first three items beyond that provided by default skins. However, for managing content, implementing a base set of tags makes a lot sense. Plugin developers should be required and restricted to using the base set of standard TWiki CSS tags. A plugin that checks content against xhtml tag formatting rules could be utilized for those sites that need to guard against runaway tags.

---

We could use the browser and version declared in the query for selecting a template better suitable to the browser.

The templates could be selected with a mechanism equal to the skin selection already in place, i.e. they could be named: <template>.<skin>.<browser>.tmpl

To even extend this to multiple languages we could use this naming schema: <template>.<skin>.<browser>.<language>.tmpl

---

%STYLESHEET% on TWikiPreferences and each WebPreferences page; potentially even a topic level use of the variable. Let's not forget too that styles are/can be inherited or included, so a site general style can descend to sub-sites (webs) and pages (topics) easily.

As for tying a particular style to a particular template, I think that has plusses and cons: styles can be more general then being used for a particular template.

---

I think for the moment CSS should be used to replace almost everything except tables. So instead of having font tags and background colours etc defined in the programing, all code uses div/span tags if necessary and there is a standard defined set of classes. This way probably 90% of all 'skinning' could be completed using CSS.

---

I like the idea of having browser specific skins. [...]

---

[...] We need an efficient way to filter each of these printf()s through a template to map the meaning to HTML[CSS] markup. Obviously, you don't want one template file per printf() statement... Stripping down the raw HTML so that it just references CSS classes kind of solves this problem. It delegates the format specification to the external style-sheet. But non-CSS devices have to pay the price for this.
In theory, it should degrade gracefully.
In practice,

1. NS4x doesn't handle any serious CSS
2. The format (rendering) often carries meaning, which disappears on non-CSS devices.
   OTOH: this may apply to HTML layout tags as well. Say, you rely on an indented table plus red color to mark-up a warning. What will your b&w WAP device make out of that?
3. PrintUsingPDF (my beloved ;-) will look rather bland...

So a good idea for efficient MicroTemplates could save the day.

---

I would push for TWiki using CSS and defining built-in classes, with the looks designed to match the skin of the current topic.

Your example would be just a

<div class=quote>
   ... the text
</div>

This is arguably not uglier than the %- syntax, and it is standard: users can learn something that they can reuse elsewhere.

For instance, see at the end of http://koala.ilog.fr/wiki/bin/view/Test/WebHome the style given to the blockquotes, with the same text on another web: http://koala.ilog.fr/wiki/bin/view/Koala_Skin/TestBlockQuotes

One could thus define different classes: quote, code, example, error... matching the skin color scheme, which would be very useful for table rows for instance...

Styles should have full control over colors (and also icons) for particular skin and color theme combination. No hardcoded colors in text. [...]

1. %FOO %BAR markup isn't any better in terms of readability and usability, and it's completetely TWiki "proprietary"
2. HTML divs/spans to reference CSS are even more complicated. Yes, there's plenty of literature about it. No, people don't want it, or why would they go for wiki in the first place?

IMHO, the task is to pick the best and most commonly understood idioms from the BabelOfWikis; my vote goes to reStructuredText.

---

it pays to also change this line: <body bgcolor="#ffffff"> to just <body>. This is because embedded styling has precedence over stylesheet styling (and the user agent's (i.e. browser) stylesheet/settings has precedence over both of those - at least per the standard). By changing the body tag thusly, you can change the bg color of all twiki view pages, and/or add a bg image (I used a nice "paper" effect).

Road Blocks

TWiki emits raw HTML

I think the deeper problem is, that plenty of code emits raw HTML.

I certainly concur that the current state of affairs seems to have too much embeded HTML and it feels/seems like its very ad-hoc.

What is emitting raw html? TWiki plugins or perl modules? If it's the former, make some sort of campaign to get plugin developers to use css instead of html tags, or TWiki.TWiki syntax, if feasible.

See HardwiredRDiffColours and HardwiredColours for specific places where colors are hard coded.

Older and Non-CSS Browsers

NS4 [Netscape 4] is full of bugs, not only in CSS. They tend to happen a lot the more you use tables, which is needed if you want some modern layout. I had to fight a lot with the table problems in NS4. Put a blockquote into a topic in KoalaSkin, and you NS4 dies, because the page has too many tables for it.

So my opinion now is that NS4 should be handled like lynx/emacs: give their full functionality, but with a different, minimal, look/layout. The best thing should have skins go either full CSS (well, the subset of CSS understood by modern browsers), or plain style geared for lynx/emacs/NS4. So we must find a way to do this in the engine properly (have it issue html or css depending on the skin in use by the user), and per-user.

---

> ...my experience with KoalaSkin is that you must be quite conservative
> in your use of CSS, if you want to be able to display properly on all browsers.

If "display properly" means "look similar in all browsers", yes, one must be conservative. However in my experience with CSS generally, after I gave up the idea of "must look the same" and adopted the principle of "all text must be accessible to all browsers" you have a lot more freedom in using CSS.

The story which made me a CSS convert: http://www.alistapart.com/stories/dao/

---

I'm not really clear on what text browsers like lynx will do with CSS, but I'd hate to eliminate 'em from the mix.

Internal CSS Examples

Okay, so much for the evangelism. L:-) How would/could we actually get there?

Establish the major logical groupings of the standard page layout. These become CSS ID 's. The list might look like:

• masthead: site logo and name; % WIKILOGOIMG%, % WIKITOOLNAME%, % WIKIHOMEURL%
• title: page/topic title; % TOPIC%
• content: the editable portion of the page and the reason it exists in the first place; % TEXT%
• meta: topic parents, revision #, attachments, etc.; % META%
• footer: copyright and other small print
• menu: self explanatory, container item for:
  • topicaction: Edit, attach, ref-by, print, etc.; % TOPICACTION%
  • topics: major topics within this web; % WEBTOPICLIST%
  • webs: other public webs on this twiki; % WIKIWEBLIST%

Next create or modify a view template file defining the above categories -- completely ignoring how it will look or where it will be located on the web page. It might look something like this (only relevant parts shown):

view.css.tmpl:

...
<link rel="stylesheet" type="text/css" media="all" href="/site-style.css" />
[/head]
[body]
<div id="title">%TOPIC% %TMPL:P{"titleaction"}% . %WEB%</div>
<div id="wrapper">
  <div id="content">%TEXT%</div>
  <div id="meta"> %META{"form"}% %META{"attachments"}%
    Revision %REVINFO% %META{"parent" prefix="<br />Parents: "}%<br />
    %META{"moved"}%
  </div>
  <div id="footer">%WEBCOPYRIGHT%</div>
</div>  
<div id="menu">
  <div id="topicaction"><h4>Topic Action:</h4> %TMPL:P{"topicaction"}%</div>
  <div id="topics">
    <form name="main" action="%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%WEB%/">
    <h4>Go to topic:</h4> %WEBTOPICLIST% 
    <input type="text" name="topic" size="16" />
    </form> </div>
  <div id="webs"><h4>Switch to web:</h4> %WIKIWEBLIST%</div>
</div>
[/body]
[/html]

...hrmm looks like html and body tags are not protected within a verbatim block, which is why the square brackets instead of angle brackets

The page this generates will look something like this:

• no style:
  

Now comes the fun, and hard, part: creating the stylesheet which will turn the above into something visually pleasing yet accessible across all browsers. I'm not going to show this fully, partly because I don't know enough to do it well and partly because it would take a lot of space. That said the styles below will take the boring early 1990's style html document above and bring a little, well, style, to it.

#wrapper { float: left; width: 85%; }
#content {border: 1px solid #a9a9a9; margin: 2%; padding: 2%;}
#menu { left: 85%;margin: 2em;padding: 0 5px; }
#menu ul {
   list-style: none;
   margin-top: -1em;
   margin-left: 1em;
   padding-left: 1em;
   text-indent: -1em;}
#menu h4 {margin-top: 0em; margin-bottom: 0em;}
body {background: #FFE0B0; font-family: Georgia, serif; font-size: small;} 
a {text-decoration:none; color:blue;} 
a:visited {color: purple;} 
a:hover {background-color: lightyellow;}

• a little bit of style:
  

I have implemented the ideas outlined above in SeeSkin. I believe this to be a strong enough working platform to springboard to TWikiUsingCSS, of course this belief needs to be tested.

In NamedIncludeSections there was talk about how improved includes would enable things like newspaper columns. Here is an example of how you can do this right now by using CSS and div :

source:

<style type ="text/css">
#container {position:relative; height:11em;}
#col1 {width:15em; margin:1em; padding:1em; border:thin gray dotted; position:absolute; left:0; top:0;}
#col2 {width:15em; margin:1em; padding:1em; border:thin gray dotted; position:absolute; left:19em; top:0;}
</style>

<div id="container"><div id="col1">
This is the first column, which needs enough text to line wrap at least once unless you have a really nice big display panel or I change my mind and use fixed width columns.
</div><div id="col2">
This is the second column, which needs enough text to line wrap at least once unless you have a really nice big display panel or I change my mind and use fixed width columns.
</div></div>

External CSS Examples

A nice demostration of a site that uses CSS AND is usable without, is Lee Jeans (and without CSS) (from http://www.zeldman.com/daily/0803a.shtml#jeanson, article at http://www.fivesevensix.com/studies/onetruefit/)

«Wired follows the trend of moving away from table based HTML to cleaner XHTML + CSS. Come on everyone, it's finally going to happen!»
-- http://internetalchemy.org/2002/10/wiredMovesToAllXHTMLPlusCSSDesign.html

More technical background: http://devedge.netscape.com/viewsource/2002/wired-interview/

---

MikeMannix, AndreaSterbini, DavidLeBlanc, AdrianLynch, DougPhilips, MartinKuhne, MattWilkie, RichardDonkin, PeterKlausner, MikeMaurer, ColasNahaboo, PeterMasiar, MS, ArthurClemens, LanceWeber, MichaelUtech,

---

---

Related topics:

• AutomaticSizingOfEditWindow
• BetterMarkup
• ContentBeforeStructure
• CssClassNames - towards a canonical list of class and ID names which could be used by all css using skins
• CssResources - gateway to many pages about using and troubleshooting and inspiration
• EnhancedSkinHandling
• HardwiredColours
• HardwiredRDiffColours (includes patch)
• PreferencesAsStyleSheets
• ProposalForAClassDesignationForLinks (includes patch)
• TWikiCSSDiscussion
• TWikiStyleSheets
• UsabilityIdeas
• UsingTopicToDefineCSS - editing stylesheets from within twiki (rather than via shell or ftp)

---

Refactoring notes:

• moved in some material from TWikiCSSDiscussion -- MattWilkie - 23 May 2004
• added "Road Blocks" and sub categories; moved relevent material into them -- MattWilkie - 24 May 2004