PatternSkinCustomization < TWiki

---+!! !PatternSkin Customization

_Guidelines how to create and customize page templates of the %SYSTEMWEB%.PatternSkin._ For styling your TWiki using stylesheets, see PatternSkinCssCookbook.

%TOC%

---++ 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:
   1 By creating a custom skin file in the =templates= directory
   1 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 [[#TopicTemplates][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 TWiki 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* %BR%
Let's say you want to simplify the bottom toolbar and remove all links except for "More topic actions". You would need to target =%<nop>TMPL:DEF{"topicactionbuttons"}%=, which is located in =view.pattern.tmpl=.

*The steps you would need:*
   1 Think up a name for your skin. Let us use =myskin= for now.
   1 Create a new (empty) view template file in =/templates= called =view.myskin.tmpl=.
   1 In =view.myskin.tmpl= you write:
   <blockquote><verbatim>
   %TMPL:INCLUDE{"view"}%
   %TMPL:DEF{"top:toolbarbuttons"}%%TMPL:P{"more_link"}%%TMPL:END%</verbatim></blockquote>
   1 For testing, view any topic and append to the topic name: =?cover=myskin=. You should see an effect now.
   1 To make the changes visible on all pages, go to [[Main.TWikiPreferences]] (to keep %WIKIPREFSTOPIC% intact) and write:
<blockquote><pre>
   * <nop>Set COVER = myskin
</pre>
or write
<pre>
   * <nop>Set SKIN = myskin,pattern
</pre></blockquote>

Test by appending =?cover=myskin= to the url.


#TopicTemplates
---+++ 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 =Template=, for instance =BlogPostViewTemplate=.

Call this template by setting =VIEW_TEMPLATE=:
<blockquote>
<verbatim>
   * Set VIEW_TEMPLATE = BlogPostView
</verbatim>
</blockquote>
   * 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
   * On topic creation you can set the topic template by passing =templatetopic=:
   <verbatim>
   <input type="hidden" name="templatetopic" value="BlogPostViewTemplate" />
   </verbatim>

We can use the same example as above. In a topic write:
<blockquote>
<verbatim>
%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"top:toolbarbuttons"}%%TMPL:P{"more_link"}%%TMPL:END%
</verbatim>
</blockquote>

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

---++ Reference: pattern skin template INCLUDE tree

The =view= script invokes the =view= template:
<verbatim>
view
    twiki
        css
        viewtopbar
            %SYSTEMWEB%.WebTopBar
        viewleftbar
            %WEB%.WebLeftBar
        viewtopicactionbuttons
        viewbottombar
            %SYSTEMWEB%.WebBottomBar
</verbatim>

#ReadOnlySkinMode
---++ Read-only skin mode

The !PatternSkin can be turned into read-only mode. This is mainly useful if you have TWiki application pages or dashboards where you do not want regular users to change content. The read-only mode is enabled with a READONLYSKINMODE preferences setting set to 1 in the [[%LOCALSITEPREFS%]] (site level), in a WebPreferences (web level) or in any topic (page level):

<blockquote><pre>
   * Set <nop>READONLY<nop>SKINMODE = 1
</pre></blockquote>

If set, the edit and attach buttons on top, and the topic action bar at the bottom are removed. There is a hard to find edit link for people who need to edit content: The topic revision info at the bottom has a dash before the WikiName that is turned into an edit link, such as:%BR%
<blockquote>
Topic revision: r7 - 2011-05-18 [[%SCRIPTURL{edit}%/%WEB%/%TOPIC%?nowysiwyg=%SERVERTIME{$epoch}%][-]] [[%USERSWEB%.TWikiAdminUser][TWikiAdminUser]]
</blockquote>

%T% Please note that this is _not_ a replacement for access control, use it in addition to %SYSTEMWEB%.TWikiAccessControl.

---++ 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. <br />
The default variables that cause this behavior are defined in [[%WIKIPREFSTOPIC%]].

Redefine your custom variables in [[%LOCALSITEPREFS%]] (to keep %WIKIPREFSTOPIC% intact):
<blockquote><pre>
   * Set <nop>WEBLOGONAME = logo.gif
   * Set <nop>WEBLOGOIMG = %<nop>PUBURLPATH%/%<nop>BASEWEB%/%<nop>WEBPREFSTOPIC%/%<nop>WEBLOGONAME%
   * Set <nop>WEBLOGOURL = %<nop>SCRIPTURLPATH{"view"}%/%<nop>BASEWEB%/%<nop>HOMETOPIC%
   * Set <nop>WEBLOGOALT = Home
</pre></blockquote>

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

*Using logo.gif:*
<blockquote>
   * Create a new image named =logo.gif= and attach it to the web's WebPreferences topic. %SYSTEMWEB%.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 variables") and insert your logo name.
</blockquote>
*Using a new filename:*
<blockquote>
   * Attach whatever image and attach it to the web's WebPreferences topic. Then add to the WebPreferences (under _Custom web preferences_):
<pre>
      * Set <nop>WEBLOGONAME = your-logo-name.gif-or-png
</pre>
   * Copy the above instructions ("Redefine your custom variables") and insert your logo name.
</blockquote>

---+++ How do I set a site-wide logo?

There is a bunch of site-wide logo variables in [[%LOCALSITEPREFS%]]: =WIKILOGOIMG=, =WIKILOGOURL= and =WIKILOGOALT=.
To change only the web logo image to site-wide, in [[%LOCALSITEPREFS%]] set:
<blockquote><pre>
   * Set <nop>WEBLOGOIMG = %<nop>WIKILOGOIMG%
</pre></blockquote>

---+++ My logo does not fit the top bar

See [[#TopBarChangeHeight][I want to change the height of the top bar]]

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

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

---++ Top bar

---+++ The search box won't find topics in other webs


In %SYSTEMWEB%.WebTopBar you can find the line:
<verbatim>
<input type="hidden" name="web" value="%BASEWEB%" />
</verbatim>

To search all webs, write:
<blockquote>
<verbatim>
<input type="hidden" name="web" value="all" />
</verbatim>
</blockquote>

To search a couple of webs, for instance the webs Main and TWiki, write:
<blockquote>
<verbatim>
<input type="hidden" name="web" value="Main,TWiki" />
</verbatim>
</blockquote>

See also: [[%SYSTEMWEB%.VarSEARCH][Search variable]]

#TopBarChangeHeight
---+++ I want to change the height of the top bar

The top bar is 64 pixels high by default.

*Using templates:* %BR%
Using either a template or a topic template, copy this definition in your custom template:

<blockquote>
<verbatim>
%TMPL:DEF{"topbardimensions"}%
#patternTopBar,
#patternClearHeaderCenter,
#patternClearHeaderLeft,
#patternClearHeaderRight,
#patternTopBarContentsOuter {
	height:64px; /* top bar height; make room for header columns */
	overflow:hidden;
}
%TMPL:END%
</verbatim>
And change the number from 64px to a different value.
</blockquote>

*Using style sheets:*
<blockquote>
Create a new stylesheet with above definition in it, attach it to a topic and point =USERLAYOUTURL= to that topic attachment. See %SYSTEMWEB%.PatternSkinCssCookbook about creating custom styles.
</blockquote>

---+++ 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 variable =WEBHEADERART=, defined in [[%WIKIPREFSTOPIC%]].

Redefine your custom variables in [[%LOCALSITEPREFS%]] (to keep %WIKIPREFSTOPIC% intact):
<blockquote><pre>
   * <nop>Set WEBHEADERART = %<nop>PUBURLPATH%/%<nop>SYSTEMWEB%/PatternSkin/TWiki_header.gif
   * <nop>Set WEBHEADERBGCOLOR = somehexcolor (no quotes, for example: #ffffff)
</pre></blockquote>

You can also set =WEBHEADERART= per web, by defining the variable in the Web's !WebPreferences.

---+++ I want to have the web color in the top bar

Redefine =WEBHEADERBGCOLOR= in [[%LOCALSITEPREFS%]] (to keep %WIKIPREFSTOPIC% intact):
<blockquote><pre>
   * <nop>Set WEBHEADERBGCOLOR = %<nop>WEBBGCOLOR%
</pre></blockquote>

---+++ 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 %SYSTEMWEB%.WebTopBar.

---+++ I want to hide the top bar

*Using templates:*

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

<pre>
%<nop>TMPL:INCLUDE{"page"}%
%<nop>TMPL:INCLUDE{"viewtopbar"}%
%<nop>TMPL:INCLUDE{"viewtoolbar"}%
%<nop>TMPL:INCLUDE{"viewleftbar"}%
%<nop>TMPL:INCLUDE{"viewrightbar"}%
%<nop>TMPL:INCLUDE{"viewtopicactionbuttons"}%
%<nop>TMPL:INCLUDE{"viewbottombar"}%
</pre>

Each included template draws a part of the screen.%BR%
Omit =%<nop>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:

<blockquote><verbatim>
%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"topbar"}%%TMPL:END%
</verbatim>

and add:

<verbatim>
%TMPL:DEF{"topbardimensions"}%#patternTopBar,
#patternClearHeaderCenter,
#patternClearHeaderLeft,
#patternClearHeaderRight,
#patternTopBarContentsOuter {
	height:0px;
}%TMPL:END%
</verbatim></blockquote>

*Using style sheets:* %BR%
See PatternSkinCssCookbookNoTopBar

---++ Left bar

---+++ I want to hide the left bar

*Using templates:* %BR%
Omit =%<nop>TMPL:INCLUDE{"viewleftbar"}%= to hide the left bar, or in a custom template clear it using
<blockquote><verbatim>
%TMPL:DEF{"leftbar"}%%TMPL:END%
%TMPL:DEF{"leftbardimensions"}%%TMPL:END%
</verbatim></blockquote>

*Using style sheets:* %BR%
See PatternSkinCssCookbookNoLeftBar

---+++ I want to make the left bar wider

*Using templates:* %BR%

The left bar is 12 em wide by default.

*Using templates:* %BR%
Using either a template or a topic template, copy this definition in your custom template:

<blockquote>
<verbatim>
%TMPL:DEF{"leftbardimensions"}%#patternOuter {
	margin-left:12em;
}
#patternLeftBar {
	width:12em;
	margin-left:-12em;
}%TMPL:END%
</verbatim>
And change the number from 12em to a different value (3 occurrences).
</blockquote>



