Lens Skin for PmWiki V2

Eggs theme for Lens PmWiki skin, author view Lens, a skin for version 2 of PmWiki,1 was the most complex web design project that I’ve done to date. It took several months and a lot of swearing to develop. It’s modular, which makes it unusually easy to customize. It is also:

Customizable

OP really was very serious when he said this theme is highly customizable. Thanks and great job! –RS

Compliment posted on my skin’s page at PmWiki’s official site

My top goal when writing Lens was for ordinary people to be able to customize it without having to learn any programming. XHTML and CSS are a cakewalk compared to a serious programming language like C, but many people still find it difficult to make one or two small changes to an otherwise ideal design without having to dive in headfirst.2  So Lens stores a lot of itself (for example, the contents of the sidebar) in the wiki rather than in the template file. It has many built-in style options to choose and learn from. And of course you can dig into the guts and tweak the code by hand if you want to.

Wiki Pages

Most of the skin’s user interface stuff — parts that are the same on every page, whose text or content you might want to change — is saved as PmWiki pages. So, if you know how to edit your PmWiki site at all, you can reword and rearrange them to your heart’s content. Doing it this way also means that previous versions of pages are saved, so it’s easy to undo any mistakes later, and that you can show or hide parts of the user interface according to conditions like today’s date or whether a user is logged in. You can’t even break your site by deleting these pages, because then it will just fall back to using the versions that came with the skin.

Built-in Options and Modularity

Lens Skin for PmWiki v2 in Camel
Camel theme (included in box)

Because I know XHTML and CSS well, I made sure that the people using Lens didn’t have to. Lens includes options for:

  • 3 colour schemes,
  • 7 common typefaces for Windows and Mac, set separately for headers and body text,
  • Liquid, elastic, and fixed-width layouts,
  • Several choices of sidebar width and position, and
  • Display of columns via absolute positioning or floats.

Here are a few samples of the possibilities.


The first two themes are included in the box when you download it from the Cookbook. The third is the Eggs theme that I designed for the previous iteration of my portfolio site.

Lens Skin for PmWiki v2 in Green
Default theme (included in box)

To use these options, all you have to do is find the right entries in skin.php, and add or remove a # in front of them.3 For example, if you’d like all the text to be smaller, you need to change this

    ## Base font size in percent (choose one)
    # 'font-size-76',
    # 'font-size-85',
    'font-size-100',
    # 'font-size-115',

to this:

    ## Base font size in percent (choose one)
    # 'font-size-76',
    'font-size-85',
    # 'font-size-100',
    # 'font-size-115',
Eggs theme for Lens PmWiki skin, display view
Eggs theme (exclusive to the previous version of my portfolio site)

The reason this is possible is that all the styles are modular, like LEGO blocks. Each stylesheet does a very specific thing.4 To make a new theme, just copy an existing one and then edit skin.php to suit. If the style option you want doesn’t exist, write your own CSS and add the option to the appropriate list in skin.php.

Works Everywhere for Everyone

Compliant and Compatible

Lens is built according to web standards with valid code. That makes it easier to maintain, compatible with many browsers instead of just one or two, and more accessible for the disabled. I then took forward and backward browser compatibility a few steps further. Lens has low-fidelity and high-fidelity versions, and you get the right one for the browser that you’re using.5

Accessible

As with my Lime Spider template, I wanted Lens to be usable for any user, through any browser or device. You can resize the text without damaging the layout or aesthetics, the code is semantic, the text and the background contrast well, no information is conveyed strictly by colour, and there are no images or plugins pretending to be text.

The low-fidelity version was designed for low vision users, screen readers, and cellphone browsers. Content comes before navigation, and internal links let you skip around the page. The single-column display is easier to read on small screens, and it doesn’t claim to know better than you (or your phone) what the best font size is. Also, if your cellphone’s browser is smart enough to fetch only stylesheets marked for mobile devices, then your data usage — and your bill — will be lower.

Modal

Eggs theme for Lens PmWiki skin, display view
Display view
Eggs theme for Lens PmWiki skin, standard view
Standard view

I built Lens partly for my own nefarious portfolio-displaying purposes, so it took shameless advantage of PmWiki’s View Modes plugin. In other words, I didn’t want hiring managers to see “Edit this page” links all over. For that matter, I didn’t want to see the entire toolbox of editing and administration controls every time I was tweaking grammar, so I used the View Modes plugin to hide them when they weren’t wanted. I’m sure this made Lens more useful to other people running professional sites on PmWiki. Here are screenshots of the different modes, from left to right: display, standard, author, and administrator.

Eggs theme for Lens PmWiki skin, author view
Administrator view
Eggs theme for Lens PmWiki skin, administrator view
Author view

Display mode only shows a login link in the sidebar, and no editing or admistrative controls. Standard mode adds Edit commands and a view mode switcher. Author mode adds in the possibility to attach files or view page history. Administrator mode shows everything.

Centralized

While developing Lens, I found out that keeping three or so complete copies in sync except for the desired differences was a lot of manual work. Instead, I wanted to keep one set of stylesheets, and have multiple themes based on them. To do that, I had to learn a bit of PHP, and write a routine that could make custom CSS files from the collection of building blocks, and then call them at need. I’m sure it’s a horrible messy hack-job of a function, but it works, and it lets the custom CSS be cached for next time, so that sites using Lens load faster on your subsequent visits.

  1. PmWiki is a wiki engine which makes a pretty good general content management system, especially back when I had a webhost that included PHP but not database access. I like wikis a lot for the simple text markup, how easy it is to make links within the site, and the built-in version history.
  2. Web page layout is harder than it has any right to be, both because the ideas are hard, and because there are so many tricky rendering differences and quirks involved.
  3. Lines with #s in front are turned off; lines without #s in front are turned on.
  4. Writing modular CSS is an entirely different experience than writing a regular stylesheet. Everything must be declared independently, at the right specificity, in the right order, so that all the combinations work reliably. I went into this project with a decent understanding of selector specificity and the cascade, but I came out of it with a better one. Even the bug fixes are modular, since I’ve employed proper hack management.
  5. It was simple to do once I found these nice big charts of CSS filtering mechanisms. I classified each stylesheet as being suitable for every browser or only modern ones, and selected just the right @import rule syntax for each kind. Voilà!  Your browser gets only the styles it can display properly without bothering you about the process at all.