data/TWiki/PatternSkinCustomization.txt
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
permissions -rw-r--r--
RELEASE 4.2.0 freetown
colas@0
     1
%META:TOPICINFO{author="TWikiContributor" date="1130019100" format="1.1" version="7"}%
colas@0
     2
colas@0
     3
---+!! %SYSTEMWEB%.PatternSkin Customization
colas@0
     4
colas@0
     5
*Questions and answers on configuring page elements.* For styling your TWiki, see PatternSkinCssCookbook.
colas@0
     6
colas@0
     7
%TOC%
colas@0
     8
colas@0
     9
---++ First Read: How to modify !PatternSkin templates
colas@0
    10
colas@0
    11
Everything you see on the common 'view' page is written by the =view= template. For pattern skin this file is =/templates/view.pattern.tmpl=.
colas@0
    12
colas@0
    13
We describe two approaches to override this template:
colas@0
    14
   1 By creating a custom skin file in the =templates= directory
colas@0
    15
   1 By creating a custom topic template
colas@0
    16
colas@0
    17
Which approach is best?
colas@0
    18
   * If you want to change the appearance for a lot of pages or even site-wide, the template approach is the easiest.
colas@0
    19
   * If you want to change the appearance of a single topic, or a set of topics, use a topic template.
colas@0
    20
colas@0
    21
---+++ The template approach
colas@0
    22
colas@0
    23
To change templates you will need shell access. If you don't have this read on below in [[#TopicTemplates][The topic template approach]].
colas@0
    24
colas@0
    25
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.
colas@0
    26
colas@0
    27
*Example* %BR%
colas@0
    28
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=.
colas@0
    29
colas@0
    30
*The steps you would need:*
colas@0
    31
   1 Think up a name for your skin. Let us use =myskin= for now.
colas@0
    32
   1 Create a new (empty) view template file in =/templates= called =view.myskin.tmpl=.
colas@0
    33
   1 In =view.myskin.tmpl= you write:
colas@0
    34
   <blockquote><verbatim>
colas@0
    35
   %TMPL:INCLUDE{"view"}%
colas@0
    36
   %TMPL:DEF{"topicactionbuttons"}%%TMPL:P{"activatable_more"}%%TMPL:END%</verbatim></blockquote>
colas@0
    37
   1 For testing, view any topic and append to the topic name: =?cover=myskin=. You should see an effect now.
colas@0
    38
   1 To make the changes visible on all pages, go to [[Main.TWikiPreferences]] (to keep %WIKIPREFSTOPIC% intact) and write:
colas@0
    39
<blockquote><pre>
colas@0
    40
   * <nop>Set COVER = myskin
colas@0
    41
</pre>
colas@0
    42
or write
colas@0
    43
<pre>
colas@0
    44
   * <nop>Set SKIN = myskin,pattern
colas@0
    45
</pre></blockquote>
colas@0
    46
colas@0
    47
Test by appending =?cover=myskin= to the url.
colas@0
    48
colas@0
    49
colas@0
    50
#TopicTemplates
colas@0
    51
---+++ The topic template approach (using VIEW_TEMPLATE)
colas@0
    52
colas@0
    53
Template overrides can be written in a topic, a so-called _topic template_. Topic template names end with =Template=, for instance =BlogPostViewTemplate=.
colas@0
    54
colas@0
    55
Call this template by setting =VIEW_TEMPLATE=:
colas@0
    56
<blockquote>
colas@0
    57
<verbatim>
colas@0
    58
   * Set VIEW_TEMPLATE = BlogPostView
colas@0
    59
</verbatim>
colas@0
    60
</blockquote>
colas@0
    61
   * Note that you don't use the =Template= extension now
colas@0
    62
   * You can make this setting hidden by writing this in the Settings screen: go to More and then Topic Settings
colas@0
    63
   * On topic creation you can set the topic template by passing =templatetopic=:
colas@0
    64
   <verbatim>
colas@0
    65
   <input type="hidden" name="templatetopic" value="BlogPostViewTemplate" />
