skin2Add my vote for this tag create new tag
, view all tags

Simplify Skin Creation based on Default Templates

Goal: Make it very easy for integrators to create a new skin.


TWiki's target deployment is behind firewall use. Many companies have a standard on corporate branding and would like to have a seamless integration of their wiki into the intranet. That is, the employee or contractor who installs TWiki is frequently tasked to create a new TWiki skin.

In the last few month I had two somewhat painful experiences in creating new skins. The first excercise was to create a complete new TWiki look based on a screenshot I got from a client. I decided to overload the PatternSkin, but even with handholding by Arthur it took me more than one week work. (Please don't get me wrong, the PatternSkin is a very functional and also nice looking plugin.)

For the other skin, I got an HTML file with ready made css files. There I decided to create a new skin. It took me a few days to create the new skin just for the view script, I configured TWiki to fall back to PatternSkin for the other scripts. Creating a new skin for all scripts would be more than two weeks work. Skin creation does not necessarily need to be difficult.


In a typical TWiki deployment we have several people involved in the skin creation process. Lets describe them with Personas:

  • Ivan: Integrator who installs TWiki. Works in the engineering department. Has some technical knowledge, but has typically no background in website design. Hobby: Rocketry with 10 year old son.
  • Berta: Boss of Ivan, manages the internal tools department, responsible for SCM and collaboration.
  • David: Website designer, working in the corporate marketing department. Knows css inside out, has a flair for design. Hobby: Still life paintings using water colors.
  • Eric: Engineering director, sponsor of the wiki deployment. No hobby.
Scenario: There are already a number of grass roots wikis. Eric decides to consolidate the wikis within engineering. He asks Berta to evaluate the best wiki for their needs. Berta asks Ivan to do some research, Evan comes up with a list of 4 wiki engines found at WikiMatrix. They decide on TWiki; Berta asks Ivan to install TWiki and gives him half a day. Ivan finishes the installation in time. The wiki is presented to Eric; Eric asks Berta to give the wiki a corporate branding look. Berta asks Ivan to contact marketing for the style sheets and gives him half a day to create the skin. Ivan studies the existing TWiki skins and tells Berta that he needs at least one week to do the work.

Analysis of Screen Elements

There are fundamentally two screen types:

  • Full functional screen: View, rdiff, ...
    • All screen elements of view screen are present
  • Simple screen: Edit, oops, ...
    • Simple header, there are no links in page decoration (no logo link etc.), so that users do not navigate away
The simple screen is a simplified version of the full functional screen. In other words, Ivan only needs to ask David to provide a sample HTML file with supporting css for the full functional screen.

Screen elements of the full functional screen

Screen Elements (click to enlarge):
Screen elements
Screen elements by group: (see screenshot to the right)

  • Top menu:
    • 1. Home link & pulldown; pulldown contains list of webs
    • 2. Web link & pulldown; pulldown contains main actions on web
    • 3. Breadcrumb, with "P" indicating parent(s) of current topic. Example:
      Empty transparent 16x16 spacerTWiki logo, gray scale Home > Sandbox web > P > P > View
    • 4. Account pulldown with link to profile page and personal bookmarks
  • Page header:
    • 5. Site logo, linked to site home
    • 6. Jump box
    • 7. Search box
    • 8. Page action buttons: Edit, Attach
    • 9. Broadcast message (if enabled)
    • 10. Tag links (optional, if TagMePlugin installed)
  • Wiki page content:
    • 11. H1 heading
    • 12. Table of Content (using %TOC%)
    • 13. H2 to H6 headings
    • 14. Paragraph text
    • 15. Unordered and ordered bullet lists
    • 16. Table, with header and rows with alternating background colors
    • (not shown) Blockquotes
    • (not shown) Code text, verbatim text
    • (not shown) Images
    • (not shown) TWiki form table (database record)
    • (not shown) File attachment table (if any)
  • Page footer:
    • 17. Page links: Edit, Attach, Print version, History links, Backlinks, Raw View, Raw Edit, More topic actions
    • 18. Page version info (revision, date, author)
    • 19. Copyright statement and small TWiki logo

These are the screen elements based on the default TopMenuSkin layout. A custom skin may have a completely different layout, but could have most of the elements listed here.

(Above section is included from ScreenElementsOfTWikiSkin)

Ideal Scenario of how a new Skin is Created

  • Ivan sends above screenshot of screen elements to David, asking him to create an HTML file that has these elements (could be anywhere on the screen)
  • David uses his Dreamweaver tool to modify an existing HTML template page based on the corporate branding, adding the screen elements that are needed
  • David sends the HTML template page with supporting css files to Ivan
  • Ivan creates an EngSkin topic: Note: This is just an example; there are different ways to skin the cat.
    • Replace the placeholders in the HTML template page with TWiki variables, such as %WIKITOOLNAME%, %WEB%, %TOPIC%, %REVINFO%, %TEXT%, %META{"form"}%, etc.
    • Add a %TMPL:INCLUDE{"skinbase"}% to the HTML template page to glue the template page to the TWiki default templates.
    • Attach the HTML template page and css files to the skin topic.
    • Create a simple screen HTML template page, attach to skin topic.
If it is possible to implement the TWiki default templates to support this scenario it would take Ivan only an hours or so to integrate the HTML page template into TWiki.

-- Contributors: PeterThoeny - 2012-08-18


yep. CssZenGardenSkin will enable a good CSS designer to make a strong initial design for twiki, without having to know how TWiki works. It also will showcase that you can (now..) customise your TWiki by only defining a twiki.SKIN.tmpl, or by over-riding an existing skin.

-- SvenDowideit - 08 Jan 2007

We are lloking forward to your template redesign. Please share early on twiki.org so that you get feedback from all stakeholders.

-- PeterThoeny - 09 Jan 2007

My company want to replace the Intranet with TWiki but of course they feel really strong about company identity. Ideally TWiki would need something like a skin creation studio, that would be a Java or perl/Tk application allowing basic skin customisation. The output of the skin studio would be a zip file ready to be installed on the server.

-- StephaneLenclud - 09 Jan 2007

This is the reason I simplified the Classic skin to create the default templates (despite significant resistance). None of the currently shipped skins is a good baseline to create anything other than a look-alike, and I felt we needed a simple baseline for skin developers.

Simply basing a skin on screenshots is rarely enough. Skins are complex beasts, involving many different screens, each of which has to be personalised to create a skin. Local requirements, such as those imposed by installed plugins or the way the TWiki is to be used, mean that the structure of the example skins frequently gets in the way.

Sven and I have discussed a number of different approaches to skin building. Here are a couple of alternative approaches, both of which can be seen (all jumbled up) in the existing skins. Note that I do not favour the hybrid approach. IMHO it is better to select an architecture, document it, and stick to it like glue, even if that means compromising on features.


In this approach, the default templates define a simple architecture for the scripts that uses parameterised TMPL:INCLUDE to build up each screen. So each template (e.g. edit.tmpl) is a full HTML page, but it uses TMPL:INCLUDE to include other components. TMPL:P is not used in order to keep the structure as simple and obvious as possible. Then, the default templates provide sample implementations for each of the components. In order to KISS, the 'TMPL:INCLUDE only' rule has to be rigidly adhered to.

Of course this implies a rigid template structure. That's OK. If you think about the structure of the default templates as a tree, then small customisations should only require customising the leaves of the tree. Larger customisations may require the overriding of whole subtrees.


In a mixin approach, the templates for the standard screens (view, edit, more etc) are defined, each in a single file, using TMPL:P calls. A big file (twiki.tmpl_ lurks in the background that defines default implementations for each of these TMPL:DEFs. A skin designer comes along and provides twiki.skin.tmpl, and within that single file they override (mix in) one or more of the TMPL:DEFs from twiki.tmpl. TWiki CSS classes are used where necessary, but every HTML construction is allocated a class within the template structure so that a CSS designer can customise each component without touching the template files. CSS is not assumed, just leveraged to provide a quick way to customise.

-- CrawfordCurrie - 09 Jan 2007

Discussion cntd.

I like the idea of a parameterised TMPL:INCLUDE - I'll do that in Feburary (I wrote a script to convert the current skins into an INCLUDE based one, but it was messy, because it made one file per TMPL:P)

however, there is a much more important thing that is needed - at the moment, every skin seems to re-define common elements, such as the edit button. Worse, they all use different names for the TMPL:DEF, making it impossible to (for example) over-ride how the Edit link is rendered for all active skins (HowToDisableTheEditButton only works on pattern skin).

This bringing together of common elements, and changing the css tags for them from things like 'patternButton' to 'twikiTopicActionButton' is essential to SimplifySkinCreation .

I will need to do this, before CssZenGardenSkin is releaseable frown

see TWiki41/TWikiSkins when twiki-4.1 is released

-- SvenDowideit - 10 Jan 2007

Standardizing common elements would be a nice step towards reusability in skins. This is one of the areas where the TWiki core and the user-specific UI overlap. Note that there was a trend a while ago where we wanted to completely separate the templates from the core so that the core would not be making any assumptions about the templates. While some success has been had, primarily with the introduction of the notion of "context" (as with the striking out of the edit button on viewing previous revisions), there are still dependencies. The one's I can think of right now are:

  • The core assumes that there are certain tags in the template and rewrites those (e.g., %FORMTEMPLATE% or %FORMFIELDS% in the edit templates)
  • The core assumes that there are certain templates present structured in a specifc way (e.g., there must be a template that describes how the form is rendered upon edit, using very specific, yet undocumented elements %REPEAT%, %ROWVALUE%, similar for search).
  • The core must set the appropriate context for a template to work which relies upon it.
There are a couple issues here:
  1. These requirements are not documented. Thus, if a skin writer does not know that the form template has to have certain structure, the form editing will not work. If the skin writer does not realize that the %TEXT% must be included in the view template, no text will be seen.
  2. These secret tags are inconsistent. For example, the form is included in the view mode via %META{"form"}%, but in the edit mode via %FORMFIELDS%.
  3. These strategies are not uniformly applied. For example, while the editing of a form requires a form template, the viewing of the form does not, albeit it seems reasonable to allow the control given for creating the edit mode of a form also for the view mode.
  4. The form writer can require any context they like, but there is no way of imposing it on the core. The contexts that are in fact created are not documented.
Simplifying skin writing would probably require first that we straighten out, or at least document, these aspects.

Then it would, in fact, be great to establish standard concepts that are expected to be provided by skin writers and which the core will support and which the core can assume to be present.

-- ThomasWeigert - 10 Jan 2007

This area of interaction between templates and core is rather sensitive, as there is one the one hand the desire to make the skins as independent from the core as possible to allow for customization and creativitiy, but on the other hand there are the obvious benefits of standardization and reuse.

-- ThomasWeigert - 10 Jan 2007

Ping. Speeding up skin creation is something that helps promote TWiki.

-- PeterThoeny - 16 Mar 2007

Summing up the things that are being said here:

  • Proposal: make it possible to use a topic or attachment to define a style. Not sure what work would be needed to achieve this. I do think that the main goal would be to skin the view template; all other templates could just need some color changes and logo substitution.
  • Decide on template architecture: tree or mixin. I am strongly in favor of sticking to mixin as this will keep duplication of html to a minimum. Note that we need one base template for view and one for application pages like edit, attach and more.
  • Standardise template elements: I am in favor of this: it would mean that selecting a different skin would keep all elements. Pattern skin for instance has introduced divs beforeText and afterText. With a different skin these would be invisible. Also a typical template app like BlogAddOn now only works with pattern. Standardising would make it work across skins. As Thomas writes we need to document it all. I expect a couple of weeks discussing which elements are necessary.
  • All would require pattern skin to be rewritten. To prevent upgrade problems/documentation differences it would probably be best if I start with a new skin name and phase out pattern when this is ready for rollout. I want to do some tests with the base templates to see if they fit my needs as well.
  • I do think that a reskin would best be based on base templates, and that small modifications is done best with a polished skin. The different types of changes require different kinds of documentation. Redoing a polished skin will still be a lot of work if you want to comply with different browsers. It is to be expected that a polished skin has more CSS code.
  • Sven mentions patternXXX classes in core topics/templates/code. These must be leftovers and should be changed to twikiXXX classes.
-- ArthurClemens - 16 Mar 2007

Template discussion continued in TemplateUnification.

-- ArthurClemens - 18 Mar 2007

Pinging this proposal. Useful feature proposal, good fit for TWikiMission.

-- PeterThoeny - 2010-07-29

I am about to make a new skin for our company twiki, and I would be quite willing to try to document the steps in a way that helps others to do it for themselves later.

But I am confused by what I read here:

  • the last real edits here are 5 years old
  • was any of the template unification actually undertaken?
  • does CssZenGardenSkin exist really and if so does it achieve any of the claims made above?

I think my goals would be a bit more modest: I would like to show how to use a topic to modify the TopMenuSkin, perhaps clarifying what that approach can and can't do.

I'm a long time twiki user, but I'm running a real old version internally at our business and I haven't done any skin changes since TopMenuSkin appeared as the default. I can say from this perspective that there is a need to freshen up the old skin customization pages because, for example, they still refer to PatternSkin as the default.

Here's my main question, actually: where is the best place for me to put notes and questions as I get started with this? Here? Or in a new topic?

-- BenDugan - 2012-10-29

Thanks Ben for working on this!

  • Last edit was actually in August this year when I updated the screen elements screenshot. But no spec or implementation has been done of the proposed skin infrastructure.
  • The CssZenGardenSkin has never been released, and the contributor is no longer active.

If you plan to work/document/enhance primarily on the TopMenuSkin then we can discuss in the TopMenuSkinDev topic.

I recommend to update the code directly in Subversion. You can request write access. See ReadmeFirst and PluginsInSubversion; in the latter, follow the link "request checkin rights to the subversion repository."

-- PeterThoeny - 2012-10-29

Although I am starting with TopMenuSkin, I am not imagining this as 'development' of that skin but just customization of it: really basic things like changing the background header image, changing the logo, changing the style of headings and links, etc. And, as a user, what I think is missing is mainly clear documentation on how to make those kinds of changes. The documentation for the PatternSkin is mostly there, but now that TopMenuSkin is the default, the PatternSkin guides don't actually help.

This page starts off on a very good note, with Ivan, Eric, Berta, and David. That seems a realistic scenario for a lot of corporate settings. But in my 10 person corporation I am basically the one person who will do what those 4 hypothetical people would do. My goal in documenting the skin customization is to make it so that one person can make all the tweaks in one day: change the header, change the logo, change heading colors, fonts, etc. It sounds to me like the approach you suggested (using a topic with style sheet, template, and image attachments) should make that possible. I'm going to try to do that on my own site, and attempt to write down how its done at the same time.

-- BenDugan - 2012-10-30

Wow: its 4:30 and I have been working on this all day and getting nowhere. All I am trying to do is get a template file to work as an attachment to a topic. Its extremely frustrating.

I took the text from the file view.topmenu.tmpl and pasted it into a file on my local machine. Then I attach that file (now named view.tmpl) to a topic. I have tried to use various topics for this but ultimately I have attached it to TWikiPreferences thinking that it might need to be site wide to work for some reason.

Then I created a file called view.brownskin.tmpl in the templates directory on the server. It contains just one line:


Finally, I set SKIN = brownskin, pattern in TWikiPreferences.

I get either a blank white page (if there is a newline at the end of this single line) or an error message saying that the view template could not be found.

I hard-coded the path after trying many combinations of the twiki url and path variables.

I am leaning towards a return to PatternSkin because I think there I will at least have a fighting chance with the documentation.

-- BenDugan - 2012-10-30

Ah, if you want to customize the current PatternSkin and TopMenuSkin (which is overloading the PatternSkin) you can follow the instructions in PatternSkinCustomization. In your case you can either use the "template approach" or "topic template approach". With the former you should be able to create a dummy template file that includes an attached file. With the latter approach you simply edit topics.

-- PeterThoeny - 2012-10-31

On %TMPL:INCLUDE{http://...}%, this won't work with a URL because the template system only works on the local file system. The $TWiki::cfg{TemplatePath} defines the template directories TWiki will search for template files. To include an attachment file you need to prefix that path to the setting. Assuming your skin is BrownSkin with attached view.brown.tmpl file, set this:

$TWiki::cfg{TemplatePath} = '/var/www/twiki/pub/TWiki/BrownSkin/$name.$skin.tmpl, ...}%

That way you don't need to put any of your skin files into the twiki/templates directory, e.g. you can attach view.brown.tmpl directly to the TWiki.BrownSkin file.

-- PeterThoeny - 2012-10-31

Thanks Peter. I will give this stuff a try.

-- BenDugan - 2012-10-31

Edit | Attach | Watch | Print version | History: r24 < r23 < r22 < r21 < r20 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r24 - 2012-10-31 - PeterThoeny
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.