-## <a name="TWiki Skins"></a> TWiki Skins
+<div>
+ <ul>
+ <li><a href="#TWiki Skins"> TWiki Skins</a><ul>
+ <li><a href="#Overview"> Overview</a></li>
+ <li><a href="#Defining Skins"> Defining Skins</a></li>
+ <li><a href="#Variables in Skins"> Variables in Skins</a><ul>
+ <li><a href="#The "Go" Box and Navigation Box"> The "Go" Box and Navigation Box</a></li>
+ </ul>
+ </li>
+ <li><a href="#Using Cascading Style Sheets"> Using Cascading Style Sheets</a></li>
+ <li><a href="#Attachment Tables"> Attachment Tables</a></li>
+ <li><a href="#Packaging and Publishing Skins"> Packaging and Publishing Skins</a></li>
+ <li><a href="#Browsing Installed Skins"> Browsing Installed Skins</a></li>
+ <li><a href="#Activating Skins"> Activating Skins</a></li>
+ </ul>
+ </li>
+ </ul>
+</div>
-Skins are customized [[TWikiTemplate|Main/TWikiTemplates]] files. You can use skins to change the look of a %WIKITOOLNAME% topic, for example the layout of the header and footer. Note that the renderd text between header and footer does **_not_** change. You can also use skins to define an alternate view, ex: a view optimized for printing.
+# <a name="TWiki Skins"></a> TWiki Skins
-Skin files are located in the <code>**twiki/template**</code> directory and are name with this syntax: <code>**<scriptname>.<skin>.tmpl**</code>. For example, the <code>**print**</code> skin for the <code>**view**</code> template is <code>**view<font>.print</font>.tmpl**</code> (red color added for clarification).
+_Skins overlay regular templates with alternate header/footer layouts; topic text is not affected_
+
+## <a name="Overview"></a> Overview
+
+Skins are customized [[TWikiTemplates]] files. You can use skins to change the look of a %WIKITOOLNAME% 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.
+
+## <a name="Defining Skins"></a> Defining Skins
+
+Skin files are located in the `twiki/templates` directory and are named with the syntax: <code>**<scriptname>.<skin>.tmpl**</code>. For example, the **Printable** skin for the `view` template is `view.print.tmpl`.
+
+Use the existing [[TWikiTemplates]] (like `view.tmpl`) or skin files as a base for your own skin, name it for example `view.myskin.tmpl`.
+
+## <a name="Variables in Skins"></a> Variables in Skins
+
+You can use [[template variables|Main/TWikiTemplates#TemplateVariables]], [[TWikiVariables]], and other predefined variables to compose your skins. Some commonly used variables in skins:
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Variable: </strong></th>
+ <th bgcolor="#99CCCC"><strong> Expanded to: </strong></th>
+ </tr>
+ <tr>
+ <td><code>%WIKILOGOURL%</code></td>
+ <td> Link of page logo </td>
+ </tr>
+ <tr>
+ <td><code>%WIKILOGOIMG%</code></td>
+ <td> Image URL of page logo </td>
+ </tr>
+ <tr>
+ <td><code>%WIKILOGOALT%</code></td>
+ <td> Alt text of page logo </td>
+ </tr>
+ <tr>
+ <td><code>%WEBBGCOLOR%</code></td>
+ <td> Web specific background color, defined in the [[Main/WebPreferences]]</td>
+ </tr>
+ <tr>
+ <td><code>%WIKITOOLNAME%</code></td>
+ <td> The name of your TWiki site </td>
+ </tr>
+ <tr>
+ <td><code>%SCRIPTURL%</code></td>
+ <td> The script URL of TWiki </td>
+ </tr>
+ <tr>
+ <td><code>%SCRIPTSUFFIX%</code></td>
+ <td> The script suffix, ex: <code>.pl</code>, <code>.cgi</code></td>
+ </tr>
+ <tr>
+ <td><code>%WEB%</code></td>
+ <td> The name of the current web. <strong><em>Note:</em></strong> It is recommended to URL-encode the variable in form actions with <code>%INTURLENCODE{"%WEB%"}%</code> for proper handling in an internationalized environment </td>
+ </tr>
+ <tr>
+ <td><code>%TOPIC%</code></td>
+ <td> The name of the current topic. <strong><em>Note:</em></strong> It is recommended to URL-encode the variable in form actions with <code>%INTURLENCODE{"%TOPIC%"}%</code> for proper handling in an internationalized environment </td>
+ </tr>
+ <tr>
+ <td><code>%WEBTOPICLIST%</code></td>
+ <td> Common links of current web, defined in the [[Main/WebPreferences]]. It includes a [[Main/WebHome#GoBox]]</td>
+ </tr>
+ <tr>
+ <td><code>%TEXT%</code></td>
+ <td> The topic text, e.g. the content that can be edited </td>
+ </tr>
+ <tr>
+ <td><code>%META{"form"}%</code></td>
+ <td>[[Main/TWikiForms]], if any </td>
+ </tr>
+ <tr>
+ <td><code>%META{"attachments"}%</code></td>
+ <td>[[Main/FileAttachment]] table </td>
+ </tr>
+ <tr>
+ <td><code>%META{"parent"}%</code></td>
+ <td> The topic parent </td>
+ </tr>
+ <tr>
+ <td><code>%EDITTOPIC%</code></td>
+ <td> Edit link </td>
+ </tr>
+ <tr>
+ <td><code>%REVTITLE%</code></td>
+ <td> The revision title, if any, ex: <code>(r1.6)</code></td>
+ </tr>
+ <tr>
+ <td><code>%REVINFO%</code></td>
+ <td> Revision info, ex: <code>r1.6 - 24 Dec 2002 - 08:12 GMT - Main.admin</code></td>
+ </tr>
+ <tr>
+ <td><code>%WEBCOPYRIGHT%</code></td>
+ <td> Copyright notice, defined in the [[Main/WebPreferences]]</td>
+ </tr>
+ <tr>
+ <td><code>%BROADCASTMESSAGE%</code></td>
+ <td> Broadcast message at the beginning of your view template, can be used to alert users of scheduled downtimes; is set in [[Main/TWikiPreferences]]</td>
+ </tr>
+</table>
+
+<a name="GoBox"></a>
+
+### <a name="The "Go" Box and Navigation Box"></a> The "Go" Box and Navigation Box
+
+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.
+
+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:
+
+<form action="http://www.dementia.org/twiki//view/%WEB%/%TOPIC%" name="sample">
+ <table border="3">
+ <tr>
+ <td><select name="sel" onchange="this.form.topic.value=this.options[this.selectedIndex].value; this.form.submit()"><option selected value="">Navigate...</option>
+ <option value="http://www.twiki.org/">Intranet home</option>
+ <option value="Main.TWikiUsers">Employee index</option>
+ <option value="Main.WebHome">Main web</option>
+ <option value="TWiki.WebHome">TWiki web</option>
+ <option value="http://www.google.com/">Google</option>
+ <option value="http://www.yahoo.com/">Yahoo!</option></select> Bare bones header for demo only </td>
+ </tr>
+ <tr>
+ <td> %WEBTOPICLIST% </td>
+ </tr>
+ </table>
+</form>
+
+## <a name="Using Cascading Style Sheets"></a> Using Cascading Style Sheets
+
+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 `view.myskin.tmpl`:
+
+ <style type="text/css">
+ .broadcastmessage {
+ background: yellow; display:block;
+ border-style:solid;border-width: 2px;border-color:red;
+ }
+ .broadcastmessage strong {color: red}
+ </style>
+
+Then add a div tag to the `%BROADCASTMESSAGE%` variable located after the `#PageTop` anchor or after the opening form tag:
+
+ <div class="broadcastmessage"> %BROADCASTMESSAGE% </div>
+
+## <a name="Attachment Tables"></a> Attachment Tables
+
+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.
+
+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:
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Macro </strong></th>
+ <th bgcolor="#99CCCC"><strong> Description </strong></th>
+ </tr>
+ <tr>
+ <td><code>ATTACH:files:header</code></td>
+ <td> Standard title bar </td>
+ </tr>
+ <tr>
+ <td><code>ATTACH:files:row</code></td>
+ <td> Standard row </td>
+ </tr>
+ <tr>
+ <td><code>ATTACH:files:footer</code></td>
+ <td> Footer for all screens </td>
+ </tr>
+ <tr>
+ <td><code>ATTACH:files:header:A</code></td>
+ <td> Title bar for upload screens, with attributes column </td>
+ </tr>
+ <tr>
+ <td><code>ATTACH:files:row:A</code></td>
+ <td> Row for upload screen </td>
+ </tr>
+ <tr>
+ <td><code>ATTACH:files:footer:A</code></td>
+ <td> Footer for all screens </td>
+ </tr>
+</table>
+
+The format of tables of file versions in the Upload screen are also formattable, using the macros:
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Macro </strong></th>
+ <th bgcolor="#99CCCC"><strong> Description </strong></th>
+ </tr>
+ <tr>
+ <td><code>ATTACH:versions:header</code></td>
+ <td> Header for versions table on upload screen </td>
+ </tr>
+ <tr>
+ <td><code>ATTACH:versions:row</code></td>
+ <td> Row format for versions table on upload screen </td>
+ </tr>
+ <tr>
+ <td><code>ATTACH:versions:footer</code></td>
+ <td> Footer for versions table on upload screen </td>
+ </tr>
+</table>
+
+The `ATTACH:row` macros are expanded for each file in the attachment table, using the following special tags:
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Tag </strong></th>
+ <th bgcolor="#99CCCC"><strong> Description </strong></th>
+ </tr>
+ <tr>
+ <td><code>%A_URL%</code></td>
+ <td> URL that will recover the file </td>
+ </tr>
+ <tr>
+ <td><code>%A_REV%</code></td>
+ <td> Revision of this file e.g. "1.1" </td>
+ </tr>
+ <tr>
+ <td><code>%A_ICON%</code></td>
+ <td> A file icon suitable for representing the attachment content </td>
+ </tr>
+ <tr>
+ <td><code>%A_FILE%</code></td>
+ <td> The name of the file </td>
+ </tr>
+ <tr>
+ <td><code>%A_SIZE%</code></td>
+ <td> The size of the file </td>
+ </tr>
+ <tr>
+ <td><code>%A_DATE%</code></td>
+ <td> The date the file was uploaded </td>
+ </tr>
+ <tr>
+ <td><code>%A_USER%</code></td>
+ <td> The user who uploaded it </td>
+ </tr>
+ <tr>
+ <td><code>%A_COMMENT%</code></td>
+ <td> The comment they put in when uploading it </td>
+ </tr>
+ <tr>
+ <td><code>%A_ATTRS%</code></td>
+ <td> The attributes of the file as seen on the upload screen e.g "h" for a hidden file </td>
+ </tr>
+</table>
+
+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.
+
+## <a name="Packaging and Publishing Skins"></a> Packaging and Publishing Skins
+
+See TWiki:Plugins/SkinPackagingHowTo and TWiki:Plugins/SkinDeveloperFAQ
+
+## <a name="Browsing Installed Skins"></a> Browsing Installed Skins
+
+You can try all installed skins in [[TWikiSkinBrowser]].
+
+## <a name="Activating Skins"></a> Activating Skins
A skin can be activated in two ways:
-- Define the SKIN preference variable in [[TWikiPreferences]], one of the [[WebPreferences]], or a user preference. Ex:
+- Define the `SKIN` Preference variable in [[TWikiPreferences]], one of the [[WebPreferences]], or in a user - Main.admin - topic.
- `Set SKIN = print`
+
- Add `?skin=name` to the URL, for this example:
- <http://www.dementia.org/twiki//view/%WEB%/%TOPIC%?skin=print> (for the print view skin)
- <http://www.dementia.org/twiki//view/%WEB%/%TOPIC%?skin=plain> (for the plain view skin that has no header and footer)
-The <code>**?skin=name**</code> URL parameter overrides the SKIN preference value.
+The <code>**?skin=name**</code> URL parameter overrides the SKIN Preference value.
--- [[PeterThoeny]] - 14 Jul 2001 <br />
+-- TWiki:Main.PeterThoeny - 25 Jul 2004 %BR% -- TWiki:Main.CrawfordCurrie - 30 Jun 2004 %BR%
git://git.openafs.org / openafs-wiki.git / blobdiff