PatternSkin Customization

PatternSkin Customization

Guidelines how to create and customize page templates. For styling your Foswiki using stylesheets, see PatternSkinCssCookbook.

Guidelines how to create and customize page templates. For styling your Foswiki using stylesheets, see PatternSkinCssCookbook.

First Read: How to modify PatternSkin templates

First Read: How to modify PatternSkin templates

Everything you see on the common 'view' page is written by the view template. For pattern skin this file is /templates/view.pattern.tmpl.

Everything you see on the common 'view' page is written by the view template. For pattern skin this file is /templates/view.pattern.tmpl.

We describe two approaches to override this template:

We describe two approaches to override this template:

1. By creating a custom skin file in the templates directory
2. By creating a custom topic template

1. By creating a custom skin file in the templates directory
2. By creating a custom topic template

Which approach is best?

Which approach is best?

• If you want to change the appearance for a lot of pages or even site-wide, the template approach is the easiest.
• If you want to change the appearance of a single topic, or a set of topics, use a topic template.

• If you want to change the appearance for a lot of pages or even site-wide, the template approach is the easiest.
• If you want to change the appearance of a single topic, or a set of topics, use a topic template.

The template approach

The template approach

To change templates you will need shell access. If you don't have this read on below in The topic template approach.

To change templates you will need shell access. If you don't have this read on below in The topic template approach.

The quickest way to change the view template would be to simply change the text in the template. A safer way - strongly recommended, because it will survive a Foswiki update - is to create your own custom skin. That may sound like an awful lot of work, but in reality a skin may be as much as 1 file that consists of only a few lines of code.

The quickest way to change the view template would be to simply change the text in the template. A safer way - strongly recommended, because it will survive a Foswiki update - is to create your own custom skin. That may sound like an awful lot of work, but in reality a skin may be as much as 1 file that consists of only a few lines of code.

Example
Let's say you want to simplify the bottom toolbar and remove all links except for "More topic actions". You would need to target %TMPL:DEF{"topicactionbuttons"}%, which is located in view.pattern.tmpl.

Example
Let's say you want to simplify the bottom toolbar and remove all links except for "More topic actions". You would need to target %TMPL:DEF{"topicactionbuttons"}%, which is located in view.pattern.tmpl.

The steps you would need:

The steps you would need:

1. Think up a name for your skin. Let us use myskin for now.
2. Create a new (empty) view template file in /templates called view.myskin.tmpl.
3. In view.myskin.tmpl you write:

      %TMPL:INCLUDE{"view"}%
      %TMPL:DEF{"top:topicactionbuttons"}%%TMPL:P{"more_link"}%%TMPL:END%

4. For testing, view any topic and append to the topic name: ?cover=myskin. You should see an effect now.
5. To make the changes visible on all pages, go to SitePreferences (to keep DefaultPreferences intact) and write:

         * Set COVER = myskin

   or write

         * Set SKIN = myskin,pattern

1. Think up a name for your skin. Let us use myskin for now.
2. Create a new (empty) view template file in /templates called view.myskin.tmpl.
3. In view.myskin.tmpl you write:

      %TMPL:INCLUDE{"view"}%
      %TMPL:DEF{"top:topicactionbuttons"}%%TMPL:P{"more_link"}%%TMPL:END%

4. For testing, view any topic and append to the topic name: ?cover=myskin. You should see an effect now.
5. To make the changes visible on all pages, go to SitePreferences (to keep DefaultPreferences intact) and write:

         * Set COVER = myskin

   or write

         * Set SKIN = myskin,pattern

Test by appending ?cover=myskin to the url.

Test by appending ?cover=myskin to the url.

The topic template approach (using VIEW_TEMPLATE)

The topic template approach (using VIEW_TEMPLATE)

Template overrides can be written in a topic, a so-called topic template. Topic template names end with ViewTemplate, for instance BlogPostViewTemplate.

Template overrides can be written in a topic, a so-called topic template. Topic template names end with ViewTemplate, for instance BlogPostViewTemplate.

Call this template by setting VIEW_TEMPLATE:

Call this template by setting VIEW_TEMPLATE:

   * Set VIEW_TEMPLATE = BlogPostView

   * Set VIEW_TEMPLATE = BlogPostView

• Note that you don't use the Template extension now
• You can make this setting hidden by writing this in the Settings screen: go to More and then Topic Settings