colas@0
    66
   </verbatim>
colas@0
    67
colas@0
    68
We can use the same example as above. In a topic write:
colas@0
    69
<blockquote>
colas@0
    70
<verbatim>
colas@0
    71
%TMPL:INCLUDE{"view"}%
colas@0
    72
%TMPL:DEF{"topicactionbuttons"}%%TMPL:P{"activatable_more"}%%TMPL:END%
colas@0
    73
</verbatim>
colas@0
    74
</blockquote>
colas@0
    75
colas@0
    76
You can also test this by appending =?template=PersonalInfoView= to the url.
colas@0
    77
colas@0
    78
---++ Reference: pattern skin template INCLUDE tree
colas@0
    79
colas@0
    80
<verbatim>
colas@0
    81
view
colas@0
    82
    page
colas@0
    83
        constants
colas@0
    84
        javascript
colas@0
    85
        styles
colas@0
    86
            stylesdynamic
colas@0
    87
        body
colas@0
    88
            viewtopbar
colas@0
    89
                %SYSTEMWEB%.WebTopBar
colas@0
    90
            viewtoolbar
colas@0
    91
            viewleftbar
colas@0
    92
                %WEB%.WebLeftBar
colas@0
    93
            viewtopicactionbuttons
colas@0
    94
            viewbottombar
colas@0
    95
                %SYSTEMWEB%.WebBottomBar
colas@0
    96
</verbatim>
colas@0
    97
colas@0
    98
---++ Logo
colas@0
    99
colas@0
   100
---+++ How can I change the web logo?
colas@0
   101
colas@0
   102
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 />
colas@0
   103
The default variables that cause this behavior are defined in [[%WIKIPREFSTOPIC%]].
colas@0
   104
colas@0
   105
Redefine your custom variables in [[%LOCALSITEPREFS%]] (to keep %WIKIPREFSTOPIC% intact):
colas@0
   106
<blockquote><pre>
colas@0
   107
   * Set <nop>WEBLOGONAME = logo.gif
colas@0
   108
   * Set <nop>WEBLOGOIMG = %<nop>PUBURLPATH%/%<nop>BASEWEB%/%<nop>WEBPREFSTOPIC%/%<nop>WEBLOGONAME%
colas@0
   109
   * Set <nop>WEBLOGOURL = %<nop>SCRIPTURLPATH{"view"}%/%<nop>BASEWEB%/%<nop>HOMETOPIC%
colas@0
   110
   * Set <nop>WEBLOGOALT = Home
colas@0
   111
</pre></blockquote>
colas@0
   112
colas@0
   113
There are 2 ways to change the logo in a web:
colas@0
   114
colas@0
   115
*Using logo.gif:*
colas@0
   116
<blockquote>
colas@0
   117
   * 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.
colas@0
   118
   * You can also upload the image with FTP to =/pub/YourWeb/WebPreferences/=.
colas@0
   119
   * Copy the above instructions ("Redefine your custom variables") and insert your logo name.
colas@0
   120
</blockquote>
colas@0
   121
*Using a new filename:*
colas@0
   122
<blockquote>
colas@0
   123
   * Attach whatever image and attach it to the web's WebPreferences topic. Then add to the WebPreferences (under _Custom web preferences_):
colas@0
   124
<pre>
colas@0
   125
      * Set <nop>WEBLOGONAME = your-logo-name.gif-or-png
colas@0
   126
</pre>
colas@0
   127
   * Copy the above instructions ("Redefine your custom variables") and insert your logo name.
colas@0
   128
</blockquote>
colas@0
   129
colas@0
   130
---+++ How do I set a site-wide logo?
colas@0
   131
colas@0
   132
There is a bunch of site-wide logo variables in [[%LOCALSITEPREFS%]]: =WIKILOGOIMG=, =WIKILOGOURL= and =WIKILOGOALT=.
colas@0
   133
To change only the web logo image to site-wide, in [[%LOCALSITEPREFS%]] set:
colas@0
   134
