TWiki/PatternSkinCustomization.mdwn

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