• Note that you don't use the Template extension now
• You can make this setting hidden by writing this in the Settings screen: go to More and then Topic Settings

We can use the same example as above. In the topic you want to use as view template, for instance OnlyMoreView, write:

We can use the same example as above. In the topic you want to use as view template, for instance OnlyMoreView, write:

%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"top:toolbarbuttons"}%%TMPL:P{"more_link"}%%TMPL:END%

%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"top:toolbarbuttons"}%%TMPL:P{"more_link"}%%TMPL:END%

You can also test this by appending ?template=OnlyMoreView to the url.

You can also test this by appending ?template=OnlyMoreView to the url.

Reference: pattern skin template INCLUDE tree

Reference: pattern skin template INCLUDE tree

The view script invokes the view template: (Note that to simplify customization of the top and side bar layouts, the templates include an "Example" topic if the corresponding topic does not exist. Copy the example topic rather than changing the example directly.)

The view script invokes the view template: (Note that to simplify customization of the top and side bar layouts, the templates include an "Example" topic if the corresponding topic does not exist. Copy the example topic rather than changing the example directly.)

view
    foswiki
        css
        viewtopbar
            %SYSTEMWEB%.WebTopBar or %SYSTEMWEB%.WebTopBarExample
        viewsidebar
            %WEB%.WebLeftBar or  %SYSTEMWEB%.WebLeftBarExample
        viewtopicactionbuttons
        viewbottombar
            %SYSTEMWEB%.WebBottomBar or %SYSTEMWEB%.WebBottomBarExample

view
    foswiki
        css
        viewtopbar
            %SYSTEMWEB%.WebTopBar or %SYSTEMWEB%.WebTopBarExample
        viewsidebar
            %WEB%.WebLeftBar or  %SYSTEMWEB%.WebLeftBarExample
        viewtopicactionbuttons
        viewbottombar
            %SYSTEMWEB%.WebBottomBar or %SYSTEMWEB%.WebBottomBarExample

Note that WebTopBar is not used per web, but it's either pulled from WebTopBar, or, if it doesn't exist, from WebTopBarExample.

Note that WebTopBar is not used per web, but it's either pulled from WebTopBar, or, if it doesn't exist, from WebTopBarExample.

Logo

Logo

How can I change the web logo?

How can I change the web logo?

By default the logo at the top left of each web points to the image with name logo.gif that is attached to each web's WebPreferences.
The preference settings that cause this behavior are defined in DefaultPreferences.

By default the logo at the top left of each web points to the image with name logo.gif that is attached to each web's WebPreferences.
The preference settings that cause this behavior are defined in DefaultPreferences.

Redefine your custom preference settings in SitePreferences (to keep DefaultPreferences intact):

Redefine your custom preference settings in SitePreferences (to keep DefaultPreferences intact):

   * Set WEBLOGONAME = logo.gif
   * Set WEBLOGOIMG = %PUBURLPATH%/%BASEWEB%/%WEBPREFSTOPIC%/%WEBLOGONAME%
   * Set WEBLOGOURL = %SCRIPTURLPATH{"view"}%/%BASEWEB%/%HOMETOPIC%
   * Set WEBLOGOALT = Home

   * Set WEBLOGONAME = logo.gif
   * Set WEBLOGOIMG = %PUBURLPATH%/%BASEWEB%/%WEBPREFSTOPIC%/%WEBLOGONAME%
   * Set WEBLOGOURL = %SCRIPTURLPATH{"view"}%/%BASEWEB%/%HOMETOPIC%
   * Set WEBLOGOALT = Home

There are 2 ways to change the logo in a web:

There are 2 ways to change the logo in a web:

Using logo.gif:

Using logo.gif:

• Create a new image named logo.gif and attach it to the web's WebPreferences topic. PatternSkin's stylesheet assumes the logo is 40px high. More about that later.
• You can also upload the image with FTP to /pub/YourWeb/WebPreferences/.
• Copy the above instructions ("Redefine your custom preference settings") and insert your logo name.

• Create a new image named logo.gif and attach it to the web's WebPreferences topic. PatternSkin's stylesheet assumes the logo is 40px high. More about that later.
• You can also upload the image with FTP to /pub/YourWeb/WebPreferences/.
• Copy the above instructions ("Redefine your custom preference settings") and insert your logo name.

Using a new filename:

Using a new filename:

• Attach whatever image and attach it to the web's WebPreferences topic. Then add to the WebPreferences (under Custom web preferences):

      * Set WEBLOGONAME = your-logo-name.gif-or-png

