Tags:
create new tag
, view all tags

Introduction and Objectives

I've been looking at all the skin packages with a view to setting up a "user-friendly" Twiki, or at least one where the programatic aspects of TWiki aren't so apparent. TWiki is very powerful and very configurable, but its so much a "hackers delight" that this sometimes gets in the way for users.

I've seen many sites that have been referenced that have quite obviously done a great deal of work in this area. Some have their very customized skins. Its a shame they can't all feed back into a repository here.

One thing I notice about the skins in the Plugins web is their great variation in quality. As it stands, many of them need plug-in support.

We need some Standards

I discuss standards a lot. Well chosen standards are not negative constraints but are actually accelerators. Think of a limited access highway - Motorway, Autobahn, whatever you call it. Because the access is limited and built into the structure, there are not stop lights or cross-roads so you can go much faster. This is the kind of standards I want.

We already have many. All of TWiki, the internet, PCs, electronic communciation is built on them. The relieve us of having to rethink from basics every time we design anything. We know we can just plu in to the standards. You can argue about whether DC or AC is better in the household, 110 volts or 240 volts, 50Hz or 60Hz, but that's beside the point. In any one setting there are the standards to make things easier.

One of my criticism is two-fold:

  1. The set of skins is so full of arbitrary and incompatible design decisions because of the lack of standards.
  2. Many skins have just done a copy and edit and inherited design problems and shortcomings because there is no standard to follow, so leaving the designer free to inovate.

The Future is CSS, but what about the Present?

On the whole I feel that CSS and SeeSkin is the way to go in the long run, remove the programatic support needed. But the reality of the present is incompatible browsers.

However, I'd like to kick off this thread by using this topic as a starting point for some ideas.

Maintainability

My first idea has to do with maintainability and development.

I notice that many skins seem incomplete. Perhaps this is becuase they are pre-alpha smile who knows.

Per skin directories - compartmentalization

Right now, my /templates directory is massively overloaded. Does LINUX suffer from O-squared directory search times? Would having sub-directories make maintenance easier?

 /templates/
   +
   + twiki.tmpl
   + view.tmpl
   + edit.tmpl
   + preview.tmpl
   + *oo*.tmpl
   + etc
   |
   +-- /see  --+
   |           + twiki.tmpl
   |           + view.tmpl
   |           + edit.tmpl
   |           + preview.tmpl
   |
   +-- /gnu  --+
   |           + twiki.tmpl
   |           + view.tmpl
   |           + edit.tmpl
   |           + preview.tmpl
   +-- /tiger -+
   |           + twiki.tmpl
   |           + view.tmpl
   |           + edit.tmpl
   |           + preview.tmpl
   

It would make creating new skins easier - just copy a whole directory and edit. It would also encourage customization beyond those basic three and make it clear that there needs to be a skin version of "twiki.tmpl".

It also encourages compartmentaization, which is a Good Thing (tm). In doing so it will eliminate many opportunities for small errors such as editing the wrong template. I defy you to tell me you've never made a typo or edited the wrong file by mistake. Its just a matter of time, and some of us are getting to be worse typists as RSI sets in frown

Code Impact

Would such changes make the skin handling code more complex? TWiki::getSkin() would be unchanged. TWiki:Store::_readTemplateFile() already searches a number of directories and TWiki::Store::getAllWebs has recursive descent code that could be adapted.

Documentation

Good documentation is also part of a quality product. There are really two forms of documentation we have to deal with:

  1. The "under the hood" documentation. This is for programmers and maintainers, including system administrators, installers and customizers. Open source should demand better documentation, but the reality is many programmers don't like documenting and consider it a chore. Many high quality shops document and specify first, but that demands a different style of management, one many programmers won't tollerate. However a Wiki is a perfect platform for for documenting the development, as many people have commented here and as PeterTheony and the other core developers have shown. Other plugIns and skins lack this extensive documentation.
  2. The "end user" documentation. This doens't have to be an "idiot's guide" but should be enough that the end user doens't need the "under the hood" documents.

Many of the developers have failed to make use of the Wiki in the way the core team have. This is a disapointment. It forces the admijistrators and instlelrs to read the code and experiment. This assumes they know, have read and studied all of the Twiki documents and so forth. That's not a reasonable assumption.

