Foswiki Skins

Skins overlay regular templates to give different looks and feels to Foswiki screens.

Overview

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.

Installing Skins

• Use /bin/configure to browse or search the list of extensions available from Foswiki.org, and to install the extension.
• Or, use the tools/extension_installer script to download and install the extension.
• Or, download an extension package from some other source, and unzip it.
• Follow any special installation instructions in the Skin topic.

Changing the default skin

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 easiest way to start creating a new skin is to layer it over an existing skin, only overriding those parts of the existing skin that you want to customise. Foswiki can be configured to fall back to another skin if a template is not defined in your skin. A custom skin can be as small as one file!

Note: Don't call your skin text or rss as these two skin names have reserved meanings, see below at hard-coded meanings.

The following template names are used for Foswiki screens, and are referenced in the Foswiki core code. If a skin doesn't define its own version of a template file, then Foswiki will fall back to the next skin in the skin path, or finally, to the default version of the template file.

• 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, not_a_user, 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
• 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 search results in book view
• searchformat - used to format search results
• search - used to format inline search results if no formatting is specified
• settings
• view - used by the view CGI script
• viewprint - used to create the printable view

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 customisation, or adding in new features to an existing skin

%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"edit_topic_link"}%%TMPL:END%
%TMPL:DEF{"edit_wysiwyg_link"}%%TMPL:END%

Settings in Skins

Using Cascading Style Sheets

• General documentation of CSS classes: AppendixCascadingStyleSheets
• To see how CSS is used in the default Foswiki skin, see: PatternSkin
• If you write a complete new skin, this is the syntax to use in a template file:

%ADDTOZONE{
    "head"
    id="MySkin/mystyle"
    text="
        <style type='text/css' media='all'>
            @import url('%PUBURLPATH%/%SYSTEMWEB%/MySkin/mystyle.css');
        </style>"
}%

Skin parts

The "Go" Box and Navigation Box

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:

FLASHNOTE Notifications

• Set FLASHNOTE = Skins documentation

See the alert at the top of this topic.

Attachment Tables

%IF{
    "'%R_STARTROW_4%' = '1'"
    then="<div class='row-fluid'>"
}%

%IF{
    "'%R_ENDROW_4%' = '1'"
    then="</div>"
}%

Packaging and Publishing Skins

<a href="https://foswiki.org/">
     <img src="%PUBURL%/%SYSTEMWEB%/ProjectLogos/foswiki-badge.png"\
          alt="Powered by Foswiki" height="42"\
          title="Powered by Foswiki" />
</a>

Generating:

Browsing Installed Skins

Activating Skins

   * Set SKIN = catskin, bearskin

• https://egothor.org/System/Skins?skin=catskin,bearskin

   * Set COVER = ruskin

1. value of the cover URL parameter
2. value of the COVER preference
3. value of the skin URL parameter, if it is non-null
4. value of the SKIN preference, if the skin URL parameter is not given

For example, if we have

   * Set SKIN = muscle,bone
   * Set COVER = epidermis

Hard-Coded Skins and Covers

text

The text skin is reserved for Foswiki internal use.

rss*

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.

cover=print

The cover URL parameter has some hardcoded effects that are not present when the same setting is prepended to the skin. The templates set the CSS media type by examining the cover value.

• cover=print sets media="all" for the print.css stylesheet. This causes the CSS to render identically for all media. What you see on the screen will be similar to what will be printed.
• skin=print,pattern links to the print.css stylesheet only for print media. This causes the CSS to honor the current media. The screen results will be different from what is actually printed.