Simplify Skin Creation based on Default Templates

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

Background

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.

Personas

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

See screenshot to the right (click on image for full screen).

• Banner with:
  • 1. Site logo, linked to home
  • 2. Jump box
  • 3. Search box
• Top of topic:
  • 4. Page links: Edit, Attach, Printable view
  • 5. Bread crumb ("you are here")
  • 6. Topic version info (revision, date, author)
  • 7. Tag links (optional, if TagMePlugin? installed)
  • (not shown) broadcast message
• Sidebar with:
  • 8. Web name
  • 9. "My personal links" section
  • 10. Shortcut links to current web
  • 11. Tips of the day (optional)
  • 12. List of webs
• Topic actions:
  • 13. Page links: Edit, Attach, Printable, Raw View, Backlinks, History links, More topic actions
• Bottom
  • 14. Copyright statement and small TWiki logo
• Main topic content
  • 15. Headings h1-h6
  • 16. Table of contents
  • 17. Paragraph text
  • 18. Bullets
  • 19. Tables
  • (not shown) Blockquotes
  • (not shown) Code text, verbatim
  • (not shown) Images

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

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 - 08 Jan 2007

Discussion

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.

Tree

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.

Mixin

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

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