---++ Buttons

---+++ I want to hide the edit buttons from certain users

It may defy the wiki-ness of your TWiki 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:
<blockquote><pre>
%<nop>TMPL:INCLUDE{"view"}%
%<nop>TMPL:DEF{"top:toolbarbuttons"}%%TMPL:END%
%<nop>TMPL:DEF{"topicaction"}%%TMPL:END%
</pre></blockquote>

In the user page of %USERSWEB%.TWikiGuest, set the cover to
<blockquote><pre>
   * <nop>Set COVER = customer
</pre></blockquote>

By default this topic is editable only by TWiki 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=
<blockquote><verbatim>
%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%
</verbatim></blockquote>

To hide that link, In a custom skin view template =view.myskin.tmpl= empty =action_revisions= by replacing it with an empty string:
<blockquote><verbatim>
%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"action_revisions"}%%TMPL:END%
</verbatim></blockquote>


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

The default definition in =view.pattern.tmpl= is:
<verbatim>
%TMPL:DEF{"top:toolbarbuttons"}%%TMPL:P{"activatable_edit_or_create"}%%TMPL:P{"activatable_attach"}%%TMPL:END%
</verbatim>

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

<blockquote><verbatim>
%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"top:toolbarbuttons"}%%TMPL:P{"history_history_link"}%%TMPL:END%
</verbatim></blockquote>

