TWiki/InstantEnhancements.mdwn

   1 # <a name="Instant TWiki Site Enhancements"></a><a name=" Instant TWiki Site Enhancements"></a> Instant TWiki Site Enhancements
   2
   3 These quick enhancements are aimed at improving TWiki's ease-of-use. New TWiki site administrators are especially encouraged to review this document for ideas before deploying a new [[TWikiSite]]. The metaphor of building a house is useful. The listed enhancements are some of the details possible when moving into a new office or home. These small changes can make a **big** differences for user satisfaction at your site. All modifications can be done through your Web browser, and they don't take more then in a couple of minutes. No system administration expertise is required. Some of these enhancements are also mentioned in the reference manual and other topics.
   4
   5 Many of these tips are based on setting some special [[TWikiVariables]].
   6
   7 %S% We recommend implementing at least **_some_** of these enhancements **_right after installation_**, to get a taste for what is possible. Some of these tips and enhancements _should_ be implemented before or during initial roll-out.
   8
   9 This may spark your imagination to **really** customize your site so that it's optimal for **your** users. Slightly more advanced customization tips are listed in [[TWikiAdminCookBook]].
  10
  11 <div>
  12   <ul>
  13     <li><a href="#Tips using _TWikiVariables"> Tips using TWikiVariables</a><ul>
  14         <li><a href="#Change Colors of Page Header/Foo"> Change Colors of Page Header/Footer</a></li>
  15         <li><a href="#Set Page Background Color"> Set Page Background Color </a></li>
  16         <li><a href="#Titles-Only Topic List - _WebTop"> Titles-Only Topic List - WebTopicList</a></li>
  17         <li><a href="#Simple way to create %RED% color"> Simple way to create %RED% colored text %ENDCOLOR% and graphics</a></li>
  18         <li><a href="#EZ Graphic Icons to Highlight Te"> EZ Graphic Icons to Highlight Text</a></li>
  19         <li><a href="#Use TOC variable to create table"> Use TOC variable to create table of content</a></li>
  20       </ul>
  21     </li>
  22     <li><a href="#Personal Productivity - Tools an"> Personal Productivity - Tools and Tips for Working Faster</a><ul>
  23         <li><a href="#Use your favorite text editor fo"> Use your favorite text editor for major edits</a></li>
  24       </ul>
  25     </li>
  26     <li><a href="#Ready to use SEARCH"> Ready to use SEARCH </a><ul>
  27         <li><a href="#Personal directory of topics you"> Personal directory of topics you're involved in</a></li>
  28         <li><a href="#Recently changed pages"> Recently changed pages </a></li>
  29       </ul>
  30     </li>
  31     <li><a href="#Hidden Edit Lock for Individual"> Hidden Edit Lock for Individual Topics</a></li>
  32     <li><a href="#Change the Default Site Logo"> Change the Default Site Logo</a></li>
  33     <li><a href="#Customize Topic Classification F"> Customize Topic Classification Forms</a></li>
  34     <li><a href="#Add Your Favorite _JavaScript Fe"> Add Your Favorite JavaScript Features</a></li>
  35   </ul>
  36 </div>
  37
  38 ----
  39
  40 ## <a name="Tips using _TWikiVariables"></a> Tips using [[TWikiVariables]]
  41
  42 You need to know what is the variable name, and in what page is/should be defined.
  43
  44 ### <a name="Change Colors of Page Header/Foo"></a> Change Colors of Page Header/Footer
  45
  46 Incredibly obvious, maybe, but some TWiki site admins don't get around to changing the default web colors right off, whether they like them or not. Simply changing the defaults will make a huge difference in the overall look.
  47
  48 **What we are doing**
  49
  50 We want to set variable WEBBGCOLOR in topic [[WebPreferences]] to one of the [[StandardColors]]. WebPreferences is, as you can guess, a topic which holds all kind of preference setting for each TWiki Web[[{*}|Main/ManagingWebs]]. Each web has its own WebPreferences, and you can set them differently for each web.
  51
  52 **How to do it**
  53
  54 1. Pick color code from company or product references, the [[StandardColors]] table (recommended for 8-bit client compatibility), or some other color reference.
  55 2. Go to [[WebPreferences]] in each web, and edit the topic.
  56 3. Set your preferred WEBBGCOLOR preferences variable, and save the topic.
  57 4. %X% Add a new line immediately after the color code. If there is (invisible) space after the color code, the page header might get strange colors (e.g. black).
  58
  59 It's just as easy to refine later on, so you're not locked in, just looking better.
  60
  61 ### <a name="Set Page Background Color"></a> Set Page Background Color
  62
  63 Without getting into the [[TWikiTemplates]] system yet, you can easily edit the <code>**view.tmpl**</code> (in the `templates` directory). In the HTML at the top, the body tag has the page background hardcoded to white <code>**bgcolor="#ffffff"**</code>. You can change that color value to new variable. First, define a new preferences variable in the site-level [[TWikiPreferences]], e.g. `* Set =PAGEBGCOLOR = #d0d0d0`, then edit the <code>**view.tmpl**</code> template file and change <code>**bgcolor="#ffffff"**</code> to <code>**bgcolor="%PAGEBGCOLOR%"**</code>. If you want you can set the page background color individualy per web, simple add a `* Set =PAGEBGCOLOR = #d0d0d0` bullet to the [[WebPreferences]] to overload the site-level preferences. (Without font color control, you'll have to stick to light colors.
  64
  65 ### <a name="Titles-Only Topic List - _WebTop"></a> Titles-Only Topic List - [[WebTopicList]]
  66
  67 **_A good first navigation tool for new users,_** a fast-loading linked list (page titles only) of a web's topics is a quick and easy way see what's available. By default, slower, but more powerfull [[WebIndex]] is used.
  68
  69 Without explaining what WEBTOPICLIST is, just try it:
  70
  71 1. Go to [[WebPreferences]] in each web, and edit the topic.
  72 2. In WEBTOPICLIST variable, replace `WebIndex` with `WebTopicList`, and save.
  73
  74 ### <a name="Simple way to create %RED% color"></a> Simple way to create %RED% colored text %ENDCOLOR% and graphics
  75
  76 This should be enabled, see the "Miscellaneous Settings" in the [[TWikiPreferences]], . If not, look at TWiki:TWiki/TWikiPreferences. Look for variables RED, BLUE etc (which define HTML tag FONT). To copy/paste the variables defining the colors you need to see the source text, but `Edit` is disabled. Instead, go to `More` and view the topic in <code>**raw**</code> format.
  77
  78 ### <a name="EZ Graphic Icons to Highlight Te"></a> EZ Graphic Icons to Highlight Text
  79
  80 Graphics in text (like this: %X%) is done also by defining special variables. See [[TWiki.TWikiPreferences|TWiki/TWikiPreferences]]. Some may prefer longer names, like `HELP`, `WARN` etc. You can also add your own images, e.g. a `NEW`, or a `ASK` to ask question.
  81
  82 %T% Using graphic icons to highlight important text right from the start can seriously improve how well new users take to a TWiki site. A minimum set of two or three icons can make content much easier to follow, eye-catching, EXCITING. Research says, people tend not to read pages through, but scan them first - and graphics (used sparringly ;-) of course) can help them. On **HELP** pages, most people tend to jump around looking for answers rather than reading through - icons help point out the most important bits.
  83
  84 **How to create your own set of icons:**
  85
  86 1. Go to the <code>**Preferences**</code> topic: [[TWikiPreferences]] for site-wide use, or [[WebPreferences]] for use in one web only.
  87 2. <code>**Attach**</code> a graphic (the ones on this page are 16x16 pixels), then define a Preference Variable with a short but recognizable name.
  88
  89 - **_Example:_** Enter `%TEST%` to get %TEST% - see how it's [[done|Main/WebPreferences#DefineIcon]].
  90 - %T% Ideas for quick icons: NEW; UPDATE; a STAR or other bullet; key symbols relating to your site content.
  91 - For documentation and help, this [[TWiki|TWiki/WebHome]] web uses three main icons: %H% for **HELP**, %T% for **TIP**, %X% for **IMPORTANT**.
  92 - **_Related:_** There are other approaches for creating more extensive TWiki icon libraries. This is a simply and quick way to get started. See [[TWikiDocGraphics]] for more info.
  93
  94 ### <a name="Use TOC variable to create table"></a> Use TOC variable to create table of content
  95
  96 TOC is Table-Of-Content, generated automagically from headers (defined like that: <code>**---++**</code> , see [[TWikiShorthand]]).
  97
  98 For example, you may want to put all your custom variables in [[TWikiPreferences]] right on top of the page, and generate table of contens, like:
  99
 100 - Preferences for easy creating nice pages
 101   - Graphics icons in text
 102   - Colored text
 103 - System Preferences
 104   - Contents of page header and footer
 105   - User interface defaults
 106   - Email
 107   - Plugins
 108   - Notes
 109
 110 Non-admin users wil be interested only in first part, non-system preferences.
 111
 112 ----
 113
 114 ## <a name="Personal Productivity - Tools an"></a> Personal Productivity - Tools and Tips for Working Faster
 115
 116 Although this area applies to all TWiki set-ups, the initial focus is on TWiki site managers working on a Linux/Apache TWiki site, from a Windows local PC. The assumption being: if you're working with Linux as your desktop, you're probably a programmer or system admin and have these basics handled!
 117
 118 ### <a name="Use your favorite text editor fo"></a> Use your favorite text editor for major edits
 119
 120 When you have a fair bit of TWiki formatting work - for example, compiling new info pages from various cut'n'paste sources, editing multiple TWiki topics or contributed material - it's often easier to use a real **[[TextEditor]]** instead of the browser's text edit box. There are several methods for doing this. For Windows, there are several well-recommended text editors.
 121
 122 **_Windows Example:_** [TextPad](http://textpad.com) is a low-cost, top flight Windows program, with an extended trial period. You can download from a well-stocked library of user-contributed macros, dictionaries, and syntax and clip files. You can also easily create a TWiki clip collection that allows you to format text with TWiki code: select a text string and click for bold, italic, links, bullet lists - just like a regular HTML editor - and also insert blocks of TWiki code, use simple or regex search and replace, more.
 123
 124 **_Copy &amp; Paste:_** Using the web window this can work very well. System differences may present difficulties with this method but it is simple and reliable in most cases.
 125
 126 **_Browser Integration:_** Some web browsers can be configured to automatically use an external editor. See your browser documentation for details. Such a configuration and a small tool for Linux is described in an example on TWiki.org. TWiki:Codev/EditDaemonWithGVimIntegration
 127
 128 **_Alternate Browser:_** While your main browser might not have the features for TWikic topic editing, another one might.
 129
 130 - An example on the Linux platform is the `w3m` pager/browser for Linux. This is a text based version similar to `lynx` but it includes text editor features and a configurable command set to act like `lynx` if you are more accustomed to it.
 131
 132 ## <a name="Ready to use SEARCH"></a> Ready to use SEARCH
 133
 134 ### <a name="Personal directory of topics you"></a> Personal directory of topics you're involved in
 135
 136 Here's how you can create your own personal directory of topics you've contributed to recently. Copy the text below (between **Start Copy** and **End Copy**) and paste it into your personal page (Main.admin). You can add other webs to search by duplicating one of the web subsections and editing the string \{web ="webname"\} in the search parameters to refer to the specific web you want to search. This script would also work for a group.
 137
 138 **Start Copy**
 139
 140     __Here's a list of topics I've been involved in recently:__
 141
 142     ---++++ Codev
 143
 144     %SEARCH{ "%TOPIC%" web="Codev" scope="text" nosearch="on" nosummary="on" noheader="on" nototal="on" order="modified" reverse="on" limit="20"}%
 145     ---++++ Support
 146
 147     %SEARCH{ "%TOPIC%" web="Support" scope="text" nosearch="on" nosummary="on" noheader="on" nototal="on" order="modified" reverse="on" limit="20"}%
 148
 149     ---++++ TWiki
 150
 151     %SEARCH{ "%TOPIC%" web="TWiki" scope="text" nosearch="on" nosummary="on" noheader="on" nototal="on" order="modified" reverse="on" limit="10"}%
 152
 153 **End Copy**
 154
 155 The SEARCH variable has many more formatting options, see [[TWikiVariables]].
 156
 157 ### <a name="Recently changed pages"></a> Recently changed pages
 158
 159 Here, last 15 is formatted into neat table.
 160
 161     <table>
 162     %SEARCH{ "\.*" scope="topic" regex="on" nosearch="on" nototal="on" order="modified" reverse="on"  format="<tr><td>  [[$topic][$topic]] </td><td>  $wikiusername  </td><td> $date  </td></tr>" limit="15" }%
 163     </table>
 164
 165 ----
 166
 167 ## <a name="Hidden Edit Lock for Individual"></a><a name="Hidden Edit Lock for Individual "></a> Hidden Edit Lock for Individual Topics
 168
 169 When you're creating main gateway pages, you may want to temporarily (or permanently) restrict editing to yourself or a limited group of people. You can do this with a Preference setting that includes one or more users and groups. Only auhorized users will be able to use <code>**Edit**</code>.
 170
 171 - **_Example:_** <code>**Set ALLOWTOPICCHANGE = Main.UserName, Main.GroupName**</code>
 172 - %T% **To hide the setting:** Use HTML comment tags - put <code>**&lt;!--**</code> on the line \_above the setting, and <code>**--&gt;**</code> on the line below.
 173 - _This is in the regular help files but worth highlighting._
 174
 175 ----
 176
 177 ## <a name="Change the Default Site Logo"></a> Change the Default Site Logo
 178
 179 If you want to change the default TWiki logo, attach a new graphic to a topic of choice and change the WIKILOGOIMG variable in the [[TWikiPreferences]], e.g.
 180
 181 - `Set WIKILOGOIMG = %PUBURL%/TWiki/MyLogo/mylogo.gif`
 182
 183 ----
 184
 185 ## <a name="Customize Topic Classification F"></a> Customize Topic Classification Forms
 186
 187 With a simple one or two-line default topic form available for every topic - in **Edit** mode, click the <code>**[Add]**</code> button, and select the form if it isn't alredy enabled. Then, click the title to get to the actual form, <code>**[Edit]**</code>, and carefully change values, probably basic page classifications. You'll get some increased value, and hands-on experience with [[TWikiForms]], without having to read up about them first. %X% **_(add the corresponding search per category - copy a default and change)_**
 188
 189 ----
 190
 191 ## <a name="Add Your Favorite _JavaScript Fe"></a> Add Your Favorite JavaScript Features
 192
 193 You're no doubt familiar or better with HTML, JS, and "webmastering". Without getting into the [[TWikiTemplates]] system yet, you can easily edit the <code>**view.tmpl**</code> (in the `templates` directory) for some dramatic effects. The top of the template is mostly regular HTML with some variables. Open up some space in the <code>**&lt;head&gt;**</code> area, and you can drop in reliable JavaScripts - a pop-up window script, for example - or tag it as an external script.
 194
 195 - %T% Obviously, you can do the same - place a link to an external stylesheet as well. If you set values for standard HTML tags, you can control a good deal of the type size, style and color with out adding CSS tags. **_example_**
 196
 197 %X% Depending on what you load up, you may change the overall cross-browser compatibility - however be careful that your site does not look beat up in various other browsers. The scripts you choose will determine compatibility.
 198
 199 ----
 200
 201 %T% **_NOTE:_** Feel free to add your own tips to TWiki:%WEB%.%TOPIC% as quick notes at the end of the list, following the existing format!
 202
 203 **Contributors:** TWiki:Main.GrantBow, TWiki:Main.LynnwoodBrown, TWiki:Main.MikeMannix, TWiki:Main.PeterMasiar, TWiki:Main.PeterThoeny, TWiki:Main.MattWilkie