Difference: TWikiSkins (15 vs. 16)
Revision 162005-03-27 - TWikiContributor
| Line: 1 to 1 | |||||||||
|---|---|---|---|---|---|---|---|---|---|
On this page:
TWiki Skins | |||||||||
| Changed: | |||||||||
| < < | Skins overlay regular templates with alternate header/footer layouts; topic text is not affected | ||||||||
| > > | Skins overlay regular templates to give different looks and feels to TWiki screens. | ||||||||
Overview | |||||||||
| Changed: | |||||||||
| < < | Skins are customized TWikiTemplates files. You can use skins to change the look of a TWiki topic, for example, the layout of the header and footer. Rendered text between header and footer does not change. You can also use skins to define an alternate view, like a view optimized for printing. | ||||||||
| > > | 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 basic look-and-feel. TWiki also includes support for skins that can be selected to give different, more sophisticated, look and feels. 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 this topic with a non-existant skin. Topic text is not affected by the choice of skin, though a skin can be defined to use a CSS (Cascading Style Sheet), which can sometimes give a radically different appearance to the text.
Changing the default TWiki skinTWiki default ships with the skin PatternSkin activated. If 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. | ||||||||
Defining Skins | |||||||||
| Changed: | |||||||||
| < < | Skin files are located in the twiki/templates directory and are named with the syntax: <scriptname>.<skin>.tmpl. For example, the Printable skin for the view template is view.print.tmpl. | ||||||||
| > > | 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.
The TWikiTemplates files used for skins are located in the | ||||||||
| Changed: | |||||||||
| < < | Use the existing TWikiTemplates (like view.tmpl) or skin files as a base for your own skin, name it for example view.myskin.tmpl. | ||||||||
| > > | 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 customise, 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.
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)
twiki.tmpl is a master template conventionally used by other templates, but not used directly by code.
| ||||||||
Variables in SkinsYou can use template variables, TWikiVariables, and other predefined variables to compose your skins. Some commonly used variables in skins:
| |||||||||
| Added: | |||||||||
| > > |
| ||||||||
| |||||||||
| Changed: | |||||||||
| < < |
| ||||||||
| > > |
| ||||||||
| |||||||||
| Added: | |||||||||
| > > |
| ||||||||
| |||||||||
| Changed: | |||||||||
| < < |
| ||||||||
| > > |
| ||||||||
| |||||||||
| Line: 38 to 101 | |||||||||
| |||||||||
| Changed: | |||||||||
| < < |
| ||||||||
| > > |
| ||||||||
The "Go" Box and Navigation Box | |||||||||
| Changed: | |||||||||
| < < | The %WEBTOPICLIST% includes a "Go" box to jump to a topic. The box also understand 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 onSelect method of the select tag to fill the selected URL into the "Go" box field, then submits the form. | ||||||||
| > > | The default %WEBTOPICLIST% includes a "Go" box, also called "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 onSelect 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 "Go" box for illustration purposes. You need to have JavaScript enabled for this to work: | |||||||||
| Changed: | |||||||||
| < < | |||||||||
| > > | |||||||||
| Line: 66 to 129 | |||||||||
Using Cascading Style Sheets | |||||||||
| Changed: | |||||||||
| < < | Although work is underway at TWiki:Codev.CssClassNames, the regular templates files currently do not use style sheets. Many skin developers, however, choose to use them; it helps in separating style from content.
Example: To use a style sheet for the broadcast message, add this to
<style type="text/css">
.broadcastmessage {
background: yellow; display:block;
border-style:solid;border-width: 2px;border-color:red;
}
.broadcastmessage strong {color: red}
</style>
| ||||||||
| > > | CSS is used by PatternSkin, the TWiki skin that is selected in new installations. See that skin topic for information how CSS is used. | ||||||||
| Changed: | |||||||||
| < < | Then add a div tag to the %BROADCASTMESSAGE% variable located after the #PageTop anchor or after the opening form tag: | ||||||||
| > > | 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 css.pattern.tmpl. | ||||||||
| Added: | |||||||||
| > > | Write in your main template: | ||||||||
| Changed: | |||||||||
| < < | |||||||||
| > > | |||||||||
|
Attachment Tables | |||||||||
| Changed: | |||||||||
| < < | 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 ay as other tables. In a very few cases you may want to change the content of the table as well. | ||||||||
| > > | 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. | ||||||||
| Changed: | |||||||||
| < < | The format of standard attachment tables is defined through the use of special TWiki template macros which by default are defined in the templates/twiki.tmpl template using the %TMPL:DEF macro syntax described in TWikiTemplates. These macros are: | ||||||||
| > > | 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: | ||||||||
| |||||||||
| Line: 97 to 149 | |||||||||
| |||||||||
| Changed: | |||||||||
| < < | The format of tables of file versions in the Upload screen are also formattable, using the macros: | ||||||||
| > > | The format of tables of file versions in the Upload screen can also be changed, using the macros: | ||||||||
| |||||||||
| Line: 106 to 159 | |||||||||
The ATTACH:row macros are expanded for each file in the attachment table, using the following special tags:
| |||||||||
| Changed: | |||||||||
| < < |
| ||||||||
| > > |
| ||||||||
| |||||||||
| Line: 115 to 168 | |||||||||
| |||||||||
| Deleted: | |||||||||
| < < | Note: it is easy to change the look and feel for an entire site by editing the twiki.tmpl template file. However, to simplify upgrading, you should avoid doing this. Instead, write a skin-specific template file e.g. attach.myskin.tmpl and use %TMPL:INCLUDE{attach.myskin.tmpl}% to include it in each of your skin files. As long as it it included after twiki.tmpl, your macro definitions will override the defaults defined there. | ||||||||
Packaging and Publishing Skins
See TWiki:Plugins/SkinPackagingHowTo
Browsing Installed Skins | |||||||||
| Changed: | |||||||||
| < < | You can try all installed skins in TWikiSkinBrowser. | ||||||||
| > > | You can try out all installed skins in the TWikiSkinBrowser. | ||||||||
Activating Skins | |||||||||
| Changed: | |||||||||
| < < | A skin can be activated in two ways: | ||||||||
| > > | 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
The basic skin is defined by a
You can also add a parameter to the URL, such as
Setting
This pushes a different skin to the front of the skin search path (so for our example above, that final skin path will be
The full skin path is built up as follows: | ||||||||
| Changed: | |||||||||
| < < |
| ||||||||
| > > |
Hard-Coded Skins | ||||||||
| Changed: | |||||||||
| < < |
| ||||||||
| > > | The text skin is reserved for TWiki internal use. | ||||||||
| Changed: | |||||||||
| < < | The ?skin=name URL parameter overrides the SKIN Preference value. | ||||||||
| > > | Skin names starting with rss also have a special meaning; if one or more of the skins in the skin path starts with 'rss' then 8-bit characters will be encoded as XML entities in the output, and the content-type header will be forced to text/xml. | ||||||||
| Changed: | |||||||||
| < < | -- TWiki:Main.PeterThoeny - 25 Jul 2004 -- TWiki:Main.CrawfordCurrie - 30 Jun 2004 | ||||||||
| > > | Related Topics: TWikiSkinBrowser, AdminDocumentationCategory, DeveloperDocumentationCategory, TWiki:TWiki.TWikiSkinsSupplement | ||||||||
| Added: | |||||||||
| > > | -- Contributors: TWiki:Main.PeterThoeny, TWiki:Main.MikeMannix, TWiki:Main.CrawfordCurrie | ||||||||
Tip: 
Note: Two skin names have reserved meanings; 
Copyright © 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors. Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiSkins.