Difference: TWikiSkins (15 vs. 16)

Revision 162005-03-27 - TWikiContributor

 
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.
 
Added:
>
>		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 Tip: TWiki:TWiki.TWikiSkinsSupplement on TWiki.org has supplemental documentation on TWiki Skins.

Changing the default TWiki skin

TWiki 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.
 
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.
>
>		The TWikiTemplates files used for skins are located in the twiki/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.
 
Added:
>
>		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.

ALERT! 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
    • ATTACH:files:footer, ATTACH:files:header, ATTACH:files:row, ATTACH:versions:footer, ATTACH:versions:header, ATTACH:versions:row
  • changeform - used to change the form in a topic
  • changes - used by the changes script
  • edit - used for the edit screen
  • form
  • formtables - used to defined the format of forms
    • FORM:display:footer, FORM:display:header, FORM:display:row
  • login - used for loggin in when using the TemplateLoginManager
    • LOG_IN, LOG_IN_BANNER, LOG_OUT, LOGGED_IN_BANNER, NEW_USER_NOTE, UNRECOGNISED_USER
  • moveattachment - used when moving an attachment
  • oopsaccessdenied - used to format Access Denied messages
    • no_such_topic, no_such_web, only_group, topic_access
  • oopsattention - used to format Attention messages
    • already_exists, bad_email, bad_ver_code, bad_wikiname, base_web_missing, confirm, created_web, delete_err, invalid_web_color, invalid_web_name, in_a_group, mandatory_field, merge_notice, missing_action, missing_fields, move_err, missing_action, no_form_def, no_users_to_reset, notwikiuser, oversized_upload, password_changed, password_mismatch, problem_adding, remove_user_done, rename_err, rename_not_wikiword, rename_topic_exists, rename_web_err, rename_web_exists, rename_web_prerequisites, reset_bad, reset_ok, save_error, send_mail_error, thanks, topic_exists, unrecognized_action, upload_name_changed, web_creation_error, web_exists, web_missing, wrong_password, zero_size_upload
  • oopschangelanguage - used to prompt for a new language when internationalisation is enabled
  • 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
twiki.tmpl is a master template conventionally used by other templates, but not used directly by code.

ALERT! 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 Skins

You can use template variables, TWikiVariables, and other predefined variables to compose your skins. Some commonly used variables in skins:

Variable: Expanded to:
Added:
>
>
%WEBLOGONAME% Filename of web logo
%WEBLOGOIMG% Image URL of web logo
%WEBLOGOURL% Link of web logo
%WEBLOGOALT% Alt text of web logo
 
%WIKILOGOURL% Link of page logo
%WIKILOGOIMG% Image URL of page logo
%WIKILOGOALT% Alt text of page logo
Changed:
<
<
%WEBBGCOLOR% Web specific background color, defined in the WebPreferences
>
>
%WEBBGCOLOR% Web-specific background color, defined in the WebPreferences
 
%WIKITOOLNAME% The name of your TWiki site
%SCRIPTURL% The script URL of TWiki
Added:
>
>
%SCRIPTURLPATH% The script URL path
 
%SCRIPTSUFFIX% The script suffix, ex: .pl, .cgi
Changed:
<
<
%WEB% The name of the current web. Note: It is recommended to URL-encode the variable in form actions with %INTURLENCODE{"%WEB%"}% for proper handling in an internationalized environment
%TOPIC% The name of the current topic. Note: It is recommended to URL-encode the variable in form actions with %INTURLENCODE{"%TOPIC%"}% for proper handling in an internationalized environment
%WEBTOPICLIST% Common links of current web, defined in the WebPreferences. It includes a #GoBox
>
>
%WEB% The name of the current web.
%TOPIC% The name of the current topic.
%WEBTOPICLIST% Common links of current web, defined in the WebPreferences. It includes a Go box
 
%TEXT% The topic text, e.g. the content that can be edited
%META{"form"}% TWikiForm, if any
%META{"attachments"}% FileAttachment table
%META{"parent"}% The topic parent
%EDITTOPIC% Edit link
%REVTITLE% The revision title, if any, ex: (r1.6)
%REVINFO% Revision info, ex: r1.6 - 24 Dec 2002 - 08:12 GMT - TWikiGuest
%WEBCOPYRIGHT% Copyright notice, defined in the WebPreferences
Changed:
<
<
%BROADCASTMESSAGE% Broadcast message at the beginning of your view template, can be used to alert users of scheduled downtimes; is set in TWikiPreferences
>
>
%BROADCASTMESSAGE% Broadcast message at the beginning of your view template, can be used to alert users of scheduled downtimes; can be set in TWikiPreferences
 

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:
<
<
>
>
 
Bare bones header for demo only
Welcome  |  Register  |  Changes  |  Topics  |  Index  |  Search  |  Go
Changed:
<
<
>
>
 

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.
>
>		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:
<
<		Example: To use a style sheet for the broadcast message, add this to view.myskin.tmpl:
>
>		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:
<
<
Deleted:
<
<		.broadcastmessage { background: yellow; display:block; border-style:solid;border-width: 2px;border-color:red; } .broadcastmessage strong {color: red}
 
Deleted:
<
<		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>
 

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:
 
Macro Description
ATTACH:files:header Standard title bar
ATTACH:files:row Standard row
ATTACH:files:footer Footer for all screens
ATTACH:files:header:A Title bar for upload screens, with attributes column
ATTACH:files:row:A Row for upload screen
ATTACH:files:footer:A Footer for all screens
Changed:
<
<		The format of tables of file versions in the Upload screen are also formattable, using the macros:
>
>
Added:
>
>		The format of tables of file versions in the Upload screen can also be changed, using the macros:
 
Macro Description
ATTACH:versions:header Header for versions table on upload screen
ATTACH:versions:row Row format for versions table on upload screen
ATTACH:versions:footer Footer for versions table on upload screen

The ATTACH:row macros are expanded for each file in the attachment table, using the following special tags:

Tag Description
%A_URL% URL that will recover the file
Changed:
<
<
%A_REV% Revision of this file e.g. "1.1"
>
>
%A_REV% Revision of this file
 
%A_ICON% A file icon suitable for representing the attachment content
%A_FILE% The name of the file
%A_SIZE% The size of the file
%A_DATE% The date the file was uploaded
%A_USER% The user who uploaded it
%A_COMMENT% The comment they put in when uploading it
%A_ATTRS% The attributes of the file as seen on the upload screen e.g "h" for a hidden file
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 and TWiki:Plugins/SkinDeveloperFAQ

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.
 
Changed:
<
<
>
>		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.
Deleted:
<
<
    • Set SKIN = print
 
Changed:
<
<
  • Add ?skin=name to the URL, for this example:
>
>		The basic skin is defined by a SKIN setting:
Deleted:
<
<
 
Changed:
<
<		The ?skin=name URL parameter overrides the SKIN Preference value.
>
>
  • Set SKIN = catskin, bearskin
 
Changed:
<
<		-- TWiki:Main.PeterThoeny - 25 Jul 2004
>
>		You can also add a parameter to the URL, such as ?skin=catskin, bearskin. Example activation of PrintSkin that generates a printable page:
Deleted:
<
<		-- TWiki:Main.CrawfordCurrie - 30 Jun 2004
 
Added:
>
>

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.

  • 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 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 Skins

The text 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

 
View topic | History: r22 < r21 < r20 < r19 | More topic actions...
 
This site is powered by the TWiki collaboration platform Powered by Perl This site is powered by the TWiki collaboration platformCopyright © 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.