TWiki uses TWikiTemplates files as the basis of all the screens it uses to interact with users. Each screen has an associated template file that contains the basic layout of the screen. This is then filled in by the code to generate what you see in the browser.
TWiki ships with a default set of template files that give a very basic, CSS-themable, look-and-feel. TWiki also includes support for skins that can be selected to give different, more sophisticated, look and feel. A default TWiki installation will usually start up with the PatternSkin already selected. Skins may also be defined by third parties and loaded into a TWiki installation to give more options. To see how TWiki looks when no skin is selected, view the current page with a non-existing skin.
TWiki topic content is not affected by the choice of skin, however a skin can be defined to use a CSS (Cascading Style Sheet) which can provide a radically different appearance to the text layout.
Relevant links on TWiki.org:
TWiki ships with the TopMenuSkin activated by default. You can set a skin for the whole site, a single web, a single topic, or for each user individually. This is done by setting the SKIN preferences setting to the name of a skin. If the skin you select doesn't exist, then TWiki will pick up the default templates. For example, to make the SKIN setting work across all topics and webs, put it in TWikiPreferences.
Skins can cascade using a skin path explained below. One skin can be based on another one, and extensions can introduce additional screen elements. For example, the TagMePlugin adds tag elements to the TopMenuSkin, and the TopMenuSkin is based on the PatternSkin, resulting in this skin path:
* Set SKIN = tagme, topmenu, pattern
Defining Skins
You may want to define your own skin, for example to comply with corporate web guidelines, or because you have a aesthetic vision that you want to share. There are a couple of places you can start doing this.
The TWikiTemplates files used for skins are located in the twiki/templates directory and are named according to the skin: <scriptname>.<skin>.tmpl. Skin files may also be defined in TWiki topics - see TWikiTemplates for details.
To start creating a new skin, copy the default TWikiTemplates (like view.tmpl), or copy an existing skin to use as a base for your own skin. You should only need to copy the files you intend to customize, as TWiki can be configured to fall back to another skin if a template is not defined in your skin. Name the files as described above (for example view.myskin.tmpl).
If you use PatternSkin as your starting point, and you want to modify the layout, colors or even the templates to suit your own needs, have a look first at the topics PatternSkinCustomization and PatternSkinCssCookbook.
For your own TWiki skin we encourage you to show a small TWiki logo at the bottom of your skin:
<a href="http://twiki.org/"><img src="%PUBURL%/%SYSTEMWEB%/TWikiLogos/T-badge-88x31.gif" alt="This site is powered by the TWiki Enterprise Collaboration Platform" width="88" height="31" title="This site is powered by the TWiki Enterprise Collaboration Platform" border="0" /></a>
Renders as:
Note: TWiki.org has no marketing budget, e.g. we rely on TWiki users to spread the word of TWiki. You can support the open source project by adding logos that point back to TWiki.org, and by mentioning TWiki in social media.
The standard TWiki skins show the logo in the %WEBCOPYRIGHT% variable.
Note: Two skin names have reserved meanings; text skin, and skin names starting with rss have hard-coded meanings.
The following template files are used for TWiki screens, and are referenced in the TWiki core code. If a skin doesn't define its own version of a template file, then TWiki will fall back to the next skin in the skin path, or finally, to the default version of the template file.
(Certain template files are expected to provide certain TMPL:DEFs - these are listed in sub-bullets)
addform - used to select a new form for a topic
attachagain - used when refreshing an existing attachment
attachnew - used when attaching a new file to a topic
attachtables - defines the format of attachments at the bottom of the standard topic view
oopschangelanguage - used to prompt for a new language when internationalisation is enabled
oopsgeneric - a basic dialog for user information; provides "ok" button only
oopslanguagechanged - used to confirm a new language when internationalisation is enabled
oopsleaseconflict - used to format lease Conflict messages
lease_active, lease_old
preview - used for previewing edited topics before saving
rdiff - used for viewing topic differences
registernotify - used by the user registration system
registernotifyadmin - used by the user registration system
rename - used when renaming a topic
renameconfirm - used when renaming a topic
renamedelete - used when renaming a topic
renameweb - used when renaming a web
renamewebconfirm - used when renaming a web
renamewebdelete - used when renaming a web
searchbookview - used to format inline search results in book view
searchformat - used to format inline search results
search - used by the search CGI script
settings
view - used by the view CGI script
viewprint - used to create the printable view
twiki.tmpl is a master template conventionally used by other templates, but not used directly by code.
Note: Make sure templates do not end with a newline. Any newline will expand to an empty <p /> in the generated html. It will produce invalid html, and may break the page layout.
Partial customization, or adding in new features to an existing skin
You can use recursion in the TMPL:INCLUDE chain (e.g. twiki.pattern.tmpl contains %TMPL:INCLUDE{"twiki"}%, the templating system will include the next twiki.SKIN in the skin path (which is explained below). For example, to create a customization of pattern skin, where you only want to remove the edit & WYSIWYG buttons from view page, you create only a view.yourlocal.tmpl:
Broadcast message at the beginning of your view template, can be used to alert users of scheduled downtimes; can be set in TWikiPreferences
The Jump Box and Navigation Box
The default skins include a Jump Box, to jump to a topic.
The box also understands URLs, e.g. you can type http://www.google.com/ to jump to an external web site. The feature is handy if you build a skin that has a select box of frequently used links, like Intranet home, employee database, sales database and such. A little JavaScript gets into action on the onchange method of the select tag to fill the selected URL into the "Go" box field, then submits the form.
Here is an example form that has a select box and the Jump Box for illustration purposes. You need to have JavaScript enabled for this to work:
Note: Redirect to a URL only works if it is enabled in configure (Miscellaneous, {AllowRedirectUrl}).
Using Cascading Style Sheets
CSS files are gererally attachments to the skin topic that are included in the the skin templates - in the case of PatternSkin in the template styles.pattern.tmpl.
To see how CSS is used in the default TWiki skin, see: PatternSkin
If you write a complete new skin, this is the syntax to use in a template file:
Controlling the look and feel of attachment tables is a little bit more complex than for the rest of a skin. By default, the attachment table is a standard TWiki table, and the look is controlled in the same way as other tables. In a very few cases you may want to change the content of the table as well.
The format of standard attachment tables is defined through the use of special TWiki template macros which by default, are defined in the attachtables.tmpl template using the %TMPL:DEF macro syntax described in TWikiTemplates. These macros are:
TWiki uses a skin search path, which lets you combine skins additively. The skin path is defined using a combination of TWikiVariables and URL parameters.
TWiki works by asking for a template for a particular function - for example, 'view'. The detail of how templates are searched for is described in TWikiTemplates, but in summary, the templates directory is searched for a file called view.skin.tmpl, where skin is the name of the skin e.g. pattern. If no template is found, then the fallback is to use view.tmpl. Each skin on the path is searched for in turn. For example, if you have set the skin path to local,pattern then view.local.tmpl will be searched for first, then view.pattern.tmpl and finally view.tmpl.
The basic skin is defined by a SKIN setting:
Set SKIN = catskin, bearskin
You can also add a parameter to the URL, such as ?skin=catskin,bearskin:
Setting SKIN (or the ?skin parameter in the URL) replaces the existing skin path setting, for the current page only. You can also extend the existing skin path as well, using covers.
Set COVER = ruskin
This pushes a different skin to the front of the skin search path (so for our example above, that final skin path will be ruskin, catskin, bearskin). There is also an equivalent cover URL parameter. The difference between setting SKIN vs. COVER is that if the chosen template is not found (e.g., for included templates), SKIN will fall back onto the next skin in line, or the default skin, if only one skin was present, while COVER will always fall back onto the current skin.
An example would be invoking the printable mode, which is achieved by applying ?cover=print. The view.print.tmpl simply invokes the viewprint template for the current skin which then can appropriately include all other used templates for the current skin. Where the printable mode be applied by using SKIN, all skins would have the same printable appearance.
The full skin path is built up as follows: SKIN setting (or ?skin if it is set), then COVER setting is added, then ?cover.
Conditional Skin Activation
TWiki skins can be activated conditionally using IfStatements. For example, you might want to use a mobile skin for iPhone and Android user agents, and the default skin otherwise. This example uses the print skin on iPhone and Android:
* Set SKIN = %IF{
"'%HTTP{"User-Agent"}%'~'*iPhone*' OR '%HTTP{"User-Agent"}%'~'*Android*'"
then="print, pattern"
else="topmenu, pattern"
}%
- 
tip: supplemental documentation on TWiki skins
Note: Two skin names have reserved meanings;