<blockquote><pre>
colas@0
   135
   * Set <nop>WEBLOGOIMG = %<nop>WIKILOGOIMG%
colas@0
   136
</pre></blockquote>
colas@0
   137
colas@0
   138
---+++ My logo does not fit the top bar
colas@0
   139
colas@0
   140
See [[#TopBarChangeHeight][I want to change the height of the top bar]]
colas@0
   141
colas@0
   142
---+++ I want to change the white space above and below the logo
colas@0
   143
colas@0
   144
Change the table style in topic %SYSTEMWEB%.WebTopBar. The default top padding is 11px.
colas@0
   145
colas@0
   146
---++ Top bar
colas@0
   147
colas@0
   148
---+++ The search box won't find topics in other webs
colas@0
   149
colas@0
   150
colas@0
   151
In TWiki.WebTopBar you can find the line:
colas@0
   152
<verbatim>
colas@0
   153
<input type="hidden" name="web" value="%BASEWEB%" />
colas@0
   154
</verbatim>
colas@0
   155
colas@0
   156
To search all webs, write:
colas@0
   157
<blockquote>
colas@0
   158
<verbatim>
colas@0
   159
<input type="hidden" name="web" value="all" />
colas@0
   160
</verbatim>
colas@0
   161
</blockquote>
colas@0
   162
colas@0
   163
To search a couple of webs, for instance the webs Main and TWiki, write:
colas@0
   164
<blockquote>
colas@0
   165
<verbatim>
colas@0
   166
<input type="hidden" name="web" value="Main,TWiki" />
colas@0
   167
</verbatim>
colas@0
   168
</blockquote>
colas@0
   169
colas@0
   170
See also: [[TWiki.VarSEARCH][Search variable]]
colas@0
   171
colas@0
   172
#TopBarChangeHeight
colas@0
   173
---+++ I want to change the height of the top bar
colas@0
   174
colas@0
   175
The top bar is 64 pixels high by default.
colas@0
   176
colas@0
   177
*Using templates:* %BR%
colas@0
   178
Using either a template or a topic template, copy this definition in your custom template:
colas@0
   179
colas@0
   180
<blockquote>
colas@0
   181
<verbatim>
colas@0
   182
%TMPL:DEF{"topbardimensions"}%
colas@0
   183
#patternTopBar,
colas@0
   184
#patternClearHeaderCenter,
colas@0
   185
#patternClearHeaderLeft,
colas@0
   186
#patternClearHeaderRight,
colas@0
   187
#patternTopBarContentsOuter {
colas@0
   188
	height:64px; /* top bar height; make room for header columns */
colas@0
   189
	overflow:hidden;
colas@0
   190
}
colas@0
   191
%TMPL:END%
colas@0
   192
</verbatim>
colas@0
   193
And change the number from 64px to a different value.
colas@0
   194
</blockquote>
colas@0
   195
colas@0
   196
*Using style sheets:*
colas@0
   197
<blockquote>
colas@0
   198
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.
colas@0
   199
</blockquote>
colas@0
   200
colas@0
   201
---+++ I want to set or change the top background image
colas@0
   202
colas@0
   203
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%]].
colas@0
   204
colas@0
   205
Redefine your custom variables in [[%LOCALSITEPREFS%]] (to keep %WIKIPREFSTOPIC% intact):
colas@0
   206
<blockquote><pre>
colas@0
   207
   * <nop>Set WEBHEADERART = %<nop>PUBURLPATH%/%<nop>SYSTEMWEB%/PatternSkin/TWiki_header.gif
