Guidelines how to create and customize page templates. For styling your Foswiki using stylesheets, see
PatternSkinCssCookbook.
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
.
We describe two approaches to override this template:
- By creating a custom skin file in the
templates
directory
- By creating a custom topic template
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.
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.
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
.
The steps you would need:
- Think up a name for your skin. Let us use
myskin
for now.
- Create a new (empty) view template file in
/templates
called view.myskin.tmpl
.
- In
view.myskin.tmpl
you write:
%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"topicactionbuttons"}%%TMPL:P{"more_link"}%%TMPL:END%
- For testing, view any topic and append to the topic name:
?cover=myskin
. You should see an effect now.
- 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.
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
.
Call this template by setting
VIEW_TEMPLATE
:
* 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
We can use the same example as above, but extend it to also replace the Edit and Print buttons at the top with a
More Actions button. 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:DEF{"topicactionbuttons"}%%TMPL:P{"more_link"}%%TMPL:END%
You can also test this by appending
?template=OnlyMoreView
to the url.
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.)
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.
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.
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
There are 2 ways to change the logo in a web:
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/
(if permitted by your server configuration).
- Copy the above instructions ("Redefine your custom preference settings") and insert your logo name.
Using a new filename:
* 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?
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%
Top bar
Customizing the Top bar
Foswiki ships with
WebTopBarExample. In order to tailor the Top
bar, navigate to
WebTopBarExample and use the
More topic actions
link to copy it to WebTopBar. Note that although the name suggest
that this is "per web", the WebTopBar is a site-wide setting.
My logo does not fit the top bar
See
I want to change the height of the top bar in the
PatternSkinCssCookbook
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.
The search box won't find topics in other webs
In WebTopBar you can find the line:
<input type="hidden" name="web" value="%BASEWEB%" />
To search all webs, write:
<input type="hidden" name="web" value="all" />
To search a couple of webs, for instance the webs Main and System, write:
<input type="hidden" name="web" value="Main,System" />
See also:
Search macro
I want to change the height of the top bar
This information has moved to PatternSkinCssCookbook
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.
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)
You can also set
WEBHEADERART
per web, by setting the preference in the Web's
WebPreferences.
Note: For more precise control, the top bar can be controlled using CSS, however: If WEBHEADERART defaults, or is set to anything other than the empty string, the CSS for the
#foswikiTopBarContents
is expanded inline from
templates/css.pattern.tmpl
. Overrides using css files will not be possible.
I want to have the web color in the top bar
Redefine
WEBHEADERBGCOLOR
in
SitePreferences (to keep
DefaultPreferences intact):
* Set WEBHEADERBGCOLOR = %WEBBGCOLOR%
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.
You can remove these items from WebTopBar.
I want to hide the top bar
Using templates:
The view template is populated with page elements using template inclusions:
%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.
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%
and add:
%TMPL:DEF{"topbardimensions"}%#patternTopBar,
#patternClearHeaderCenter,
#patternClearHeaderLeft,
#patternClearHeaderRight {
height:0px;
}%TMPL:END%
Using style sheets:
See
PatternSkinCssCookbookNoTopBar
Left bar
I want to customize the side bar
In order to customize your left bar in each web, just copy
YourWeb.WebLeftBarExample to
YourWeb.WebLeftBar an put your customizations there.
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
%TMPL:DEF{"sidebar"}%%TMPL:END%
Using style sheets:
See
PatternSkinCssCookbookNoLeftBar
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:
%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"top:toolbarbuttons"}%%TMPL:END%
%TMPL:DEF{"topicaction"}%%TMPL:END%
In the user page of
WikiGuest, set the cover to
* Set COVER = customer
By default this topic is editable only by Wiki admins.
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
%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:
%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"action_revisions"}%%TMPL:END%
The default definition in
view.pattern.tmpl
is:
%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:
%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
.
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:
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
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.
Both modules are wrapped in CSS containers:
-
contentheader
- wrapped in div
of class foswikiContentHeader
. Expands beforetext
template.
-
contentfooter
- wrapped in div
of class foswikiContentFooter
. Expands aftertext
template.
Note: the
contentheader
and
contentfooter
templates are
PatternSkin specific names for the
beforetext
and
aftertext
templates. For best
compatibility with other skins, you should override
beforetext
, and/or
aftertext
.
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{"beforetext"}%This is the text before%TMPL:END%
Use the same procedure for contents to be put
after the topic text:
%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"aftertext"}%This is the text after%TMPL:END%
Hint: These templates are often used by
extensions to add to the page above or below the topic contents. Rather than
simply replacing them, consider extending them by using the
TMPL:PREV
option
to expand the previous definition of the template.
%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"beforetext"}%This text prefaces other aftertext templates.%TMPL:PREV%%TMPL:END%
%TMPL:DEF{"aftertext"}%%TMPL:PREV%This text extends other aftertext templates.%TMPL:END%
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%
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%