Standard Features for Skins

Some Suggestions

  • The background color - what we call the WEBBGCOLOR but is really the colour of the borders and trims and not the background to the text.
  • The background color for the text region, lets call it WEBTXTBGCOLOR. Note that SeeSkin makes use of INLINESTYLE and if that is set to WEBBGCOLOR as in the example, there is not differentiation between the text area and the surroundings.
  • In /templates/twiki.tmpl the "<body>" statement explicity sets the background to "#FFFF". The GNU and tiger skins over-ride it with their own values. The SeeSkin assumes the parameters for it will be set in the style sheet. However it can also be used to set text background color, margins, the color of text and hyperlinks, what happens when the document is loaded or unloaded. Yes, these should be in a style sheet. But perhaps for skins that don't use a stylesheet there should be a default value:
      * #Set WEBBODY = bgcolor="%WEBTXTBGCOLOR" 
  • A standard name for the system logo and the per web logos

Of course all that could be obliviated if the skin has a setting for style sheets. But that requires some accomodation in the twiki..tmpl file. And it then up to the skin designer how to handle that.

Standards for use of CSS in TWiki and Skins

It may well be worth having standardized names for the DIVs and SPANs used if the basic regions are migrated into the core distribution. The SeeSkin illustrates this well.

Perhaps we need a topic where CSS oriented skin developers and customizers can discuss core compatibilities and incompatibilites. Using AgentPlugin is an unsatisfactory solution since the definitions have to be kept up to date as new reelases, products and patches come out.

-- AntonAylward - 01 Jan 2003


ThreadMode Comments

thank you for your vote of confidence in the SeeSkin approach Anton.

The stuff regarding default background colours and related is more of a bug report than a maintainability issue, but it is good to see it said nonetheless.

As for the propsed new templates directory structure: I Agree.

More generally, if some of the issues skins are being built to resolve were folded into the Twiki Core I think maintainability would follow by default (because skin developers would just leave well enough alone). I'll try and flesh out what I mean on this point later, but the basic idea is: there is a difference between changing the look and feel of something so that it matches your organisation and changing the functionality of the software. One is the proper purvue of a "skin" and the other should be taking place elsewhere.

-- MattWilkie - 03 Jan 2003

Indeed!

The more I look at the skins the more I think that Plugins.Seeskin approach is the only sensible way to go. It has focus but not the arbitraryness of FlexibleSkin. A disciplne is needed to maintian focus.

We don't see it but PeterThoeny and the other code developers have given us focus and are imposing a discipline in the code. The upcoming APIs are an example of that. Their appraoch to documentation is an example of that that far exceeds what I've observed (both as documentation and as discipline) in most of the non military shops I've worked in or consulted to over the last 25 years.

What a lot of programmers fail to realise is that if the supply good documentation and document their design structures and design decisions (i.e why that design desicion was made, how it supports the coherency of the whole) then other programmers and developers are more likely to use it and less likely to hack it apart. To say "Use the Code Luke" is a cop out.

However with the new release pending, I'm not doing any code work. I'll write up my ideas, comments and critiques, but design and coding is on hold until the new release has stabilized.

But as for skins an CSS. Yes, the separation of structure and colour is a good one. The ID tags need documenting. You or me?

We also need a few references to thigns like "why <FONT> is a bad idea", "use of <DIV> vs <SPAN>" and so forth.

I'd also like to see a discusion for skin developers on

  • What you should use that's already in templates/twiki.tmpl and shouldn't rewrite
  • What you should put in templates/yourskinname/twiki.tmpl
  • Whether just your versiosn of view.tmpl, edit.tmpl and preview.tmpl are enough.

-- AntonAylward - 03 Jan 2003

I've added a section to SeeSkin documenting the ID tags. Feel free to flesh it out and perhaps generalise so it's not skin specific. As for discussions on "why FONT is deprecated" etc. we could just point people to the appropriate css-discuss wiki topics (see CssResources). [e.g. I don't have the time/energy for this kind of documentation; I have RSI worries of my own. :-}]

-- MattWilkie - 03 Jan 2003

Edit | Attach | Watch | Print version | History: r5 < r4 < r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r5 - 2003-01-03 - MattWilkie
 
  • 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.