colas@0
   208
   * <nop>Set WEBHEADERBGCOLOR = somehexcolor (no quotes, for example: #ffffff)
colas@0
   209
</pre></blockquote>
colas@0
   210
colas@0
   211
You can also set =WEBHEADERART= per web, by defining the variable in the Web's !WebPreferences.
colas@0
   212
colas@0
   213
---+++ I want to have the web color in the top bar
colas@0
   214
colas@0
   215
Redefine =WEBHEADERBGCOLOR= in [[%LOCALSITEPREFS%]] (to keep %WIKIPREFSTOPIC% intact):
colas@0
   216
<blockquote><pre>
colas@0
   217
   * <nop>Set WEBHEADERBGCOLOR = %<nop>WEBBGCOLOR%
colas@0
   218
</pre></blockquote>
colas@0
   219
colas@0
   220
---+++ I want to remove the Jump and Search boxes from the top bar 
colas@0
   221
colas@0
   222
If you have localization enabled, you will also see a language dropdown box at the far right.
colas@0
   223
colas@0
   224
You can remove these items from %SYSTEMWEB%.WebTopBar.
colas@0
   225
colas@0
   226
---+++ I want to hide the top bar
colas@0
   227
colas@0
   228
*Using templates:*
colas@0
   229
colas@0
   230
The view template is populated with page elements using template inclusions:
colas@0
   231
colas@0
   232
<pre>
colas@0
   233
%<nop>TMPL:INCLUDE{"page"}%
colas@0
   234
%<nop>TMPL:INCLUDE{"viewtopbar"}%
colas@0
   235
%<nop>TMPL:INCLUDE{"viewtoolbar"}%
colas@0
   236
%<nop>TMPL:INCLUDE{"viewleftbar"}%
colas@0
   237
%<nop>TMPL:INCLUDE{"viewrightbar"}%
colas@0
   238
%<nop>TMPL:INCLUDE{"viewtopicactionbuttons"}%
colas@0
   239
%<nop>TMPL:INCLUDE{"viewbottombar"}%
colas@0
   240
</pre>
colas@0
   241
colas@0
   242
Each included template draws a part of the screen.%BR%
colas@0
   243
Omit =%<nop>TMPL:INCLUDE{"viewtopbar"}%= to hide the top bar.
colas@0
   244
colas@0
   245
Another approach is to clear the contents of module =topbar=. Using either a template or a topic template, write in your custom template:
colas@0
   246
colas@0
   247
<blockquote><verbatim>
colas@0
   248
%TMPL:INCLUDE{"view"}%
colas@0
   249
%TMPL:INCLUDE{"topbar"}%%TMPL:END%
colas@0
   250
</verbatim>
colas@0
   251
colas@0
   252
and add:
colas@0
   253
colas@0
   254
<verbatim>
colas@0
   255
%TMPL:DEF{"topbardimensions"}%#patternTopBar,
colas@0
   256
#patternClearHeaderCenter,
colas@0
   257
#patternClearHeaderLeft,
colas@0
   258
#patternClearHeaderRight,
colas@0
   259
#patternTopBarContentsOuter {
colas@0
   260
	height:0px;
colas@0
   261
}%TMPL:END%
colas@0
   262
</verbatim></blockquote>
colas@0
   263
colas@0
   264
*Using style sheets:* %BR%
colas@0
   265
See PatternSkinCssCookbookNoTopBar
colas@0
   266
colas@0
   267
---++ Left bar
colas@0
   268
colas@0
   269
---+++ I want to hide the left bar
colas@0
   270
colas@0
   271
*Using templates:* %BR%
colas@0
   272
Omit =%<nop>TMPL:INCLUDE{"viewleftbar"}%= to hide the left bar, or in a custom template clear it using
colas@0
   273
<blockquote><verbatim>
colas@0
   274
%TMPL:DEF{"viewleftbar"}%%TMPL:END%
colas@0
   275
</verbatim></blockquote>
colas@0
   276
colas@0
   277
*Using style sheets:* %BR%
colas@0
   278
See PatternSkinCssCookbookNoLeftBar
colas@0
   279
colas@0
   280
---+++ I want to make the left bar wider
colas@0
   281
colas@0
   282
*Using templates:* %BR%
colas@0
   283
colas@0
   284
The left bar is 12 em wide by default.
colas@0
   285
colas@0
   286
*Using templates:* %BR%
colas@0
   287
Using either a template or a topic template, copy this definition in your custom template:
colas@0
   288
