On this page:
TWiki SkinsSkins overlay regular templates to give different looks and feels to TWiki screens.OverviewTWiki 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. Tip: TWiki:TWiki.TWikiSkinsSupplement on TWiki.org has supplemental documentation on TWiki Skins.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 SkinsYou 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 thetwiki/templates directory and are named according to the skin: <scriptname>.<skin>.tmpl . For example, the template used for pages generated by the view script with the print skin selected is view.print.tmpl (this is how the Printable control is implemented). 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 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 .
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) | |||||||||||||||||||||||||||||||||||||||||||||||||
Changed: | |||||||||||||||||||||||||||||||||||||||||||||||||
< < |
| ||||||||||||||||||||||||||||||||||||||||||||||||
> > |
| ||||||||||||||||||||||||||||||||||||||||||||||||
twiki.tmpl is a master template conventionally used by other templates, but not used directly by code.
Note: You are strongly recommended not to TMPL:INCLUDE the default templates, or templates from other skins, when you are defining your own skin. If you do, you run the risk that the included file might change and break your skin.
Variables in SkinsYou can use template variables, TWikiVariables, and other predefined variables to compose your skins. Some commonly used variables in skins:
| |||||||||||||||||||||||||||||||||||||||||||||||||
Changed: | |||||||||||||||||||||||||||||||||||||||||||||||||
< < |
| ||||||||||||||||||||||||||||||||||||||||||||||||
> > |
| ||||||||||||||||||||||||||||||||||||||||||||||||
The "Go" Box and Navigation BoxThe 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:
Using Cascading Style SheetsCSS is used by PatternSkin, the TWiki skin that is selected in new installations. See that skin topic for information how CSS is used. CSS files are gererally attachments to the skin topic that are included in the the skin templates - in the case of PatternSkin in the templatecss.pattern.tmpl .
Write in your main template:
<style type='text/css' media='all'>@import url('%PUBURLPATH%/%TWIKIWEB%/MySkin/mystyle.css');</style> Attachment TablesControlling 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 theattachtables.tmpl template using the %TMPL:DEF macro syntax described in TWikiTemplates. These macros are:
ATTACH:row macros are expanded for each file in the attachment table, using the following special tags:
Packaging and Publishing SkinsSee TWiki:Plugins/SkinPackagingHowTo and TWiki:Plugins/SkinDeveloperFAQBrowsing Installed SkinsYou can try out all installed skins in the TWikiSkinBrowser.Activating SkinsTWiki 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 calledview. 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: | |||||||||||||||||||||||||||||||||||||||||||||||||
Changed: | |||||||||||||||||||||||||||||||||||||||||||||||||
< < |
| ||||||||||||||||||||||||||||||||||||||||||||||||
> > |
| ||||||||||||||||||||||||||||||||||||||||||||||||
You can also add a parameter to the URL, such as ?skin=catskin, bearskin . Example activation of PrintSkin that generates a printable page: | |||||||||||||||||||||||||||||||||||||||||||||||||
Changed: | |||||||||||||||||||||||||||||||||||||||||||||||||
< < | |||||||||||||||||||||||||||||||||||||||||||||||||
> > | |||||||||||||||||||||||||||||||||||||||||||||||||
Setting SKIN (or the ?skin parameter in the URL) replaces the existing skin path setting. You can also extend the existing skin path as well, using covers. | |||||||||||||||||||||||||||||||||||||||||||||||||
Changed: | |||||||||||||||||||||||||||||||||||||||||||||||||
< < |
| ||||||||||||||||||||||||||||||||||||||||||||||||
> > |
| ||||||||||||||||||||||||||||||||||||||||||||||||
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 full skin path is built up as follows: SKIN setting (or ?skin if it is set), then COVER setting is added, then ?cover .
Hard-Coded SkinsThetext skin is reserved for TWiki internal use.
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 .
Related Topics: TWikiSkinBrowser, AdminDocumentationCategory, DeveloperDocumentationCategory, TWiki:TWiki.TWikiSkinsSupplement
-- Contributors: TWiki:Main.PeterThoeny, TWiki:Main.MikeMannix, TWiki:Main.CrawfordCurrie |