• Copy the above instructions ("Redefine your custom preference settings") and insert your logo name.

• Attach whatever image and attach it to the web's WebPreferences topic. Then add to the WebPreferences (under Custom web preferences):

      * Set WEBLOGONAME = your-logo-name.gif-or-png

• Copy the above instructions ("Redefine your custom preference settings") and insert your logo name.

How do I set a site-wide logo?

How do I set a site-wide logo?

There are a bunch of site-wide logo preference settings in SitePreferences: WIKILOGOIMG, WIKILOGOURL and WIKILOGOALT. To change only the web logo image to site-wide, in SitePreferences set:

There are a bunch of site-wide logo preference settings in SitePreferences: WIKILOGOIMG, WIKILOGOURL and WIKILOGOALT. To change only the web logo image to site-wide, in SitePreferences set:

   * Set WEBLOGOIMG = %WIKILOGOIMG%

   * Set WEBLOGOIMG = %WIKILOGOIMG%

My logo does not fit the top bar

My logo does not fit the top bar

See I want to change the height of the top bar

See I want to change the height of the top bar

I want to change the white space above and below the logo

I want to change the white space above and below the logo

Change the table style in topic WebTopBar. The default top padding is 11px.

Change the table style in topic WebTopBar. The default top padding is 11px.

Top bar

Top bar

The search box won't find topics in other webs

The search box won't find topics in other webs

In WebTopBar you can find the line:

In WebTopBar you can find the line:

To search all webs, write:

To search all webs, write:

To search a couple of webs, for instance the webs Main and System, write:

To search a couple of webs, for instance the webs Main and System, write:

See also: Search macro

See also: Search macro

I want to change the height of the top bar

I want to change the height of the top bar

This information has moved to PatternSkinCssCookbook

This information has moved to PatternSkinCssCookbook

I want to set or change the top background image

I want to set or change the top background image

The image at the top is called "header art" - commonly the top image found on blog sites. The image that is displayed by default is set by the preference WEBHEADERART, defined in DefaultPreferences.

The image at the top is called "header art" - commonly the top image found on blog sites. The image that is displayed by default is set by the preference WEBHEADERART, defined in DefaultPreferences.

Redefine your custom preference settings in SitePreferences (to keep DefaultPreferences intact):

Redefine your custom preference settings in SitePreferences (to keep DefaultPreferences intact):

   * Set WEBHEADERART = %PUBURLPATH%/%SYSTEMWEB%/PatternSkin/Foswiki_header.gif
   * Set WEBHEADERBGCOLOR = somehexcolor (no quotes, for example: #ffffff)

   * Set WEBHEADERART = %PUBURLPATH%/%SYSTEMWEB%/PatternSkin/Foswiki_header.gif
   * Set WEBHEADERBGCOLOR = somehexcolor (no quotes, for example: #ffffff)

You can also set WEBHEADERART per web, by setting the preference in the Web's WebPreferences.

You can also set WEBHEADERART per web, by setting the preference in the Web's WebPreferences.

I want to have the web color in the top bar

I want to have the web color in the top bar

Redefine WEBHEADERBGCOLOR in SitePreferences (to keep DefaultPreferences intact):

Redefine WEBHEADERBGCOLOR in SitePreferences (to keep DefaultPreferences intact):

   * Set WEBHEADERBGCOLOR = %WEBBGCOLOR%

   * Set WEBHEADERBGCOLOR = %WEBBGCOLOR%

I want to remove the Jump and Search boxes from the top bar

I want to remove the Jump and Search boxes from the top bar

If you have localization enabled, you will also see a language dropdown box at the far right.

If you have localization enabled, you will also see a language dropdown box at the far right.

You can remove these items from WebTopBar.

You can remove these items from WebTopBar.

I want to hide the top bar

I want to hide the top bar

Using templates:

Using templates:

The view template is populated with page elements using template inclusions:

The view template is populated with page elements using template inclusions:

%TMPL:INCLUDE{"view"}%
%TMPL:INCLUDE{"viewtopicactionbuttons"}%
%TMPL:INCLUDE{"viewtopbar"}%
%TMPL:INCLUDE{"viewsidebar"}%

%TMPL:INCLUDE{"view"}%
%TMPL:INCLUDE{"viewtopicactionbuttons"}%
%TMPL:INCLUDE{"viewtopbar"}%
%TMPL:INCLUDE{"viewsidebar"}%

Each included template draws a part of the screen.
Omit %TMPL:INCLUDE{"viewtopbar"}% to hide the top bar.

Each included template draws a part of the screen.
Omit %TMPL:INCLUDE{"viewtopbar"}% to hide the top bar.

Another approach is to clear the contents of module topbar with an empty definition. Using either a template or a topic template, write in your custom template:

Another approach is to clear the contents of module topbar with an empty definition. Using either a template or a topic template, write in your custom template:

%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"topbar"}%%TMPL:END%

%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"topbar"}%%TMPL:END%