colas@0
   289
<blockquote>
colas@0
   290
<verbatim>
colas@0
   291
%TMPL:DEF{"leftbardimensions"}%#patternOuter {
colas@0
   292
	margin-left:12em;
colas@0
   293
}
colas@0
   294
#patternLeftBar {
colas@0
   295
	width:12em;
colas@0
   296
	margin-left:-12em;
colas@0
   297
}%TMPL:END%
colas@0
   298
</verbatim>
colas@0
   299
And change the number from 12em to a different value (3 occurrences).
colas@0
   300
</blockquote>
colas@0
   301
colas@0
   302
colas@0
   303
---++ Other page parts
colas@0
   304
colas@0
   305
---+++ I want to hide the edit buttons from certain users
colas@0
   306
colas@0
   307
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.
colas@0
   308
colas@0
   309
Using either a template or a topic template, 'empty' =topicaction= and =toolbar= by writing:
colas@0
   310
<blockquote><pre>
colas@0
   311
%<nop>TMPL:INCLUDE{"view"}%
colas@0
   312
%<nop>TMPL:DEF{"topicaction"}%%TMPL:END%
colas@0
   313
%<nop>TMPL:DEF{"toolbar"}%%TMPL:END%
colas@0
   314
</pre></blockquote>
colas@0
   315
colas@0
   316
In the user page of %USERSWEB%.TWikiGuest, set the cover to
colas@0
   317
<blockquote><pre>
colas@0
   318
   * <nop>Set COVER = customer
colas@0
   319
</pre></blockquote>
colas@0
   320
colas@0
   321
By default this topic is editable only by TWiki admins.
colas@0
   322
colas@0
   323
---+++ I want to remove the History button from the bottom
colas@0
   324
colas@0
   325
All action buttons are defined in =viewtopicactionbuttons.pattern.tmpl=. The history buttons or in module =revisions=:
colas@0
   326
<blockquote><code style="white-space:pre">
colas@0
   327
%<nop>TMPL:DEF{"topicactionbuttons"}%%<nop>TMPL:P{"activatable_raw_edit"}%%<nop>TMPL:P{"sep"}%
colas@0
   328
%<nop>TMPL:P{context="WysiwygPluginEnabled" then="activatable_edit_wysiwyg"}%
colas@0
   329
%<nop>TMPL:P{context="WysiwygPluginEnabled" then="sep"}%
colas@0
   330
%<nop>TMPL:P{"activatable_attach"}%%<nop>TMPL:P{"sep"}%
colas@0
   331
%<nop>TMPL:P{"printable"}%%<nop>TMPL:P{"sep"}%
colas@0
   332
%<nop>TMPL:P{"raw"}%%<nop>TMPL:P{"sep"}%
colas@0
   333
%<nop>TMPL:P{"backlinks"}%%<nop>TMPL:P{"sep"}%
colas@0
   334
%<nop>TMPL:P{"revisions"}%%<nop>TMPL:P{"sep"}% <span style="color:red">&lt; HERE</span>
colas@0
   335
%<nop>TMPL:P{"activatable_more"}%%<nop>TMPL:END%
colas@0
   336
</code>
colas@0
   337
</blockquote>
colas@0
   338
colas@0
   339
If we emptied module =revisions= we would end up with 2 separators, so we need to remove the line altogether. We do this by copying the block and omitting the line. %BR%
colas@0
   340
Using either a template or a topic template, to remove the history buttons write in your custom template:
colas@0
   341
colas@0
   342
<blockquote><verbatim>
colas@0
   343
%TMPL:INCLUDE{"view"}%
colas@0
   344
colas@0
   345
%TMPL:DEF{"topicactionbuttons"}%%TMPL:P{"activatable_raw_edit"}%%TMPL:P{"sep"}%
colas@0
   346
%TMPL:P{context="WysiwygPluginEnabled" then="activatable_edit_wysiwyg"}%
colas@0
   347
%TMPL:P{context="WysiwygPluginEnabled" then="sep"}%
colas@0
   348