View any topic with =?skin=myskin,pattern=, or set the =SKIN= variable 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:
<blockquote><verbatim>
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
</verbatim></blockquote>


---++ 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 =twikiContentHeader=
   * =contentfooter= - wrapped in =div= of class =twikiContentFooter=
   
To put contents *before* the main text, use the custom skin approach as described above.%BR%
So our custom template contains:
<blockquote><verbatim>
%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"contentheader"}%This is the text before%TMPL:END%
</verbatim></blockquote>

Use the same procedure for contents to be put *after* the topic text:
<blockquote><verbatim>
%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"contentfooter"}%This is the text after%TMPL:END%
</verbatim></blockquote>

---+++ 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:

<blockquote>
<verbatim>
%TMPL:DEF{"formtop"}%%TMPL:END%
%TMPL:DEF{"formbottom"}%%TMPL:P{"form"}%%TMPL:END%
</verbatim>
</blockquote>

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

<blockquote>
<verbatim>
%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"formtop"}%%TMPL:P{"form"}%%TMPL:END%
%TMPL:DEF{"formbottom"}%%TMPL:END%
</verbatim>
</blockquote>

---+++ I want to put the topic form in a twisty

The attachment tables are placed in a open/close twisty. You can do the same for the topic form.

Edit =templates/formtables.pattern.tmpl= to have this code:
<verbatim>
%{ These templates define the form attached at the bottom of viewed page. }%

%TMPL:DEF{"starttopicformwisty"}%%TWISTY{id="topicformlist" mode="div" remember="on" link="%MAKETEXT{"Form"}%" showimgleft="%ICONURLPATH{toggleopen}%" hideimgleft="%ICONURLPATH{toggleclose}%"}%%TMPL:END%

%TMPL:DEF{"endtopicformwisty"}%%ENDTWISTY%%TMPL:END%

%{ Start of form table }%
%TMPL:DEF{FORM:display:header}%<div class="twikiForm">%TMPL:P{"starttopicformwisty"}%
<table class='twikiFormTable' border='1'>%TMPL:P{FORM:display:header:headerrow}%%TMPL:END%

%{ Header }%
%TMPL:DEF{FORM:display:header:headerrow}%<tr><th class='twikiFormTableHRow twikiFirstCol' colspan='2'>
[[%A_TITLE%]]
</th></tr>%TMPL:END%

%{ Each row }%
%TMPL:DEF{FORM:display:row}%<tr valign='top'><td class='twikiFormTableRow twikiFirstCol' align='right'> %A_TITLE% </td><td>
%A_VALUE%
</td></tr>%TMPL:END%

%{ Footer }%
%TMPL:DEF{FORM:display:footer}%</table>%TMPL:P{FORM:display:footer:editlink}%
%TMPL:P{"endtopicformwisty"}%</div><!-- /twikiForm -->%TMPL:END%
</verbatim>

To give the twisty toggle link the same style as the attachment twisty link, add this to pattern skin's =style.css=:
<verbatim>
.twikiForm .twistyTrigger .twikiLinkLabel {
   font-size:122%; /* h4 size */
   font-weight:bold;
}
</verbatim>
This topic: TWiki > PatternSkinCustomization
Topic revision: r12 - 2013-03-21 - TWikiContributor
Copyright © 1999-2024 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.PatternSkinCustomization.