Documentation of the TWiki Implementation (version 01 Feb 2003)

• (1) Implementation Notes
• (2) Installation Notes
• (3) Upgrading Earlier Versions of TWiki
• (4) TWiki Authentication
• (5) Wiki Username vs. Login Username
• (6) TWiki Access Control
• (7) Wiki Templates
• (8) Wiki Variables
• (9) Notification of Changes by Email
• (10) TWiki Category Table
• (11) TWiki Administration

Note: Read the most up to date version of this document at http://TWiki.org/cgi-bin/view/TWiki/TWikiDocumentation

Related Topics: TWikiWeb, TWikiHistory, TWikiPlannedFeatures, TWikiEnhancementRequests.

-- PeterThoeny? - 02 Nov 2000

These installation steps use the Apache web server on Linux as an example. TWiki should run on other web servers and Unix systems as well. (TWiki on Windows is possible, but has not been documented well. More on that at http://TWiki.org/cgi-bin/view/Codev/TWikiOnWindows )

Note: Below installation steps assume user nobody for all files manupulated by the cgi scripts (executed by the web server), and user twiki for all other files. You need to replace user nobody with an other user in case the web server executes the script with a different user ( default for Debian is www-data ). Also, you can substitute user twiki with your own user name.

Note: Below installation steps assume that you have control over the web server configuraton files. In case you don't (i.e. if you are installing it on a hosted server) follow the steps but use these directories instead:

Installation steps:

• Request the TWiki distribution (in Unix ZIP format) from http://TWiki.org/download.html .
• Create directory /home/httpd/twiki and unzip the TWiki distribution into this directory.
• The twiki/bin directory of TWiki must be set as a cgi-bin directory. Add /home/httpd/twiki/bin to file /etc/httpd/httpd.conf with only ExecCGI option.
• The twiki/pub directory of TWiki must be set so that it is visible as a URL. Add /home/httpd/twiki to file httpd.conf with normal access options (copy from /home/httpd/html ).
• Now add ScriptAlias for /twiki/bin and Alias for /twiki to file httpd.conf .
  Note: The ScriptAlias must come before the Alias in Apache, otherwise it will fail to correctly set up /twiki/bin/ , due to the fact that it sees that as being just another subdirectory of the /twiki/ alias.
  
• Here are example httpd.conf entries:

 ScriptAlias /twiki/bin/ "/home/httpd/twiki/bin/"
 Alias /twiki/ "/home/httpd/twiki"
 <Directory "/home/httpd/twiki/bin">
    Options +ExecCGI
    SetHandler cgi-script
    Allow from all
 </Directory>
 <Directory "/home/httpd/twiki/pub">
    Options FollowSymLinks +Includes
    AllowOverride None
    Allow from all
 </Directory>

• Restart Apache by /etc/rc.d/rc5.d/S85httpd restart .
• Test if the twiki/bin directory is cgi-enabled:
  • Enter the URL of that directory into your browser ( http://your.domain.com/twiki/bin ). It is not set correctly as cgi-bin in case you get something like "Index of /twiki/bin" . It is OK if you get a message like "Forbidden. You don't have permission to access /twiki/bin/ on this server."
  • Execute the testenv script from your browser ( http://your.domain.com/twiki/bin/testenv ). It shows a table with all CGI environment variables and tests the settings in your twiki/bin/wikicfg.pm configuration file.
• Make sure PERL 5 and the PERL CGI library is installed on your system. Default location of PERL executable is /usr/bin/perl . In case PERL is installed in a different location, the first line of all perl scripts in the twiki/bin directory need to be changed (alternatively you can create a symbolic link from /usr/bin/perl ).
• To be able to edit the perl scripts and .tmpl files it is necessary to chown and chgrp -R twiki so all the files have the owner you want.
• The scripts execute as nobody . Set the file permission of all Perl scripts in the twiki/bin directory as executable to -rwxr-xr-x .
• Set the file permission of all files below twiki/data to 666 ( -rw-rw-rw- ).
• Set the file permission of the twiki/data directory and all its subdirectories to 777 ( drwxrwxrwx ).
• Set the file permission of the twiki/pub directory to 777 ( drwxrwxrwx ).
• Edit the file twiki/bin/wikicfg.pm and set the variables at the beginning of the file to your needs.
• Make sure RCS is installed. Set $rcsDir in twiki/bin/wikicfg.pm to mach the location of your RCS binaries.
• Point your browser at http://your.domain.com/twiki/bin/view and start TWiki-ing away!
• Using your browser, edit the TWikiPreferences topic in the TWiki.TWiki web to set the WIKIWEBMASTER email address, the WEBCOPYRIGHT message and other preferences.
• Note in case the cgi scripts must have a file extension like .pl or .cgi:
  • Add the extension to all the scripts (except for the .pm ones) in twiki/bin
  • Edit wikicfg.pm and set the file extension in the $scriptSuffix variable.
  • If you use .htaccess, edit the file and add the file extension to edit, view, preview, etc.
• Note in case the cgi scripts are not running as user nobody: The *,v RCS repository files delivered with the installation package are locked by user nobody . In case the user is different (e.g. www-data ), it is not possible to check in files, this has the effect that the topic version number does not increase when saving a topic. In this case you need to unlock all repository files and lock them as user www-data (check the rcs man pages), or simply delete all the repository files. A simple way to switch the locker of the RCS files is to use sed:
  for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done
• Security issue: Directories twiki/data , twiki/templates and all its subdirectories should be set so that they are not visible as a URL. (Alternatively, move the directries to a place where they are not visible, and change the variables in twiki/bin/wikicfg.pm accordingly)
• Enable email notification of topic changes, Notification of Changes has more. Using your browser, edit also the WebNotify topic in all webs and set the users you want to notify.
• Add the TWiki:Main.PoweredByTWikiLogo to your WebHome topic.

• Optional: You can add new rendering rules or new %VARIABLES%. To insure an easy upgrade of TWiki it is recommended to do this customization in twiki/bin/wikicfg.pm , not twiki/bin/wiki.pm .

• Optional: If you are on a non authenticated server (i.e. not using SSL) and you would like to authenticate users:
  • Rename file .htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. For details consult the HTTP server documentation (for Apache server: [1], [2]). Note: In case .htaccess does not have any effect you need to enable it: Add "AllowOverride All" to the Directory section of access.conf for your twiki/bin directory.
  • Copy the TWikiRegistrationPub topic to TWikiRegistration. You can customize the topic if needed. Note: You can delete or add new input tags to the registration form. The name="" parameter of the input tags must start with: "Twk0..." (if this is an optional entry), or "Twk1..." (if this is a required entry). This will ensure that the fields are processed correctly.

• Optional: You can automatically generate usage statistics for all webs. To enable this:
  • Make sure variable $doLogTopicView, $doLogTopicSave and $doLogTopicUpload in wikicfg.pm are set. This will generate log entries in file twiki/data/log<date>.txt .
  • Topic WebStatistics must be present in all webs where you want to have statistics. You can use the topic in the Main web as a template.
  • Call the twiki/bin/statistics script from a cron job, once a day is recommended. This will update the WebStatistics topics in all webs.
  • Attention: The script must run as the same user as the CGI scripts are running, which is user nobody on most systems. Example crontab entry:
    0 0 * * * (cd /path/to/TWiki/bin; ./statistics >/dev/null 2>&1)
  • There is a workaround in case you can't run the script as user nobody : Run the utility twiki/bin/geturl in your cron job and specify the URL of the twiki/bin/statistics script as a parameter. Example:
    0 0 * * * (cd /path/to/TWiki/bin; ./geturl mydomain.com /urlpath/to/TWiki/bin/statistics >/dev/null 2>&1)
  • The twiki/bin/statistics script can also be executed as a CGI script, just enter the URL in your browser. Examples:
    • Update current month for all webs:
      http://mydomain.com/twiki/bin/statistics
    • Update current month for Main web only:
      http://mydomain.com/twiki/bin/statistics/Main
    • Update January 2000 for Main web:
      http://mydomain.com/twiki/bin/statistics/Main?logdate=200001

• To create a new web:
  • Use a name for the web consisting of characters A..Z , a..z but not in WikiNotation.
  • Create a new template directory under twiki/templates .
  • Create a new data directory under twiki/data and check the file permission of the directory.
  • Copy the Web*.txt files from the twiki/data/Main directory to the new data directory, preserving the original files' owner, group and permissions ( on Unix use cp -p ). The data files must be writable by the owner the CGI scripts are running on ( usually nobody ). Hint: You can set permissions of .txt and .txt,v files to -rw-rw-rw- and then edit the topic using your browser, RCS will restore the file permission correctly when saving the topic.
  • Add the new web to the web list (visible in the upper right corner of each topic) by editing the site-level preferences TWikiPreferences:
    • Add the new web to the WIKIWEBLIST variable.
  • Add the new web to the web table (at the bottom of each WebHome topic) by editing the TWikiWebsTable topic.
  • Change the web preferences by editing the WebPreferences topic of the new web:
    • Set the WEBBGCOLOR variable to a color of your taste. The number represents the unique color for the web (consult an HTML book for colors.)
    • Customize the WEBTOPICLIST variable to contain the web specific links you prefer.
    • Optional: Set the WEBCOPYRIGHT variable to have a web-specific copyright text (at the bottom of each topic).
  • If needed, create customized templates in the new templates directory. (Non existing templates are inherited from twiki/templates )
  • If you want to use a category table, copy the three files twikicatitems.tmpl , twikicatedit.tmpl and twikicatview.tmpl from the twiki/templates/Know directory to the new templates directory, and customize it. More on that in TWiki Category Table.
  • In case you want usage statistics for this web: Copy file WebStatistics.txt from the twiki/data/Main directory to the new data directory. Edit topic WebStatistics in the new web and delete old usage entries.

Here are contents of directories showing file permissions. Please note that this is for debugging reasons only and does not exactly reflect the distribution:

Directory twiki/bin :

drwxrwxr-x   2 twiki twiki   4096 Jun 17 16:34 .
drwxrwxr-x   3 twiki twiki   4096 Jun 17 16:34 ..
-rw-rw-r--   1 twiki twiki    650 Feb 10  2000 .htaccess
-rwxrwxr-x   1 twiki twiki   4322 Mar 12 00:31 attach
-rwxrwxr-x   1 twiki twiki   1426 Jun 20 19:52 delete
-rwxrwxr-x   1 twiki twiki   9001 Jul 28 11:03 edit
-rwxrwxr-x   1 twiki twiki   1811 Mar 11 02:27 geturl
-rwxrwxr-x   1 twiki twiki   5006 Mar 11 02:41 mailnotify
-rwxrwxr-x   1 twiki twiki   1769 Mar 11 03:07 oops
-rwxrwxr-x   1 twiki twiki   6890 Jun 21 19:58 preview
-rwxrwxr-x   1 twiki twiki   7606 Mar 31 18:30 rdiff
-rwxrwxr-x   1 twiki twiki   8349 Jun 21 18:12 register
-rwxrwxr-x   1 twiki twiki   2693 Jul  5 14:32 save
-rwxrwxr-x   1 twiki twiki   3831 Jul 20 12:13 search
-rwxrwxr-x   1 twiki twiki   9835 Jun 20 19:03 statistics
-rwxrwxr-x   1 twiki twiki    509 Feb  7  2000 testenv
-rwxrwxr-x   1 twiki twiki  14543 Jul 20 18:46 upload
-rwxrwxr-x   1 twiki twiki   4755 May 22 18:11 view
-rwxrwxr-x   1 twiki twiki   1689 Jun 20 20:10 viewfile
-rw-rw-r--   1 twiki twiki  34123 Nov  1 15:43 wiki.pm
-rw-rw-r--   1 twiki twiki   7234 Oct 23 00:34 wikiaccess.pm
-rw-rw-r--   1 twiki twiki  11719 Oct 28 21:58 wikicfg.pm
-rw-rw-r--   1 twiki twiki   6441 Nov  1 23:13 wikiprefs.pm
-rw-rw-r--   1 twiki twiki  13160 Oct 27 14:53 wikisearch.pm
-rw-rw-r--   1 twiki twiki  10540 Oct 28 21:43 wikistore.pm

Directory twiki/templates/ :

drwxrwxr-x   4 twiki twiki   4096 Aug  3 01:17 .
drwxrwxr-x   4 twiki twiki   4096 Aug 19 18:38 ..
drwxrwxr-x   2 twiki twiki   4096 Jun 17 16:35 Know
drwxrwxr-x   2 twiki twiki   4096 May  1 01:24 Main
-rw-rw-r--   1 twiki twiki   2688 Aug 15 18:15 attach.tmpl
-rw-rw-r--   1 twiki twiki   1283 Jul 20 15:56 attachtable.tmpl
-rw-rw-r--   1 twiki twiki   1907 Jul 28 16:41 changes.tmpl
-rw-rw-r--   1 twiki twiki   2265 Aug 15 17:57 edit.tmpl
-rw-rw-r--   1 twiki twiki    965 Feb  8  2000 mailnotify.tmpl
-rw-rw-r--   1 twiki twiki     30 Jan 13  1999 notedited.tmpl
-rw-rw-r--   1 twiki twiki    940 Jul 20 15:59 notext.tmpl
-rw-rw-r--   1 twiki twiki    907 Jul 20 16:01 notwiki.tmpl
-rw-rw-r--   1 twiki twiki    341 Mar  8 11:39 noweb.tmpl
-rw-rw-r--   1 twiki twiki   1000 Mar  8 11:40 oops.tmpl
-rw-rw-r--   1 twiki twiki   1043 Oct 23 19:17 oopsaccesschange.tmpl
-rw-rw-r--   1 twiki twiki   1036 Oct 23 19:17 oopsaccessview.tmpl
-rw-rw-r--   1 twiki twiki    914 Mar  8 11:40 oopsdel.tmpl
-rw-rw-r--   1 twiki twiki   1423 May 29 01:23 oopslocked.tmpl
-rw-rw-r--   1 twiki twiki   1067 Mar  8 11:41 oopsregexist.tmpl
-rw-rw-r--   1 twiki twiki    955 Mar  8 11:41 oopsregpasswd.tmpl
-rw-rw-r--   1 twiki twiki    966 Mar  8 11:41 oopsregrequ.tmpl
-rw-rw-r--   1 twiki twiki   1244 Apr 28 17:11 oopsregthanks.tmpl
-rw-rw-r--   1 twiki twiki   1003 Jul 22 12:48 oopsregwiki.tmpl
-rw-rw-r--   1 twiki twiki   1607 Mar  8 11:42 oopsrev.tmpl
-rw-rw-r--   1 twiki twiki    949 Mar  8 11:43 oopsupload.tmpl
-rw-rw-r--   1 twiki twiki   1735 Aug 15 18:14 preview.tmpl
-rw-rw-r--   1 twiki twiki   1682 Aug 15 18:14 rdiff.tmpl
-rw-rw-r--   1 twiki twiki    530 Jul 22 12:10 register.tmpl
-rw-rw-r--   1 twiki twiki    690 Apr 28 16:53 registernotify.tmpl
-rw-rw-r--   1 twiki twiki   1900 Aug 15 18:15 search.tmpl
-rw-rw-r--   1 twiki twiki   1785 Aug 15 18:15 searchbookview.tmpl
-rw-rw-r--   1 twiki twiki   1559 Aug 19 02:53 view.tmpl

Directory twiki/templates/Know (has a TWiki Category Table) :

drwxrwxr-x   2 twiki   twiki   4096 Jun 17 16:35 .
drwxrwxr-x   4 twiki   twiki   4096 Aug  3 01:17 ..
-rw-rw-r--   1 twiki   twiki    446 Jun  7  1999 notedited.tmpl
-rw-rw-r--   1 twiki   twiki    206 Jun  7  1999 twikicatedit.tmpl
-rw-rw-r--   1 twiki   twiki   1068 Aug 18 18:26 twikicatitems.tmpl
-rw-rw-r--   1 twiki   twiki    231 Jun  7  1999 twikicatview.tmpl

Directory twiki/data/ :

drwxrwxrwx   6 nobody  nobody  4096 Aug  3 01:09 .
drwxrwxr-x   4 twiki   twiki   4096 Aug 19 18:38 ..
-rw-rw-r--   1 nobody  nobody    51 Apr 21 16:48 .htpasswd
drwxrwxrwx   2 nobody  nobody  4096 Aug 20 17:18 Know
drwxrwxrwx   2 nobody  nobody  4096 Aug 19 04:15 Main
drwxrwxrwx   2 nobody  nobody  4096 Aug 20 17:56 TWiki
-rw-rw-rw-   1 twiki   twiki      1 Mar 11 04:19 debug.txt
-rw-r--r--   1 nobody  nobody  1516 Aug 20 17:56 log200008.txt

Part of directory twiki/data/Main :

drwxrwxrwx   2 nobody  nobody  4096 Aug 19 04:15 .
drwxrwxrwx   6 nobody  nobody  4096 Aug  3 01:09 ..
-rw-rw-rw-   1 twiki twiki     3716 Aug 19 02:19 .changes
-rw-rw-rw-   1 twiki twiki        9 Aug 19 02:45 .mailnotify
-rw-r--r--   1 nobody  nobody   358 Aug 18 17:22 OfficeLocations.txt
-r--r--r--   1 nobody  nobody   878 Aug 18 17:22 OfficeLocations.txt,v
-rw-r--r--   1 nobody  nobody   680 Aug 18 17:36 TWikiGuest.txt
-r--r--r--   1 nobody  nobody  1989 Aug 18 17:36 TWikiGuest.txt,v
-rw-r--r--   1 nobody  nobody   459 Aug 18 17:19 TWikiUsers.txt
-r--r--r--   1 nobody  nobody  3840 Aug 18 17:19 TWikiUsers.txt,v
-rw-r--r--   1 nobody  nobody    95 Aug 19 03:06 WebChanges.txt
-r--r--r--   1 nobody  nobody   284 Aug 19 03:06 WebChanges.txt,v
-rw-r--r--   1 nobody  nobody  1853 Aug 18 18:08 WebHome.txt
-r--r--r--   1 nobody  nobody  6523 Aug 18 18:08 WebHome.txt,v
-rw-r--r--   1 nobody  nobody    56 Aug 18 17:21 WebIndex.txt
-r--r--r--   1 nobody  nobody   245 Aug 18 17:21 WebIndex.txt,v
-rw-r--r--   1 nobody  nobody   495 Aug 18 17:40 WebNotify.txt
-r--r--r--   1 nobody  nobody  1896 Aug 18 17:40 WebNotify.txt,v
-rw-r--r--   1 nobody  nobody  1904 Aug 19 01:01 WebPreferences.txt
-r--r--r--   1 nobody  nobody  3108 Aug 19 01:01 WebPreferences.txt,v
-rw-r--r--   1 nobody  nobody  5553 Aug 19 02:30 WebSearch.txt
-r--r--r--   1 nobody  nobody  8406 Aug 19 02:30 WebSearch.txt,v
-rw-r--r--   1 nobody  nobody   729 Aug 18 17:41 WebStatistics.txt
-r--r--r--   1 nobody  nobody  1129 Aug 18 17:41 WebStatistics.txt,v

Directory twiki/pub/ :

drwxrwxrwx   6 nobody  nobody  4096 Aug  3 01:21 .
drwxrwxr-x   3 twiki   twiki   4096 Jun 17 16:35 ..
drwxrwxrwx   3 nobody  nobody  4096 Jun 17 16:35 Know
drwxrwxrwx   2 nobody  nobody  4096 Aug  3 01:21 Main
drwxrwxrwx   3 nobody  nobody  4096 Aug  3 01:21 TWiki
-rw-rw-r--   1 twiki   twiki   1078 Jan 14  2000 favicon.ico
drwxrwxr-x   2 twiki   twiki   4096 Jun 17 16:35 icn
-rw-rw-r--   1 twiki   twiki   3016 Oct  5  1999 twikilogo.gif
-rw-rw-r--   1 twiki   twiki   5320 Oct  5  1999 twikilogo1.gif
-rw-rw-r--   1 twiki   twiki   6125 Oct  5  1999 twikilogo2.gif
-rw-rw-r--   1 twiki   twiki   7218 Oct  5  1999 twikilogo3.gif
-rw-rw-r--   1 twiki   twiki   6710 Oct  5  1999 twikilogo4.gif
-rw-rw-r--   1 twiki   twiki   2877 Jun  7  1999 wikiHome.gif

Directory twiki/pub/icn/ :

drwxrwxr-x   2 twiki   twiki   4096 Jun 17 16:35 .
drwxrwxrwx   6 nobody  nobody  4096 Aug  3 01:21 ..
-rw-rw-r--   1 twiki   twiki    801 Mar 26  1999 _filetypes.txt
-rw-rw-r--   1 twiki   twiki    143 Mar  9  1999 bat.gif
-rw-rw-r--   1 twiki   twiki    926 Mar  9  1999 bmp.gif
-rw-rw-r--   1 twiki   twiki    141 Mar 25  1999 c.gif
-rw-rw-r--   1 twiki   twiki    144 Mar  9  1999 dll.gif
-rw-rw-r--   1 twiki   twiki    152 Mar  9  1999 doc.gif
-rw-rw-r--   1 twiki   twiki    130 Mar  9  1999 else.gif
-rw-rw-r--   1 twiki   twiki    876 Mar 26  1999 exe.gif
-rw-rw-r--   1 twiki   twiki    147 Mar  9  1999 fon.gif
-rw-rw-r--   1 twiki   twiki    142 Mar 25  1999 h.gif
-rw-rw-r--   1 twiki   twiki    156 Mar  9  1999 hlp.gif
-rw-rw-r--   1 twiki   twiki    186 Mar  9  1999 html.gif
-rw-rw-r--   1 twiki   twiki    144 Mar 25  1999 java.gif
-rw-rw-r--   1 twiki   twiki    148 Mar  9  1999 mov.gif
-rw-rw-r--   1 twiki   twiki    150 Mar  9  1999 pdf.gif
-rw-rw-r--   1 twiki   twiki    146 Mar 25  1999 pl.gif
-rw-rw-r--   1 twiki   twiki    150 Mar  9  1999 ppt.gif
-rw-rw-r--   1 twiki   twiki    148 Mar 25  1999 ps.gif
-rw-rw-r--   1 twiki   twiki    148 Mar 25  1999 py.gif
-rw-rw-r--   1 twiki   twiki    130 Mar  9  1999 ram.gif
-rw-rw-r--   1 twiki   twiki    154 Mar  9  1999 reg.gif
-rw-rw-r--   1 twiki   twiki    147 Mar 25  1999 sh.gif
-rw-rw-r--   1 twiki   twiki    155 Mar  9  1999 sniff.gif
-rw-rw-r--   1 twiki   twiki    149 Mar  9  1999 ttf.gif
-rw-rw-r--   1 twiki   twiki    134 Mar  9  1999 txt.gif
-rw-rw-r--   1 twiki   twiki    154 Mar  9  1999 wav.gif
-rw-rw-r--   1 twiki   twiki    152 Mar  9  1999 wri.gif
-rw-rw-r--   1 twiki   twiki    152 Mar  9  1999 xls.gif
-rw-rw-r--   1 twiki   twiki    144 Mar  9  1999 zip.gif

-- PeterThoeny? - 24 Nov 2000

If you are coming from a version earlier than the 01 May 2000 production release, please see TWikiUpgradeTo01May2000 first.

The 01 Dec 2000 release has these changes that affect the upgrade of the 01 May 2000 version:

• Improved search, i.e. search multiple webs.
• The changes script has been retired (related to new search).
• Reorganization of topics: The TWiki.Main web was split up into TWiki.Main and TWiki.TWiki web.

This upgrade is somewhat more labor intensive, mainly caused by splitting up the TWiki.Main web. Please note that subsequent updates will be much easier because user related topics (in TWiki.Main web) and TWiki related documents (in TWiki.TWiki web) have been separated.

These are the steps you need to perform to upgrade the 01 May 2000 version to the 01 Dec 2000 release: [ We assume export TWIKIROOT=/some/dir/ ]

• Backup all existing TWiki directories ( bin, pub, data, templates )

• Unpack the zip file into some working directory:
  mkdir -p ~/tmp/
cd ~/tmp
unzip ~/TWiki20001201.zip

• Upgrade the TWiki document files ( twiki )
  • Move the document files to your TWiki root, i.e.
    mv ~/tmp/TWiki*.html $TWIKIROOT
mv ~/tmp/readme.txt $TWIKIROOT

• Upgrade cgi-bin scripts ( twiki/bin )
  • Rename your original twiki/bin directory, i.e.
    mv $TWIKIROOT/bin $TWIKIROOT/bin.old
  • Move the new scripts to your original twiki/bin location, i.e.
    mv ~/tmp/bin $TWIKIROOT/bin
  • Merge the changes in your current wikicfg.pm into the new wikicfg.pm. We suggest using diff -c to compared the two files if you have made heavy changes to the file, i.e.
    diff -c $TWIKIROOT/bin.old/wikicfg.pm $TWIKIROOT/bin/wikicfg.pm | less
  • Restore any additional scripts you might have from the old directory, i.e.
    mv $TWIKIROOT/bin.old/somescript $TWIKIROOT/bin/
    (Note that the changes script is obsolete.)
  • In case you have basic authentication:
    • The TWikiRegistration topic moved from the TWiki.Main web to the TWiki.TWiki web. Change .htaccess to reflect the new location, i.e.
      ErrorDocument 401 /cgi-bin/view/TWiki/TWikiRegistration
  • Pay attention to the file and directory permissions (security issue)
  • Test your TWiki installation if you can view topics. (Ignore the %HTTP_EQUIV_ON_VIEW% you see on top of the topic, this will disappear after upgrading the template files.

• Upgrade templates files ( twiki/templates )
  • Rename your original twiki/templates directory, i.e.
    mv $TWIKIROOT/templates $TWIKIROOT/templates.old
  • Move the new templates to your original twiki/templates location, i.e.
    mv ~/tmp/templates $TWIKIROOT/templates
  • Merge the changes in your current template files into the new template files. To compare two files use
    diff -c $TWIKIROOT/templates.old/view.tmpl $TWIKIROOT/templates/view.tmpl | less
  • Restore any additional template subdirectories of your TWiki webs you might have and merge the changes.
  • Test your TWiki installation if you can view topics.

• Upgrade public files ( twiki/pub )
  • Move the new twiki/pub/TWiki directory to your installation, i.e.
    mv ~/tmp/pub/TWiki $TWIKIROOT/pub/
  • Pay attention to the file permissions of the TWiki directory and its subdirectory and files. The files must be writable by the cgi-scripts (usually user "nobody")
  • Move the new twiki/pub/twikilogo* image files to your installation, i.e.
    mv ~/tmp/pub/twikilogo* $TWIKIROOT/pub/

• Upgrade data files ( twiki/data )
  • Move the new twiki/data/TWiki directory to your installation, i.e.
    mv ~/tmp/data/TWiki $TWIKIROOT/data/
    Pay attention to the file permissions of the TWiki directory and its files. The files must be writable by the cgi-scripts (usually user "nobody")
  • Optionally move the new twiki/data/Test directory to your installation, i.e.
    mv ~/tmp/data/Test $TWIKIROOT/data/
    (Pay attention to the file permissions)
  • Move these new TWiki.Main web topics to your TWiki.Main web: TWikiGroups, TWikiAdminGroup, and if needed also OfficeLocations , i.e.
    mv ~/tmp/data/Main/TWikiGroups.* $TWIKIROOT/data/Main
    (Pay attention to the file permissions)
  • The following topics in the TWiki.Main web are obsolete and can be deleted: BillClinton, GoodStyle, RegularExpression, TextFormattingFAQ, TextFormattingRules, TWikiAdministration, TWikiCategoryTable, TWikiEnhancementRequests, TWikiImplementationNotes, TWikiInstallationNotes, TWikiNotificationOfChanges, TWikiPlannedFeatures, TWikiUpgradeTo01May2000, TWikiUsernameVsLoginUsername, TWikiWeb, WelcomeGuest, WelcomeVisitor, WikiName, WikiNotation, WikiTopic, WikiWikiClones. Sample delete command:
    rm -f $TWIKIROOT/data/Main/BillClinton.*
  • The following topics are new and most be copied to all of your TWiki webs: WebChanges, WebIndex.
    cp -p $TWIKIROOT/data/TWiki/WebChanges.txt* $TWIKIROOT/data/Main
cp -p $TWIKIROOT/data/TWiki/WebIndex.txt* $TWIKIROOT/data/Main
    Repeat this for all your webs. Pay attention to the file permissions.
  • TWikiRegistration moved from TWiki.Main to TWiki.TWiki. In case you customized TWikiRegistration , merge your changes back into TWiki.TWikiRegistration , then delete $TWIKIROOT/data/Main/TWikiRegistration*.
  • TWikiPreferences moved from TWiki.Main to TWiki.TWiki. Merge your changes to TWikiPreferences into TWiki.TWikiPreferences.
  • Modify the WebPreferences topics in all your webs to reflect the following:
    • WEBTOPICLIST should use WebChanges for "Changes", and WebIndex for "Index", i.e.
      | <a href="WebChanges">Changes</a>
| <a href="WebIndex">Index</a>
    • In case you want to exclude a web from a web="all" search: Set this new preference
      Set NOSEARCHALL = on
  • The WebSearch topic has considerable changes. Copy the one from TWiki.TWiki into all webs, or merge them if you made changes. To copy, do an edit-copy-edit-paste operation.
  • Change the WebHome topics in all your webs to reflect these changes:
    1. The "Changes" link should point to WebChanges.
    2. The "Topic index" link should point to WebIndex.
    3. Change the include of the web table to %INCLUDE{"%TWIKIWEB%.TWikiWebsTable"}%
  • Merge your TWikiWebsTable topic in TWiki.Main with the TWikiWebsTable topic in TWiki.TWiki. Note the new variable to query the color of a web. Delete the old TWikiWebsTable topic in TWiki.Main after merge is complete.
  • The following topics in the TWiki.Main web are depreciated (because they moved to TWiki.TWiki), but still need to be present in TWiki.Main because of existing links to them: FileAttachment, TWikiDocumentation, TWikiHistory, TWikiPreferences, TWikiVariables.
    It is recommended to edit these topics in TWiki.Main and replace the content with this line:
    This topic moved to %TWIKIWEB%.%TOPIC% in the %WIKITOOLNAME%.%TWIKIWEB% web.
  • In all your webs, change references to topics that moved to the TWiki.TWiki web:
    • Change topics: TWikiUsers , WebNotify , WebHome
    • With links to: TWikiPreferences , TWikiVariables , TWikiUsers , TWikiWebsTable and WelcomeGuest

• TWiki Access Control
  • Read TWikiAccessControl in case you want to use the new authorization feature based on groups.

• Known Issues
  • Check http://TWiki.org/cgi-bin/view/Codev/KnownIssuesOfTWiki01Dec2000 for known issues of TWiki 01 Dec 2000 (production release)

-- PeterThoeny? - 08 Nov 2000

• Forget about authentication. All changes will be registered as TWikiGuest user, e.g. you can't tell who made changes.
• Use basic authentication for the edit and attach scripts. TWiki Installation tells you more about that.
• Use SSL to authenticate and secure the whole server.

The REMOTE_USER environment variable is only set for the scripts that are under authentication. If for example the edit, save and preview scripts are authenticated, but not view, you would get your WikiName in preview for the %WIKIUSERNAME% variable, but view will show TWikiGuest instead of your WikiName.

There is a way to tell TWiki to remember the user for the scripts that are not authenticated, e.g. for the case where the REMOTE_USER environment variable is not set. TWiki can be configured to remember the IP address / username pair whenever an authentication happens (edit topic, attach file). Once remembered, the non authenticated scripts like view will show the correct username instead of TWikiGuest. You can enable this by setting the $doRememberRemoteUser flag in wikicfg.pm. TWiki persistently stores the IP address / username pairs in file $remoteUserFilename, which is "$dataDir/remoteusers.txt" by default. Please note that this can fail in case the IP address changes due to dynamically assigned IP addresses or proxy servers. Test: You are Main.guest.

-- PeterThoeny? - 02 Nov 2000

TWiki Username vs. Login Username

This section applies only if your TWiki is installed on a server that is both authenticated and on an intranet.

TWiki internally manages two usernames: Login username and TWiki username.

• Login username: When you login to the intranet, you use your existing login username, for example pthoeny. This name is normally passed to TWiki by the REMOTE_USER environment variable. TWiki uses this name internally to log topic changes. Login usernames are maintained by your system administrator.
• TWiki username: This is your name in WikiNotation, for example PeterThoeny, recorded when you register in TWikiRegistration; doing so also generates your personal home page in the Main web of your TWiki site.

TWiki can map the intranet username to the Wiki username automatically, provided that the Login username and Wiki username pair has been entered in the TWikiUsers topic. This happens automatically when you register.

NOTE: To correctly enter a WikiName - your own or someone else's - be sure to specify the Main web in front of the Wiki username: write Main.WikiUsername or %MAINWEB%.WikiUsername. This assures that the name will be linked automatically to the Main web, where user home pages are stored, even if the text is entered in a different web.

-- PeterThoeny? - 30 Jan 2003

IMPORTANT NOTE: Think twice before restricting write access to a web or a topic, because an open system where everybody can contribute is the essence of the WikiCulture. Experience shows that unrestricted write access works very well because:

• There is enough peer pressure to post only conform content.
• Content does not get lost because topics are under revision control.
• A topic revision can be undone by a member of the TWikiAdminGroup in case needed.

Users and Groups

Access control is based on users and groups.

Users are defined by the user topics in the Main web, i.e. TWikiGuest

• Users can be authenticated using basic authentication or SSL. Installation Notes has more.

Groups are defined by group topics in the Main web, i.e. TWikiAdminGroup

• A group topic name must end in ...Group
• The group topic should define these two variables:
  • Set GROUP = < list of users and groups >
  • Set ALLOWTOPICCHANGE = < list of users and groups >
• GROUP defines the members of the group; it is a comma delimited list of users and other groups. Example:
      * Set GROUP = Main.SomeUser, Main.OtherUser, Main.SomeOtherGroup
• ALLOWTOPICCHANGE defines who is allowed to change the group topic; it is a comma delimited list of users and groups. You typically want to restrict that to the members of the group itself, so it should contain the name of the topic, i.e.
      * Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup
  for the TWikiAdminGroup topic. (This is to prevent users not in the group from editing the topic and gaining unauthorized membership to the group.)

Access Control for Individual Topics

You can define some restrictions of who is allowed to make changes and attach files to a topic.

Define one or both of these variables in a topic, preferably at the end of the topic:

• Set DENYTOPICCHANGE = < list of users and groups >
• Set ALLOWTOPICCHANGE = < list of users and groups >

DENYTOPICCHANGE defines users or groups that are not allowed to make changes to the topic. It is a comma delimited list of users and groups. Example:
    * Set DENYTOPICCHANGE = Main.SomeBadBoy, Main.SomeBadGirl, Main.SomeHackerGroup

ALLOWTOPICCHANGE defines users or groups that are allowed to make changes to the topic. It is a comma delimited list of users and groups. Example:
    * Set ALLOWTOPICCHANGE = Main.SomeGoodGuy, Main.SomeGoodGirl, Main.TWikiAdminGroup

DENYTOPICCHANGE is evaluated before ALLOWTOPICCHANGE. Access is denied if the authenticated person is in the DENYTOPICCHANGE list, or not in the ALLOWTOPICCHANGE list. Access is granted in case DENYTOPICCHANGE and ALLOWTOPICCHANGE is not defined.

Access Control per TWiki Web

You can define some restrictions of who is allowed to make changes and attach files to topics or create new topics in a TWiki web.

Define one or both of these variable in the WebPreferences topic:

• Set DENYWEBCHANGE = < list of users and groups >
• Set ALLOWWEBCHANGE = < list of users and groups >

The same rules apply like the one for Access Control for Individual Topics; with these additions:

• DENYTOPICCHANGE (in topic) overrides DENYWEBCHANGE (in WebPreferences)
• ALLOWTOPICCHANGE (in topic) overrides ALLOWWEBCHANGE (in WebPreferences)

Related topics: TWikiPreferences, WebPreferences (in every web), TWikiAdminGroup, TWikiGroups

-- PeterThoeny? - 28 Oct 2000

TWiki Templates

Definition of the templates used to render all HTML pages displayed in TWiki

Overview

The new modular template system offers flexible, easy control over the layout of all TWiki pages. The master template approach groups parts that are shared by several templates - like headers and footers - in a common file. Special variables allow individual layouts to include parts from a master template - variables are mixed with regular HTML markup for template-specific content. Templates are used to define page layout, and also to supply default content for new pages.

Major changes from the previous template system

Where the old templates were each complete HTML documents, the new templates are defined using variables to include template parts from a master file. You can now change one instance of a common element to update all occurrences; previously, every affected template had to be updated. This simplifies the conversion of templates into XHTML format, and provides a more versatile solution for templates and for TWikiSkins. The new system:

• separates a set of common template parts into a base template that is included by all of the related templates;
• defines common variables, like a standard separator (ex: "|"), in the base template;
• defines variable text in the individual templates and passes it back to the base template.

How Template Variables Work

• Special template directives (or preprocessor commands) are embedded in normal templates.
• All template preprocessing is done in &TWiki::Store::readTemplate() so that the caller simply gets an expanded template file (the same as before).
• Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
• Directives:
  • %TMPL:INCLUDE{"file"}%: Includes a template file. The template directory of the current web is searched first, then the templates root (twiki/templates).
  • %TMPL:DEF{"var"}%: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
  • %TMPL:END%: Ends variable definition.
  • %TMPL:P{"var"}%: Prints a previously defined variable.
• Variables live in a global name space: there is no parameter passing.
• Two-pass processing lets you use a variable before or after declaring it.
• Templates and TWikiSkins work transparently and interchangeably. For example, you can create a skin that overloads only the twiki.tmpl master template, like twiki.print.tmpl, that redefines the header and footer.
• Use of template directives is optional: templates work without them.
• NOTE: Template directives work only for templates: they do not get processed in topic text.

Types of Template

There are three types of template:

• Master Template: Stores common parts; included by other templates
• HTML Page Templates: Defines the layout of TWiki pages
• Template Topics: Defines default text when you create a new topic

Master Templates

Common parts, appearing in two or more templates, can be defined in a master template and then shared by others: twiki.tmpl is the default master template.

Template variable:	Defines:
%TMPL:DEF{"sep"}%	"|" separator
%TMPL:DEF{"htmldoctype"}%	Start of all HTML pages
%TMPL:DEF{"standardheader"}%	Standard header (ex: view, index, search)
%TMPL:DEF{"simpleheader"}%	Simple header with reduced links (ex: edit, attach, oops)
%TMPL:DEF{"standardfooter"}%	Footer, excluding revision and copyright parts
%TMPL:DEF{"oops"}%	Skeleton of oops dialog

HTML Page Templates

TWiki uses HTML template files for all actions, like topic view, edit, and preview. This allows you to change the look and feel of all pages by editing just a few template files.

Templates are in the twiki/templates directory. As an example, twiki/templates/view.tmpl is the template file for the twiki/bin/view script. Templates can be overloaded by individual webs. The following search order applies:

1. twiki/templates/$webName/$scriptName.tmpl
2. twiki/templates/$scriptName.tmpl
   • $webName is the name of the web (ex: Main)
   • $scriptName is the script (ex: view).

NOTE: TWikiSkins can be defined to overload the standard templates.

Special variables are used in templates, especially in view, to display meta data.

Template Topics

Template topics define the default text for new topics. There are three types of template topic:

Topic Name:	What it is:
WebTopicViewTemplate	Error page shown when you try to view a nonexistent topic
WebTopicNonWikiTemplate	Alert page shown when you try to view a nonexistent topic with a non-WikiName
WebTopicEditTemplate	Default text shown when you create a new topic.

1. A topic name specified by the templatetopic CGI parameter.
2. WebTopicEditTemplate in the current web
3. WebTopicEditTemplate in the TWiki web

Edit Template Topics and Variable Expansion

The following variables get expanded when a user creates a new topic based on a template topic:

Variable:	Description:
%DATE%	Current date, e.g. 19 May 2012
%WIKIUSERNAME%	User name, e.g. Main.guest
%URLPARAM{"name"}%	Value of a named URL parameter
%NOP%	A no-operation variable that gets removed. Useful to prevent a SEARCH from hitting an edit template topic; also useful to escape a variable like %URLPARAM%NOP%{...}%
%NOP{ ... }%	A no-operation text that gets removed. Useful to write-protect an edit template topic, but not the topics based this template topic. See notes below. Example: %NOP{    * Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup }%

Notes:

• Unlike other variables, %NOP{ ... }% can span multiple lines.
• The scan for the closing }% pattern is "non-greedy", that is, it stops at the first occurance. That means, you need to escape variables with parameters located inside %NOP{ ... }%: Insert a %NOP% between } and %. Silly example: %NOP{ %GMTIME{"$year"}%NOP%% }%.

All other variables are unchanged, e.g. are carried over "as is" into the new topic.

Template Topics in Action

Here is an example for creating new topics based on a specific template topic:

The above form asks for a topic name. A hidden input tag named templatetopic specifies ExampleTopicTemplate? as the template topic to use. Here is the HTML source of the form:

<form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%"}%/">
   * New example topic: 
     <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
     <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
     <input type="hidden" name="onlywikiname" value="on" />
     <input type="submit" value="Create" />
     (date format is <nop>YYYYxMMxDD)
</form>

The onlywikiname parameter enforces WikiWords for topic names.

TIP: You can use the %WIKIUSERNAME% and %DATE% variables in your topic templates to include the signature of the person creating a new topic. The variables are expanded into fixed text when a new topic is created. The standard signature is:
-- %WIKIUSERNAME% - %DATE%

Templates by Example

Attached is an example of an oops based template oopsbase.tmpl and an example oops dialog oopstest.tmpl based on the base template. %A% NOTE: This isn't the release version, just a quick, simple demo.

Base template oopsbase.tmpl

The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%

%TMPL:DEF{"sep"}% | %TMPL:END% <html> <head> <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title> <base href="%SCRIPTURL%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%"> <meta name="robots" content="noindex"> </head> <body bgcolor="#FFFFFF"> <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr> <td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%"> <a href="%WIKIHOMEURL%"> <img src="%PUBURLPATH%/wikiHome.gif" border="0"></a> </td> <td> <b>%WIKITOOLNAME% . %WEB% . </b><font size="+2"> <B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font> </td> </tr> <tr bgcolor="%WEBBGCOLOR%"> <td colspan="2"> %TMPL:P{"webaction"}% </td> </tr> </table> --- ++ %TMPL:P{"heading"}% %TMPL:P{"message"}% <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr bgcolor="%WEBBGCOLOR%"> <td valign="top"> Topic <b>%TOPIC%</b> . { %TMPL:P{"topicaction"}% } </td> </tr> </table> </body>

Test template oopstest.tmpl

Each oops template basically just defines some variables and includes the base template that does the layout work.

%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END% %TMPL:DEF{"webaction"}% test =webaction= %TMPL:END% %TMPL:DEF{"heading"}% Test heading %TMPL:END% %TMPL:DEF{"message"}% Test =message=. Blah blah blah blah blah blah blah blah blah blah blah... * Some more blah blah blah blah blah blah blah blah blah blah... * Param1: %PARAM1% * Param2: %PARAM2% * Param3: %PARAM3% * Param4: %PARAM4% %TMPL:END% %TMPL:DEF{"topicaction"}% Test =topicaction=: [[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}% [[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END% %TMPL:INCLUDE{"oopsbase"}%

Sample screen shot of oopstest.tmpl

With URL: .../bin/oops/Sandbox/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify

Known Issues

• A drawback of referring to a master template is that you can only test a template from within TWiki, where the include variables are resolved. In the previous system, each template was a structurally complete HTML document with a .tmpl filename extension - it contained unresolved %VARIABLES%, but could still be previewed directly in a browser.

-- PeterThoeny? - 01 Feb 2003
-- MikeMannix? - 14 Sep 2001
-- TWiki:Main/DavidLeBlanc - 11 Mar 2002

[1] Note: A web can be excluded from a web="all" search if you define a NOSEARCHALL=on variable in its WebPreferences.

Additional variables are defined in the preferences ( site-level ( SL ) in TWikiPreferences, web-level ( WL ) in WebPreferences of each web, and user level ( UL ) preferences in individual user topics):

Notes:

• Preferences variables ( on site-level, web-level and user level ) are defined by bullet lines with this syntax:
  • Set VARIABLENAME = value
• Additional preferences variables can be defined on all three level as needed. Example:
  • Set MYLOGO = %PUBURLPATH%/%MAINWEB%/LogoTopic/logo.gif

-- PeterThoeny? - 10 Nov 2000

Each TWiki web does an automatic email notification of recent changes. Users can subscribe / unsubscribe themselves in WebNotify of each TWiki web. The Perl script mailnotify is called by a deamon in regular intervals. The script is sending an automated email to subscribed users in case some topics changed in a web within this interval.

Installation note for Unix platforms: Edit the cron table so that mailnotify is called in an interval of your choice. Please consult man crontab of how to modify the table that schedules program execution at certain intervals. Example:

% crontab -e
15,45 * * * * (cd ~twiki/public_html/bin; ./mailnotify -q)

-- PeterThoeny? - 20 Sep 2000

Note: This feature has been replaced by: TWikiForms

• See Installation Notes

How to Rename or Delete a Web

• It is advisable not to rename the TWiki.Main web.
• Be aware that other webs might link to the web you want to rename / delete. Search each web for links to this web, i.e. search all webs for Obsolete. (include the period, this is to find topics like Obsolete.SomeTopic ). Take measures if necessary.
• Edit the TWikiPreferences topic and rename / delete the web from the WIKIWEBLIST variable.
• Edit the TWikiWebsTable topic and rename / delete the web from the table.
• Telnet to the TWiki installation.
• cd to twiki/data and rename / delete the web directory.
• cd to twiki/templates and rename / delete the web directory if present.
• cd to twiki/pub and rename / delete the web directory if present.

-- PeterThoeny? - 12 Nov 2000