TWiki/PatternSkinCustomization.mdwn

   1 # <a name="TWiki._PatternSkin Customization"></a><a name=" TWiki._PatternSkin Customizatio"></a> [[PatternSkin]] Customization
   2
   3 **Guidelines how to create and customize page templates.** For styling your TWiki using stylesheets, see [[PatternSkinCssCookbook]].
   4
   5 <div>
   6   <ul>
   7     <li><a href="#First Read: How to modify _Patt"> First Read: How to modify PatternSkin templates</a><ul>
   8         <li><a href="#The template approach"> The template approach</a></li>
   9         <li><a href="#The topic template approach (usi"> The topic template approach (using VIEW_TEMPLATE)</a></li>
  10       </ul>
  11     </li>
  12     <li><a href="#Reference: pattern skin template"> Reference: pattern skin template INCLUDE tree</a></li>
  13     <li><a href="#Logo"> Logo</a><ul>
  14         <li><a href="#How can I change the web logo?"> How can I change the web logo?</a></li>
  15         <li><a href="#How do I set a site-wide logo?"> How do I set a site-wide logo?</a></li>
  16         <li><a href="#My logo does not fit the top bar"> My logo does not fit the top bar</a></li>
  17         <li><a href="#I want to change the white space"> I want to change the white space above and below the logo</a></li>
  18       </ul>
  19     </li>
  20     <li><a href="#Top bar"> Top bar</a><ul>
  21         <li><a href="#The search box won't find topics"> The search box won't find topics in other webs</a></li>
  22         <li><a href="#I want to change the height of t"> I want to change the height of the top bar</a></li>
  23         <li><a href="#I want to set or change the top"> I want to set or change the top background image</a></li>
  24         <li><a href="#I want to have the web color in"> I want to have the web color in the top bar</a></li>
  25         <li><a href="#I want to remove the Jump and Se"> I want to remove the Jump and Search boxes from the top bar </a></li>
  26         <li><a href="#I want to hide the top bar"> I want to hide the top bar</a></li>
  27       </ul>
  28     </li>
  29     <li><a href="#Left bar"> Left bar</a><ul>
  30         <li><a href="#I want to hide the left bar"> I want to hide the left bar</a></li>
  31         <li><a href="#I want to make the left bar wide"> I want to make the left bar wider</a></li>
  32       </ul>
  33     </li>
  34     <li><a href="#Buttons"> Buttons</a><ul>
  35         <li><a href="#I want to hide the edit buttons"> I want to hide the edit buttons from certain users</a></li>
  36         <li><a href="#I want to remove the History but"> I want to remove the History button from the bottom</a></li>
  37         <li><a href="#I want to put the bottom links a"> I want to put the bottom links as buttons at the top</a></li>
  38       </ul>
  39     </li>
  40     <li><a href="#Other page parts"> Other page parts</a><ul>
  41         <li><a href="#I want to insert text outside of"> I want to insert text outside of the topic content</a></li>
  42         <li><a href="#I want to place the form at the"> I want to place the form at the top</a></li>
  43         <li><a href="#I want to put the topic form in"> I want to put the topic form in a twisty</a></li>
  44       </ul>
  45     </li>
  46   </ul>
  47 </div>
  48
  49 ## <a name="First Read: How to modify _Patte"></a> First Read: How to modify PatternSkin templates
  50
  51 Everything you see on the common 'view' page is written by the `view` template. For pattern skin this file is `/templates/view.pattern.tmpl`.
  52
  53 We describe two approaches to override this template:
  54
  55 1. By creating a custom skin file in the `templates` directory
  56 2. By creating a custom topic template
  57
  58 Which approach is best?
  59
  60 - If you want to change the appearance for a lot of pages or even site-wide, the template approach is the easiest.
  61 - If you want to change the appearance of a single topic, or a set of topics, use a topic template.
  62
  63 ### <a name="The template approach"></a> The template approach
  64
  65 To change templates you will need shell access. If you don't have this read on below in [[The topic template approach|Main/WebHome#TopicTemplates]].
  66
  67 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.
  68
  69 **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 `%TMPL:DEF{"topicactionbuttons"}%`, which is located in `view.pattern.tmpl`.
  70
  71 **The steps you would need:**
  72
  73 1. Think up a name for your skin. Let us use `myskin` for now.
  74 2. Create a new (empty) view template file in `/templates` called `view.myskin.tmpl`.
  75 3. In `view.myskin.tmpl` you write:
  76 > %TMPL:INCLUDE{"view"}%
  77 >        %TMPL:DEF{"top:toolbarbuttons"}%%TMPL:P{"more_link"}%%TMPL:END%
  78 4. For testing, view any topic and append to the topic name: `?cover=myskin`. You should see an effect now.
  79 5. To make the changes visible on all pages, go to [[Main.TWikiPreferences|Main/TWikiPreferences]] (to keep [[TWikiPreferences]] intact) and write:
  80
  81 > * Set COVER = myskin
  82 >
  83 > or write
  84 >
  85 >        * Set SKIN = myskin,pattern
  86
  87 Test by appending `?cover=myskin` to the url.
  88
  89 <a name="TopicTemplates"></a>
  90
  91 ### <a name="The topic template approach (usi"></a> The topic template approach (using VIEW\_TEMPLATE)
  92
  93 Template overrides can be written in a topic, a so-called _topic template_. Topic template names end with `Template`, for instance `BlogPostViewTemplate`.
  94
  95 Call this template by setting `VIEW_TEMPLATE`:
  96
  97 > * Set VIEW_TEMPLATE = BlogPostView
  98
  99 - Note that you don't use the `Template` extension now
 100 - You can make this setting hidden by writing this in the Settings screen: go to More and then Topic Settings
 101 - On topic creation you can set the topic template by passing `templatetopic`:
 102        <input type="hidden" name="templatetopic" value="BlogPostViewTemplate" />
 103
 104 We can use the same example as above. In a topic write:
 105
 106 > %TMPL:INCLUDE{"view"}%
 107 >     %TMPL:DEF{"top:toolbarbuttons"}%%TMPL:P{"more_link"}%%TMPL:END%
 108
 109 You can also test this by appending `?template=PersonalInfoView` to the url.
 110
 111 ## <a name="Reference: pattern skin template"></a> Reference: pattern skin template INCLUDE tree
 112
 113 The `view` script invokes the `view` template:
 114
 115     view
 116         twiki
 117             css
 118             viewtopbar
 119                 %TWIKIWEB%.WebTopBar
 120             viewleftbar
 121                 %WEB%.WebLeftBar
 122             viewtopicactionbuttons
 123             viewbottombar
 124                 %TWIKIWEB%.WebBottomBar
 125
 126 ## <a name="Logo"></a> Logo
 127
 128 ### <a name="How can I change the web logo?"></a> How can I change the web logo?
 129
 130 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 [[TWikiPreferences]].
 131
 132 Redefine your custom variables in [[Main.TWikiPreferences|Main/TWikiPreferences]] (to keep [[TWikiPreferences]] intact):
 133
 134 > * Set WEBLOGONAME = logo.gif
 135 >        * Set WEBLOGOIMG = %PUBURLPATH%/%BASEWEB%/%WEBPREFSTOPIC%/%WEBLOGONAME%
 136 >        * Set WEBLOGOURL = %SCRIPTURLPATH{"view"}%/%BASEWEB%/%HOMETOPIC%
 137 >        * Set WEBLOGOALT = Home
 138
 139 There are 2 ways to change the logo in a web:
 140
 141 **Using logo.gif:**
 142
 143 > - 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.
 144 > - You can also upload the image with FTP to `/pub/YourWeb/WebPreferences/`.
 145 > - Copy the above instructions ("Redefine your custom variables") and insert your logo name.
 146
 147 **Using a new filename:**
 148
 149 > - Attach whatever image and attach it to the web's [[WebPreferences]] topic. Then add to the [[WebPreferences]] (under _Custom web preferences_):
 150 >
 151 >           * Set WEBLOGONAME = your-logo-name.gif-or-png
 152 >
 153 > - Copy the above instructions ("Redefine your custom variables") and insert your logo name.
 154
 155 ### <a name="How do I set a site-wide logo?"></a> How do I set a site-wide logo?
 156
 157 There is a bunch of site-wide logo variables in [[Main.TWikiPreferences|Main/TWikiPreferences]]: `WIKILOGOIMG`, `WIKILOGOURL` and `WIKILOGOALT`. To change only the web logo image to site-wide, in [[Main.TWikiPreferences|Main/TWikiPreferences]] set:
 158
 159 > * Set WEBLOGOIMG = %WIKILOGOIMG%
 160
 161 ### <a name="My logo does not fit the top bar"></a> My logo does not fit the top bar
 162
 163 See [[I want to change the height of the top bar|Main/WebHome#TopBarChangeHeight]]
 164
 165 ### <a name="I want to change the white space"></a> I want to change the white space above and below the logo
 166
 167 Change the table style in topic [[WebTopBar]]. The default top padding is 11px.
 168
 169 ## <a name="Top bar"></a> Top bar
 170
 171 ### <a name="The search box won&#39;t find topics"></a> The search box won't find topics in other webs
 172
 173 In [[WebTopBar]] you can find the line:
 174
 175     <input type="hidden" name="web" value="%BASEWEB%" />
 176
 177 To search all webs, write:
 178
 179 > <input type="hidden" name="web" value="all" />
 180
 181 To search a couple of webs, for instance the webs Main and TWiki, write:
 182
 183 > <input type="hidden" name="web" value="Main,TWiki" />
 184
 185 See also: [[Search variable|TWiki/VarSEARCH]]
 186
 187 <a name="TopBarChangeHeight"></a>
 188
 189 ### <a name="I want to change the height of t"></a> I want to change the height of the top bar
 190
 191 The top bar is 64 pixels high by default.
 192
 193 **Using templates:** %BR% Using either a template or a topic template, copy this definition in your custom template:
 194
 195 > %TMPL:DEF{"topbardimensions"}%
 196 >     #patternTopBar,
 197 >     #patternClearHeaderCenter,
 198 >     #patternClearHeaderLeft,
 199 >     #patternClearHeaderRight,
 200 >     #patternTopBarContentsOuter {
 201 >        height:64px; /* top bar height; make room for header columns */
 202 >        overflow:hidden;
 203 >     }
 204 >     %TMPL:END%
 205 >
 206 > And change the number from 64px to a different value.
 207
 208 **Using style sheets:**
 209
 210 > Create a new stylesheet with above definition in it, attach it to a topic and point
 211 >
 212 > `USERLAYOUTURL`
 213 >
 214 > to that topic attachment. See
 215 >
 216 > [[PatternSkinCssCookbook]]
 217 >
 218 > about creating custom styles.
 219
 220 ### <a name="I want to set or change the top"></a><a name="I want to set or change the top "></a> I want to set or change the top background image
 221
 222 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 [[TWikiPreferences]].
 223
 224 Redefine your custom variables in [[Main.TWikiPreferences|Main/TWikiPreferences]] (to keep [[TWikiPreferences]] intact):
 225
 226 > * Set WEBHEADERART = %PUBURLPATH%/%TWIKIWEB%/PatternSkin/TWiki_header.gif
 227 >        * Set WEBHEADERBGCOLOR = somehexcolor (no quotes, for example: #ffffff)
 228
 229 You can also set `WEBHEADERART` per web, by defining the variable in the Web's WebPreferences.
 230
 231 ### <a name="I want to have the web color in"></a><a name="I want to have the web color in "></a> I want to have the web color in the top bar
 232
 233 Redefine `WEBHEADERBGCOLOR` in [[Main.TWikiPreferences|Main/TWikiPreferences]] (to keep [[TWikiPreferences]] intact):
 234
 235 > * Set WEBHEADERBGCOLOR = %WEBBGCOLOR%
 236
 237 ### <a name="I want to remove the Jump and Se"></a> I want to remove the Jump and Search boxes from the top bar
 238
 239 If you have localization enabled, you will also see a language dropdown box at the far right.
 240
 241 You can remove these items from [[WebTopBar]].
 242
 243 ### <a name="I want to hide the top bar"></a> I want to hide the top bar
 244
 245 **Using templates:**
 246
 247 The view template is populated with page elements using template inclusions:
 248
 249     %TMPL:INCLUDE{"page"}%
 250     %TMPL:INCLUDE{"viewtopbar"}%
 251     %TMPL:INCLUDE{"viewtoolbar"}%
 252     %TMPL:INCLUDE{"viewleftbar"}%
 253     %TMPL:INCLUDE{"viewrightbar"}%
 254     %TMPL:INCLUDE{"viewtopicactionbuttons"}%
 255     %TMPL:INCLUDE{"viewbottombar"}%
 256
 257 Each included template draws a part of the screen.%BR% Omit `%TMPL:INCLUDE{"viewtopbar"}%` to hide the top bar.
 258
 259 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:
 260
 261 > %TMPL:INCLUDE{"view"}%
 262 >     %TMPL:DEF{"topbar"}%%TMPL:END%
 263 >
 264 > and add:
 265 >
 266 >     %TMPL:DEF{"topbardimensions"}%#patternTopBar,
 267 >     #patternClearHeaderCenter,
 268 >     #patternClearHeaderLeft,
 269 >     #patternClearHeaderRight,
 270 >     #patternTopBarContentsOuter {
 271 >        height:0px;
 272 >     }%TMPL:END%
 273
 274 **Using style sheets:** %BR% See [[PatternSkinCssCookbookNoTopBar]]
 275
 276 ## <a name="Left bar"></a> Left bar
 277
 278 ### <a name="I want to hide the left bar"></a> I want to hide the left bar
 279
 280 **Using templates:** %BR% Omit `%TMPL:INCLUDE{"viewleftbar"}%` to hide the left bar, or in a custom template clear it using
 281
 282 > %TMPL:DEF{"leftbar"}%%TMPL:END%
 283 >     %TMPL:DEF{"leftbardimensions"}%%TMPL:END%
 284
 285 **Using style sheets:** %BR% See [[PatternSkinCssCookbookNoLeftBar]]
 286
 287 ### <a name="I want to make the left bar wide"></a> I want to make the left bar wider
 288
 289 **Using templates:** %BR%
 290
 291 The left bar is 12 em wide by default.
 292
 293 **Using templates:** %BR% Using either a template or a topic template, copy this definition in your custom template:
 294
 295 > %TMPL:DEF{"leftbardimensions"}%#patternOuter {
 296 >        margin-left:12em;
 297 >     }
 298 >     #patternLeftBar {
 299 >        width:12em;
 300 >        margin-left:-12em;
 301 >     }%TMPL:END%
 302 >
 303 > And change the number from 12em to a different value (3 occurrences).
 304
 305 ## <a name="Buttons"></a> Buttons
 306
 307 ### <a name="I want to hide the edit buttons"></a><a name="I want to hide the edit buttons "></a> I want to hide the edit buttons from certain users
 308
 309 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.
 310
 311 Using either a template or a topic template, 'empty' `top:toolbarbuttons` and `topicaction` by writing:
 312
 313 > %TMPL:INCLUDE{"view"}%
 314 >     %TMPL:DEF{"top:toolbarbuttons"}%%TMPL:END%
 315 >     %TMPL:DEF{"topicaction"}%%TMPL:END%
 316
 317 In the user page of [[TWikiGuest]], set the cover to
 318
 319 > * Set COVER = customer
 320
 321 By default this topic is editable only by TWiki admins.
 322
 323 ### <a name="I want to remove the History but"></a> I want to remove the History button from the bottom
 324
 325 All action links and buttons are defined in `viewtopicactionbuttons.tmpl`. The bottom history link is defined in DEF `action_revisions`
 326
 327 > %TMPL:DEF{"topicactionbuttons"}%
 328 >     %TMPL:P{"action_activatable_edit_or_create"}%
 329 >     %TMPL:P{"action_activatable_attach"}%
 330 >     %TMPL:P{"action_printable"}%
 331 >     %TMPL:P{"action_revisions"}%
 332 >     %TMPL:P{"action_backlinks_simple"}%
 333 >     %TMPL:P{"action_raw_or_view"}%
 334 >     %TMPL:P{"action_activatable_raw_edit"}%
 335 >     %TMPL:P{"activatable_more"}%
 336 >     %TMPL:END%
 337
 338 To hide that link, In a custom skin view template `view.myskin.tmpl` empty `action_revisions` by replacing it with an empty string:
 339
 340 > %TMPL:INCLUDE{"view"}%
 341 >     %TMPL:DEF{"action_revisions"}%%TMPL:END%
 342
 343 ### <a name="I want to put the bottom links a"></a> I want to put the bottom links as buttons at the top
 344
 345 The default definition in `view.pattern.tmpl` is:
 346
 347     %TMPL:DEF{"top:toolbarbuttons"}%%TMPL:P{"activatable_edit_or_create"}%%TMPL:P{"activatable_attach"}%%TMPL:END%
 348
 349 Create a new skin by creating a file `view.myskin.tmpl` in the `templates` directory. Write in it:
 350
 351 > %TMPL:INCLUDE{"view"}%
 352 >     %TMPL:DEF{"top:toolbarbuttons"}%%TMPL:P{"history_history_link"}%%TMPL:END%
 353
 354 View any topic with `?skin=myskin,pattern`, or set the `SKIN` variable to `myskin,pattern`.
 355
 356 This will remove the Edit and Attach buttons, and place a History button at the top.
 357
 358 You will probably not just want to have the History button there. Other button include names are:
 359
 360 > create_topic_link
 361 >     raw_edit_link
 362 >     view_topic_link
 363 >     activatable_attach
 364 >     activatable_edit_or_create
 365 >     more_link
 366 >     activatable_printable
 367 >     backlinks_web_link
 368 >     backlinks_all_link
 369 >     backlinks_link
 370 >     history_rdiff_link
 371 >     history_history_link
 372 >     raw_link
 373
 374 ## <a name="Other page parts"></a> Other page parts
 375
 376 ### <a name="I want to insert text outside of"></a> I want to insert text outside of the topic content
 377
 378 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.
 379
 380 Both modules are wrapped in CSS containers:
 381
 382 - `contentheader` - wrapped in `div` of class `twikiContentHeader`
 383 - `contentfooter` - wrapped in `div` of class `twikiContentFooter`
 384
 385 To put contents **before** the main text, use the custom skin approach as described above.%BR% So our custom template contains:
 386
 387 > %TMPL:INCLUDE{"view"}%
 388 >     %TMPL:DEF{"contentheader"}%This is the text before%TMPL:END%
 389
 390 Use the same procedure for contents to be put **after** the topic text:
 391
 392 > %TMPL:INCLUDE{"view"}%
 393 >     %TMPL:DEF{"contentfooter"}%This is the text after%TMPL:END%
 394
 395 ### <a name="I want to place the form at the"></a><a name="I want to place the form at the "></a> I want to place the form at the top
 396
 397 Pattern skin has 2 buckets for the form: `formtop` (form at the top) and `formbottom` (form at the bottom). The default definition is:
 398
 399 > %TMPL:DEF{"formtop"}%%TMPL:END%
 400 >     %TMPL:DEF{"formbottom"}%%TMPL:P{"form"}%%TMPL:END%
 401
 402 You simply swap the bucket contents. Using either a template or a topic template, write in your custom template:
 403
 404 > %TMPL:INCLUDE{"view"}%
 405 >     %TMPL:DEF{"formtop"}%%TMPL:P{"form"}%%TMPL:END%
 406 >     %TMPL:DEF{"formbottom"}%%TMPL:END%
 407
 408 ### <a name="I want to put the topic form in"></a><a name="I want to put the topic form in "></a> I want to put the topic form in a twisty
 409
 410 The attachment tables are placed in a open/close twisty. You can do the same for the topic form.
 411
 412 Edit `templates/formtables.pattern.tmpl` to have this code:
 413
 414     %{ These templates define the form attached at the bottom of viewed page. }%
 415
 416     %TMPL:DEF{"starttopicformwisty"}%%TWISTY{id="topicformlist" mode="div" remember="on" link="%MAKETEXT{"Form"}%" showimgleft="%ICONURLPATH{toggleopen}%" hideimgleft="%ICONURLPATH{toggleclose}%"}%%TMPL:END%
 417
 418     %TMPL:DEF{"endtopicformwisty"}%%ENDTWISTY%%TMPL:END%
 419
 420     %{ Start of form table }%
 421     %TMPL:DEF{FORM:display:header}%<div class="twikiForm">%TMPL:P{"starttopicformwisty"}%
 422     <table class='twikiFormTable' border='1'>%TMPL:P{FORM:display:header:headerrow}%%TMPL:END%
 423
 424     %{ Header }%
 425     %TMPL:DEF{FORM:display:header:headerrow}%<tr><th class='twikiFormTableHRow twikiFirstCol' colspan='2'>
 426     [[%A_TITLE%]]
 427     </th></tr>%TMPL:END%
 428
 429     %{ Each row }%
 430     %TMPL:DEF{FORM:display:row}%<tr valign='top'><td class='twikiFormTableRow twikiFirstCol' align='right'> %A_TITLE% </td><td>
 431     %A_VALUE%
 432     </td></tr>%TMPL:END%
 433
 434     %{ Footer }%
 435     %TMPL:DEF{FORM:display:footer}%</table>%TMPL:P{FORM:display:footer:editlink}%
 436     %TMPL:P{"endtopicformwisty"}%</div><!-- /twikiForm -->%TMPL:END%
 437
 438 To give the twisty toggle link the same style as the attachment twisty link, add this to pattern skin's `style.css`:
 439
 440     .twikiForm .twistyTrigger .twikiLinkLabel {
 441        font-size:122%; /* h4 size */
 442        font-weight:bold;
 443     }