and add:

and add:

%TMPL:DEF{"topbardimensions"}%#patternTopBar,
#patternClearHeaderCenter,
#patternClearHeaderLeft,
#patternClearHeaderRight {
   height:0px;
}%TMPL:END%

%TMPL:DEF{"topbardimensions"}%#patternTopBar,
#patternClearHeaderCenter,
#patternClearHeaderLeft,
#patternClearHeaderRight {
   height:0px;
}%TMPL:END%

Using style sheets:
See PatternSkinCssCookbookNoTopBar

Using style sheets:
See PatternSkinCssCookbookNoTopBar

Left bar

Left bar

I want to hide the side bar

I want to hide the side bar

Using templates:
Omit %TMPL:INCLUDE{"viewsidebar"}% to hide the side bar, or in a custom template clear it using

Using templates:
Omit %TMPL:INCLUDE{"viewsidebar"}% to hide the side bar, or in a custom template clear it using

%TMPL:DEF{"sidebar"}%%TMPL:END%

%TMPL:DEF{"sidebar"}%%TMPL:END%

Using style sheets:
See PatternSkinCssCookbookNoLeftBar

Using style sheets:
See PatternSkinCssCookbookNoLeftBar

Buttons

Buttons

I want to hide the edit buttons from certain users

I want to hide the edit buttons from certain users

It may defy the wiki-ness of your Foswiki installation, but in certain circumstances it could be useful to hide the edit buttons from users that are not logged in, for instance for clients that have gotten viewing rights only.

It may defy the wiki-ness of your Foswiki installation, but in certain circumstances it could be useful to hide the edit buttons from users that are not logged in, for instance for clients that have gotten viewing rights only.

Using either a template or a topic template, 'empty' top:toolbarbuttons and topicaction by writing:

Using either a template or a topic template, 'empty' top:toolbarbuttons and topicaction by writing:

%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"top:toolbarbuttons"}%%TMPL:END%
%TMPL:DEF{"topicaction"}%%TMPL:END%

%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"top:toolbarbuttons"}%%TMPL:END%
%TMPL:DEF{"topicaction"}%%TMPL:END%

In the user page of WikiGuest, set the cover to

In the user page of WikiGuest, set the cover to

   * Set COVER = customer

   * Set COVER = customer

By default this topic is editable only by Wiki admins.

By default this topic is editable only by Wiki admins.

I want to remove the History button from the bottom

I want to remove the History button from the bottom

All action links and buttons are defined in viewtopicactionbuttons.tmpl. The bottom history link is defined in DEF action_revisions

All action links and buttons are defined in viewtopicactionbuttons.tmpl. The bottom history link is defined in DEF action_revisions

%TMPL:DEF{"topicactionbuttons"}%
%TMPL:P{"action_activatable_edit_or_create"}%
%TMPL:P{"action_activatable_attach"}%
%TMPL:P{"action_printable"}%
%TMPL:P{"action_revisions"}%
%TMPL:P{"action_backlinks_simple"}%
%TMPL:P{"action_raw_or_view"}%
%TMPL:P{"action_activatable_raw_edit"}%
%TMPL:P{"activatable_more"}%
%TMPL:END%

%TMPL:DEF{"topicactionbuttons"}%
%TMPL:P{"action_activatable_edit_or_create"}%
%TMPL:P{"action_activatable_attach"}%
%TMPL:P{"action_printable"}%
%TMPL:P{"action_revisions"}%
%TMPL:P{"action_backlinks_simple"}%
%TMPL:P{"action_raw_or_view"}%
%TMPL:P{"action_activatable_raw_edit"}%
%TMPL:P{"activatable_more"}%
%TMPL:END%

To hide that link, In a custom skin view template view.myskin.tmpl empty action_revisions by replacing it with an empty string:

To hide that link, In a custom skin view template view.myskin.tmpl empty action_revisions by replacing it with an empty string:

%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"action_revisions"}%%TMPL:END%

%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"action_revisions"}%%TMPL:END%

I want to put the bottom links as buttons at the top

I want to put the bottom links as buttons at the top

The default definition in view.pattern.tmpl is:

The default definition in view.pattern.tmpl is:

%TMPL:DEF{"top:toolbarbuttons"}%%TMPL:P{"activatable_edit_or_create"}%%TMPL:P{"activatable_attach"}%%TMPL:END%

%TMPL:DEF{"top:toolbarbuttons"}%%TMPL:P{"activatable_edit_or_create"}%%TMPL:P{"activatable_attach"}%%TMPL:END%

Create a new skin by creating a file view.myskin.tmpl in the templates directory. Write in it:

Create a new skin by creating a file view.myskin.tmpl in the templates directory. Write in it:

%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"top:toolbarbuttons"}%%TMPL:P{"history_history_link"}%%TMPL:END%

%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"top:toolbarbuttons"}%%TMPL:P{"history_history_link"}%%TMPL:END%

View any topic with ?skin=myskin,pattern, or set the SKIN preference to myskin,pattern.

View any topic with ?skin=myskin,pattern, or set the SKIN preference to myskin,pattern.

This will remove the Edit and Attach buttons, and place a History button at the top.

This will remove the Edit and Attach buttons, and place a History button at the top.

You will probably not just want to have the History button there. Other button include names are:

You will probably not just want to have the History button there. Other button include names are:

create_topic_link
raw_edit_link
view_topic_link
activatable_attach
activatable_edit_or_create
more_link
activatable_printable
backlinks_web_link
backlinks_all_link
backlinks_link
history_rdiff_link
history_history_link
raw_link

create_topic_link
raw_edit_link
view_topic_link
activatable_attach
activatable_edit_or_create
more_link
activatable_printable
backlinks_web_link
backlinks_all_link
backlinks_link
history_rdiff_link
history_history_link
raw_link

Other page parts

Other page parts

I want to insert text outside of the topic content

I want to insert text outside of the topic content

PatternSkin has 2 'buckets' to write additional content to: contentheader and contentfooter, both defined in view.pattern.tmpl. These containers can contain text or html and are placed directly before and after the topic text.

PatternSkin has 2 'buckets' to write additional content to: contentheader and contentfooter, both defined in view.pattern.tmpl. These containers can contain text or html and are placed directly before and after the topic text.

Both modules are wrapped in CSS containers:

Both modules are wrapped in CSS containers:

• contentheader - wrapped in div of class foswikiContentHeader
• contentfooter - wrapped in div of class foswikiContentFooter

• contentheader - wrapped in div of class foswikiContentHeader
• contentfooter - wrapped in div of class foswikiContentFooter

To put contents before the main text, use the custom skin approach as described above.
So our custom template contains:

To put contents before the main text, use the custom skin approach as described above.
So our custom template contains:

%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"contentheader"}%This is the text before%TMPL:END%

%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"contentheader"}%This is the text before%TMPL:END%

Use the same procedure for contents to be put after the topic text:

Use the same procedure for contents to be put after the topic text:

%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"contentfooter"}%This is the text after%TMPL:END%

%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"contentfooter"}%This is the text after%TMPL:END%

I want to place the form at the top

I want to place the form at the top

Pattern skin has 2 buckets for the form: formtop (form at the top) and formbottom (form at the bottom). The default definition is:

Pattern skin has 2 buckets for the form: formtop (form at the top) and formbottom (form at the bottom). The default definition is:

%TMPL:DEF{"formtop"}%%TMPL:END%
%TMPL:DEF{"formbottom"}%%TMPL:P{"form"}%%TMPL:END%

%TMPL:DEF{"formtop"}%%TMPL:END%
%TMPL:DEF{"formbottom"}%%TMPL:P{"form"}%%TMPL:END%

You simply swap the bucket contents. Using either a template or a topic template, write in your custom template:

You simply swap the bucket contents. Using either a template or a topic template, write in your custom template:

%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"formtop"}%%TMPL:P{"form"}%%TMPL:END%
%TMPL:DEF{"formbottom"}%%TMPL:END%

%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"formtop"}%%TMPL:P{"form"}%%TMPL:END%
%TMPL:DEF{"formbottom"}%%TMPL:END%