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