%TMPL:P{"activatable_attach"}%%TMPL:P{"sep"}%
colas@0
   349
%TMPL:P{"printable"}%%TMPL:P{"sep"}%
colas@0
   350
%TMPL:P{"raw"}%%TMPL:P{"sep"}%
colas@0
   351
%TMPL:P{"backlinks"}%%TMPL:P{"sep"}%
colas@0
   352
%TMPL:P{"activatable_more"}%%TMPL:END%
colas@0
   353
</verbatim>
colas@0
   354
colas@0
   355
Remove all newlines if you copy-paste above text.
colas@0
   356
</blockquote>
colas@0
   357
colas@0
   358
---+++ I want to insert text outside of the topic content
colas@0
   359
colas@0
   360
!PatternSkin has 2 'buckets' to write additional content to: =beforetextcontents= and =aftertextcontents=, both defined in =view.pattern.tmpl=. These containers can contain text or html and are placed directly before and after the topic text.
colas@0
   361
colas@0
   362
Both modules are wrapped in CSS containers:
colas@0
   363
   * =beforetextcontents= - wrapped in =div= of class =twikiBeforeText=
colas@0
   364
   * =aftertextcontents= - wrapped in =div= of class =twikiAfterText=
colas@0
   365
   
colas@0
   366
To put contents *before* the main text, use the custom skin approach as described above.%BR%
colas@0
   367
So our custom template contains:
colas@0
   368
<blockquote><verbatim>
colas@0
   369
%TMPL:INCLUDE{"view"}%
colas@0
   370
%TMPL:DEF{"beforetextcontents"}%This is the text before%TMPL:END%
colas@0
   371
</verbatim></blockquote>
colas@0
   372
colas@0
   373
Use the same procedure for contents to be put *after* the topic text:
colas@0
   374
<blockquote><verbatim>
colas@0
   375
%TMPL:INCLUDE{"view"}%
colas@0
   376
%TMPL:DEF{"aftertextcontents"}%This is the text after%TMPL:END%
colas@0
   377
</verbatim></blockquote>
colas@0
   378
colas@0
   379
---+++ I want to place the form at the top
colas@0
   380
colas@0
   381
Pattern skin has 2 buckets for the form: =formattop= (form-at-the-top) and =formatbottom= (form-at-the-bottom):
colas@0
   382
colas@0
   383
<blockquote>
colas@0
   384
<verbatim>
colas@0
   385
%TMPL:DEF{"formattop"}%%TMPL:END%
colas@0
   386
%TMPL:DEF{"formatbottom"}%%TMPL:P{"form"}%%TMPL:END%
colas@0
   387
</verbatim>
colas@0
   388
</blockquote>
colas@0
   389
colas@0
   390
You simply swap the bucket contents. Using either a template or a topic template, write in your custom template:
colas@0
   391
colas@0
   392
<blockquote>
colas@0
   393
<verbatim>
colas@0
   394
%TMPL:INCLUDE{"view"}%
colas@0
   395
%TMPL:DEF{"formattop"}%%TMPL:P{"form"}%%TMPL:END%
colas@0
   396
%TMPL:DEF{"formatbottom"}%%TMPL:END%
colas@0
   397
</verbatim>
colas@0
   398
</blockquote>
colas@0
   399
colas@0
   400
---+++ I only want to show the WYSIWYG button on explicit pages
colas@0
   401
In [[Main.TWikiPreferences]], set =COMPOSER= to a blank value:
colas@0
   402
<blockquote>
colas@0
   403
<verbatim>
colas@0
   404
   * Set COMPOSER =
colas@0
   405
</verbatim>
colas@0
   406
</blockquote>
colas@0
   407
   
colas@0
   408
In the topic, set the =COMPOSER= variable to =kupu=:
colas@0
   409
<blockquote>
colas@0
   410
<verbatim>
colas@0
   411
   * Set COMPOSER = kupu
colas@0
   412
</verbatim>
colas@0
   413
</blockquote>
colas@0
   414