Tags:
extract_doc1Add my vote for this tag create new tag
, view all tags

Creating a Custom TWiki Skin

Philosophy

This skin design tries to do without tables, as I find it quite harder to place things this way. This also means there's heavy dependency on CSS.

Understanding HTML Generation

Topics are generated by Perl scripts which parse templates. A template can contain plain HTML code, comments or even include other template files, and employs a particular syntax for these purposes. Especially noteworthy are directives which generate content:

  • %TEXT%: responsible for inserting the TWiki-marked up text of the topic
  • %REVISIONS%, %REVTITLE%: revision information
  • %WEBLIST%, %WEBTOPICLIST%: Web navigation

It is useful to understand how TWiki goes about producing the finished product, which is the plain html file your browser understands:

  1. as you choose a certain action (usually view), the same name perl script is called
  2. this script will read the template which carries its name: view.(skin).tmpl
  3. in the template there's a paraphernalia of html code, directives and definitions, which will be substituted by the html/text value TWiki stores internally
  4. in particular, %TEXT% will be replaced by the contents of the file with the same name as the topic you're currently viewing - try editing a sandbox web file (twiki/data/Sandbox/somefile.txt)

Tools

Even if I'm stating the obvious, here it goes:
  • Browser - one that does tabbed/split browsing, like Firefox or Konqueror. Don't forget about the View Source feature - it's very important!
  • Editor - VIm and newer JEdit do syntax highlighting for TWiki .tmpl files.
  • RCS - if you want to put your files under revision control

All of these should be found in your system, otherwise TWiki wouldn't be running; RCS may be absent, though. They're the "tools of the trade".

TWiki templates are necessary

Some definitions need to exist in the template files if the scripts are to be able to render pages. Since I'm still learning about this, I'll put my notes on the important files here.

Certain script templates (view, login, preview, attach, and probably others) include the twiki.tmpl before defining or overriding other blocks. This way, a frame is already in place, and one needs write only the relevant code lines.

  1. twiki.tmpl
What would we want to have as a standard in every generated page? The html, head and body sections of the page, the navigation and actions bar, and a nice topbar with a logo and/or other functions. Defining these on a single file and including it in subsequent templates is the natural way.

Let's start with our twiki.custom.tmpl file. Remember we won't generate any page from here, rather include the definitions somewhere else. Inside are definitions of static constructs, such as the htmldoctype. Notice how %TMPL:DEF{""}% and their corresponding %TMPL:END% commands are used to define the blocks, and to print them.

  1. view.tmpl
View is probably the most used script, as well as one of the most complex.

  1. css.tmpl
Style information is likely to be wanted in each generated file. Putting it in a separated file, which is included by twiki.tmpl or other template makes the process flexible.

Misplaced note

A technique that appears to be used in the templace files is that of defining a construct with empty space, then printing it within the proper block. This construct is then overriden somewhere down the road, and appears in 'the proper block'.

The core template: twiki.(skin).tmpl

Definitions which will be present in every page, no matter which script was used, can be set in a central file which is then included by every other. Also, definitions in this core file may be overriden later - a very handy feature.

The action templates: view, attach, edit, ...

This is where all the action is: the directive introduced above, !%TEXT%, will be replaced by the 'twikied' text. Within its borders, then, we won't be needing any template editing. Around it, though, we'll have to insert the commands that compose a web page:
  • topic navigation: #PageTop, #TopicEnd
  • the html, head and body tags, and their contents
  • the div blocks (or others) you'll be formatting with CSS

CSS: layout, style and colors

If you look at the source for a standard-skinned TWiki topic, you may find tags like <div=patternLeftBar> and the like. These blocks are defined in CSS files and control the visual aspect of the page. Of course, style directives (here in html-speak) must be made known to the browser - that's what css.(skin).tmpl is for.

Useful Links

-- Contributors: RenatoSerodio

Discussion

Do you have question or is this a documentation topic?

-- ArthurClemens - 19 Apr 2006

Well, this was an effort to document my experiences with creating a custom skin. Did I pick the wrong web?

-- RenatoSerodio - 22 Apr 2006

Your intention was not clear from the first version of the topic, I think that's why ArthurClemens asked.

As for the Web, I think that the final version should be moved to the TWiki web, but in Codev it get's more visibility and a bigger chance of feedback. So, I would say leave it here while it's a work in procees and then move the final document to TWiki to be marked as a Supplemental Document.

This is a much needed effort. Keep going smile

-- RafaelAlvarez - 25 Apr 2006

Edit | Attach | Watch | Print version | History: r7 < r6 < r5 < r4 < r3 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r7 - 2008-09-17 - TWikiJanitor
 
  • 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.