TWiki/PatternSkinCustomization.mdwn

   1 # <a name="TWiki._PatternSkin Customization"></a><a name=" TWiki._PatternSkin Customizatio"></a> [[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></li>
   8     <li><a href="#Logo"> Logo</a><ul>
   9         <li><a href="#How can I change the web logo?"> How can I change the web logo?</a></li>
  10         <li><a href="#How do I set a site-wide logo?"> How do I set a site-wide logo?</a></li>
  11         <li><a href="#My logo does not fit the top bar"> My logo does not fit the top bar</a></li>
  12         <li><a href="#I want to change the white space"> I want to change the white space above and below the logo</a></li>
  13       </ul>
  14     </li>
  15     <li><a href="#Top bar"> Top bar</a><ul>
  16         <li><a href="#I want to set or change the top"> I want to set or change the top background image</a></li>
  17         <li><a href="#I want to have the web color in"> I want to have the web color in the top bar</a></li>
  18         <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>
  19         <li><a href="#I want to hide the top bar"> I want to hide the top bar</a></li>
  20       </ul>
  21     </li>
  22     <li><a href="#Left bar"> Left bar</a><ul>
  23         <li><a href="#I want to hide the left bar"> I want to hide the left bar</a></li>
  24       </ul>
  25     </li>
  26     <li><a href="#Other page parts"> Other page parts</a><ul>
  27         <li><a href="#I want to hide the edit buttons"> I want to hide the edit buttons from certain users</a></li>
  28         <li><a href="#I want to remove the History but"> I want to remove the History button from the bottom</a></li>
  29         <li><a href="#I want to insert text outside of"> I want to insert text outside of the topic content</a></li>
  30       </ul>
  31     </li>
  32   </ul>
  33 </div>
  34
  35 ## <a name="First Read: How to modify _Patte"></a> First Read: How to modify PatternSkin templates
  36
  37 If you need to change any of the elements that are visible on the common 'view' pages, you need to change the 'view' _template_: `/templates/view.pattern.tmpl`. The quickest way 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.
  38
  39 **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`.
  40
  41 **The steps you would need:**
  42
  43 1. Think up a name for your skin. Let us use `myskin` for now.
  44 2. Create a new (empty) view template file in `/templates` called `view.myskin.tmpl`.
  45 3. In `view.myskin.tmpl` you write: %BR% `%TMPL:INCLUDE{"view"}%` %BR% `%TMPL:DEF{"topicactionbuttons"}%%TMPL:P{"activatable_more"}%%TMPL:END%`
  46 4. Now the skin is set. For testing, view any topic and append to the topic name: `?cover=myskin`. You should see an effect now.
  47 5. To make the changes visible on all pages, go to [[Main.TWikiPreferences|Main/TWikiPreferences]] (to keep [[TWikiPreferences]] intact) and write:
  48
  49 > * Set COVER = myskin
  50 >
  51 > or write
  52 >
  53 >        * Set SKIN = myskin,pattern
  54
  55 ## <a name="Logo"></a> Logo
  56
  57 ### <a name="How can I change the web logo?"></a> How can I change the web logo?
  58
  59 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]].
  60
  61 Redefine your custom variables in [[Main.TWikiPreferences|Main/TWikiPreferences]] (to keep [[TWikiPreferences]] intact):
  62
  63 > * Set WEBLOGONAME = logo.gif
  64 >        * Set WEBLOGOIMG = %PUBURLPATH%/%BASEWEB%/%WEBPREFSTOPIC%/%WEBLOGONAME%
  65 >        * Set WEBLOGOURL = %SCRIPTURLPATH{"view"}%/%BASEWEB%/%HOMETOPIC%
  66 >        * Set WEBLOGOALT = Home
  67
  68 There are 2 ways to change the logo in a web:
  69
  70 **Using logo.gif:**
  71
  72 > - 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.
  73 > - You can also upload the image with FTP to `/pub/YourWeb/WebPreferences/`.
  74 > - Copy the above instructions ("Redefine your custom variables") and insert your logo name.
  75
  76 **Using a new filename:**
  77
  78 > - Attach whatever image and attach it to the web's [[WebPreferences]] topic. Then add to the [[WebPreferences]] (under _Custom web preferences_):
  79 >
  80 >           * Set WEBLOGONAME = your-logo-name.gif-or-png
  81 >
  82 > - Copy the above instructions ("Redefine your custom variables") and insert your logo name.
  83
  84 ### <a name="How do I set a site-wide logo?"></a> How do I set a site-wide logo?
  85
  86 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:
  87
  88 > * Set WEBLOGOIMG = %WIKILOGOIMG%
  89
  90 ### <a name="My logo does not fit the top bar"></a> My logo does not fit the top bar
  91
  92 The top bar is 64 pixels high by default.
  93
  94 **Using templates:**
  95
  96 > Change the height of the top bar in
  97 >
  98 > `templates/viewtopbar.pattern.tmpl`
  99 >
 100 > :
 101 >
 102 >     %TMPL:DEF{"topbardimensions"}%
 103 >     #patternTopBar,
 104 >     #patternClearHeaderCenter,
 105 >     #patternClearHeaderLeft,
 106 >     #patternClearHeaderRight,
 107 >     #patternTopBarContentsOuter {
 108 >       height:64px; /* top bar height; make room for header columns */
 109 >       overflow:hidden;
 110 >     }
 111 >     %TMPL:END%
 112 >
 113 > Only change the number from 64px to another value.
 114
 115 **Using style sheets:**
 116
 117 > Create a new stylesheet with above definition in it, attach it to a topic and point
 118 >
 119 > `USERLAYOUTURL`
 120 >
 121 > to that topic attachment. See
 122 >
 123 > [[PatternSkinCssCookbook]]
 124 >
 125 > about creating custom styles.
 126
 127 ### <a name="I want to change the white space"></a> I want to change the white space above and below the logo
 128
 129 Change the table style in topic [[WebTopBar]]. The default top padding is 11px.
 130
 131 ## <a name="Top bar"></a> Top bar
 132
 133 ### <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
 134
 135 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]].
 136
 137 Redefine your custom variables in [[Main.TWikiPreferences|Main/TWikiPreferences]] (to keep [[TWikiPreferences]] intact):
 138
 139 > * Set WEBHEADERART = %PUBURLPATH%/%TWIKIWEB%/PatternSkin/TWiki_header.gif
 140 >        * Set WEBHEADERBGCOLOR = somehexcolor (no quotes, for example: #ffffff)
 141
 142 You can also set `WEBHEADERART` per web, by defining the variable in the Web's WebPreferences.
 143
 144 ### <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
 145
 146 Redefine `WEBHEADERBGCOLOR` in [[Main.TWikiPreferences|Main/TWikiPreferences]] (to keep [[TWikiPreferences]] intact):
 147
 148 > * Set WEBHEADERBGCOLOR = %WEBBGCOLOR%
 149
 150 ### <a name="I want to remove the Jump and Se"></a> I want to remove the Jump and Search boxes from the top bar
 151
 152 If you have localization enabled, you will also see a language dropdown box at the far right.
 153
 154 You can remove these items from [[WebTopBar]].
 155
 156 ### <a name="I want to hide the top bar"></a> I want to hide the top bar
 157
 158 **Using templates:**
 159
 160 The view template is populated with page elements using template inclusions:
 161
 162     %TMPL:INCLUDE{"page"}%
 163     %TMPL:INCLUDE{"viewtopbar"}%
 164     %TMPL:INCLUDE{"viewtoolbar"}%
 165     %TMPL:INCLUDE{"viewleftbar"}%
 166     %TMPL:INCLUDE{"viewrightbar"}%
 167     %TMPL:INCLUDE{"viewtopicactionbuttons"}%
 168     %TMPL:INCLUDE{"viewbottombar"}%
 169
 170 Each included template draws a part of the screen.%BR% Omit `%TMPL:INCLUDE{"viewtopbar"}%` to hide the top bar.
 171
 172 Another approach is to clear the contents of module `topbar`; for example in `view.myskin.tmpl`:
 173
 174 > %TMPL:INCLUDE{"view"}%
 175 >
 176 >     %TMPL:INCLUDE{"topbar"}%%TMPL:END%
 177 >
 178 > and add:
 179 >
 180 >     %TMPL:DEF{"topbardimensions"}%#patternTopBar,
 181 >     #patternClearHeaderCenter,
 182 >     #patternClearHeaderLeft,
 183 >     #patternClearHeaderRight,
 184 >     #patternTopBarContentsOuter {
 185 >       height:0px;
 186 >     }%TMPL:END%
 187
 188 **Using style sheets:**
 189
 190 > See
 191 >
 192 > [[PatternSkinCssCookbookNoTopBar]]
 193 >
 194 > .
 195
 196 ## <a name="Left bar"></a> Left bar
 197
 198 ### <a name="I want to hide the left bar"></a> I want to hide the left bar
 199
 200 **Using templates:**
 201
 202 > Omit
 203 >
 204 > `%TMPL:INCLUDE{"viewleftbar"}%`
 205 >
 206 > to hide the left bar, or in a view template clear it using
 207 >
 208 > `%TMPL:DEF{"viewleftbar"}%%TMPL:END%`
 209
 210 **Using style sheets:**
 211
 212 > See
 213 >
 214 > [[PatternSkinCssCookbookNoLeftBar]]
 215 >
 216 > .
 217
 218 ## <a name="Other page parts"></a> Other page parts
 219
 220 ### <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
 221
 222 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 customers.
 223
 224 Create in the template directory the file `view.customer.tmpl`. 'Empty' `topicaction` and `toolbar` by writing in the template:
 225
 226 > %TMPL:INCLUDE{"view"}%
 227 >     %TMPL:DEF{"topicaction"}%%TMPL:END%
 228 >     %TMPL:DEF{"toolbar"}%%TMPL:END%
 229
 230 In [[TWikiGuest]], set the cover to
 231
 232 > * Set COVER = customer
 233
 234 By default this topic is editable only by TWikiAdminGroup members.
 235
 236 ### <a name="I want to remove the History but"></a> I want to remove the History button from the bottom
 237
 238 All action buttons are defined in `viewtopicactionbuttons.pattern.tmpl`. Remove module `revisions` from `%TMPL:DEF{"topicactionbuttons"}%`. %BR%
 239
 240 > <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"\}% <span><font><s>%TMPL:P\{"revisions"\}%%TMPL:P\{"sep"\}%</s></font></span> %TMPL:P\{"activatable\_more"\}%%TMPL:END% </code>
 241
 242 In your `view.myskin.tmpl` file (see above) you write:
 243
 244 > %TMPL:INCLUDE{"view"}%
 245 >
 246 >     %TMPL:DEF{"topicactionbuttons"}% |
 247 >     %TMPL:P{context="WysiwygPluginEnabled" then="activatable_edit_wysiwyg"}%
 248 >     %TMPL:P{"activatable_attach"}% |
 249 >     %TMPL:P{"printable"}% |
 250 >     %TMPL:P{"raw"}% |
 251 >     %TMPL:P{"backlinks"}% |
 252 >     %TMPL:P{"activatable_more"}%%TMPL:END%
 253 >
 254 > Remove all newlines if you copy-paste above text.
 255
 256 Test by appending `?cover=myskin` to any topic.
 257
 258 ### <a name="I want to insert text outside of"></a> I want to insert text outside of the topic content
 259
 260 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.
 261
 262 Both modules are wrapped in CSS containers:
 263
 264 - `beforetextcontents` - wrapped in `div` of class `twikiBeforeText`
 265 - `aftertextcontents` - wrapped in `div` of class `twikiAfterText`
 266
 267 To put contents before the main text, use the custom skin approach as described above.%BR% So our `view.myskin.tmpl` file contains:
 268
 269 > %TMPL:INCLUDE{"view"}%
 270 >
 271 >     %TMPL:DEF{"beforetextcontents"}%This is the text before%TMPL:END%
 272
 273 Test by appending `?cover=myskin` to any topic.
 274
 275 Use the same procedure for contents to be put after the topic text:
 276
 277 > %TMPL:INCLUDE{"view"}%
 278 >
 279 >     %TMPL:DEF{"aftertextcontents"}%This is the text after%TMPL:END%