TWiki Reference Manual (04 Sep 2004 $Rev: 1742 $)

This page contains all documentation topics as one long, complete reference sheet.Doubleclick anywhere to return to the top of the page.

Note - if you are reading this at twiki.org, then you are reading about the most recent code under development.
If you want to read about the features on your local TWiki, then you should read the documentation there!

TWiki System Requirements

Low client and server requirements are core features that keep TWiki widely deployable, particularly across a range of browser platforms and versions.

Server Requirements

TWiki is written in Perl 5, uses a number of shell commands, and requires RCS (Revision Control System), a GNU Free Software package. TWiki is developed in a basic Linux/Apache environment. It also works with Microsoft Windows, and should have no problem on any other platform that meets the requirements.

5.7 or higher (including GNU diff) Optional, but the all-Perl RCS replacement is not currently recommended for live sites - see TWiki:Codev.RcsLite

GNU diff

GNU diff 2.7 or higher is required when not using the all-Perl RcsLite. Install on PATH if not included with RCS (check version with diff -v) Must be the version used by RCS, to avoid problems with binary attachments - RCS may have hard-coded path to diff

*Current documentation mainly covers Linux and Apache installations. See WindowsInstallCookbook for a Windows installation guide. See TWiki:Codev.TWikiOn for help with installation on various platforms including Unix, MacOS X, Apache mod_perl, web hosts, etc.

TWiki Installation Guide

Installation instructions for the TWiki 01-Sep-2004 production release.

If you are reading this on your own TWiki installation, please get the latest installation guide (TWiki:TWiki.TWikiInstallationGuide), as this often has important updates to resolve installation issues.

These installation steps are based on the Apache web server on Linux. TWiki runs on other web servers and Unix systems, and should be fine with any web server and OS that meet the system requirements. Official documentation for platforms other than Linux is somewhat limited, so please check the topics listed below, they include some important tips for HP-UX, Solaris, OS/390, and many other platforms.

Standard Installation

Step 1: Create & Configure the Directories

NOTE:If you don't have access to your Web server configuration files - for example, if you're installing on an ISP-hosted account, or you don't have administrator privileges on your intranet server - use the alternative Step 1 instead.

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 httpd.conf (typcially located in /etc/httpd/) 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 ScriptAliasmust come before the Alias, otherwise, Apache will fail to correctly set up /twiki/bin/, by treating it as just another subdirectory of the /twiki/ alias.

The twiki/data and twiki/templates directories should be set so that they are not visible as URLs. Add them to httpd.conf with deny from all.

Note: Don't worry if you are not able to put the twiki/lib directory at the same level as the twiki/bin directory (e.g. because CGI bin directories can't be under your home directory and you don't have root access). You can create this directory elsewhere and configure the /twiki/bin/setlib.cfg file (done in Step 3)

Step 2: Set File Permissions

Make sure Perl 5 and the Perl CGI library are installed on your system. The default location of Perl is /usr/bin/perl. If it's elsewhere, change the path to Perl in the first line of each script in the twiki/bin directory, or create a symbolic link from /usr/bin/perl.

Alternatively, you might try creating a file twiki/bin/.htaccess that contains the single line SetHandler cgi-script, which tells Apache to treat all files in this directory as CGI scripts.

Set the file permission of all Perl scripts in the twiki/bin directory as executable to -rwxr-xr-x (755).

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.

This Guide assumes user nobody ownership for all files manipulated by the CGI scripts (executed by the Web server), and user twiki for all other files. You can:

replace nobody with another user if your server executes scripts under a different name (ex: default for Debian is www-data).

HINT: Run the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. It will show you the user name of the CGI scripts, a table listing all CGI environment variables, and a test of your twiki/lib/TWiki.cfg configuration file (you'll configure that in a minute).

replace user twiki with your own username

Set permissions manually.

Set the permission of all files below twiki/data so that they are writable by user nobody. A simple way is to chmod them to -rw-rw-r-- (664) and to chown them to nobody.

Set the permission of the twiki/datadirectory and its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.

Set the permission of the twiki/pub directory and all its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.

The twiki/data/*/*.txt,v RCS repository files in the installation package are locked by user nobody. If your CGI scripts are not running as user nobody, it's not possible to check in files (you'll see that the revision number won't increase after saving a topic). In this case, you need to unlock all repository files (check the RCS man pages) and lock them with a different user, such as www-data, or delete them all - new files will be automatically created the first time each topic is edited. You have two options to change ownership of the RCS lock user:

Run the testenv script from your browser; in the Fix line you can relock all the rcs files (recommended)

Step 3: Edit the Configuration Files

Set $twikiLibPath to the absolute file path of your /twiki/lib as seen by the web server.

Attention: Do not leave it as a relative "../lib" path or Plugins might fail to initialize properly

You can also edit $localPerlLibPath if you are not root and need to install additional CPAN modules, but can't update the main Perl installation files on the server. Just set this variable to the full pathname to your local lib directory, typically under your home directory.

Attention: If you are running TWiki on Apache 2.0 on Unix you might experience cgi scripts to hang forever. This is a known Apache 2.0 bug. See details and woraround in the setlib.cfg file.

Edit the file twiki/lib/TWiki.cfg, setting the variables to your needs.

Set the file extension in the $scriptSuffix variable to cgi or pl if required.

RCS - revision control system to store revision of topics and attachments. You can use RCS executables or a version of RCS written in Perl, note that as the time of writing (Apr 2002) the Perl version has not been widely tested, so if you want to put up a live site the RCS executables are recommended.

Set $storeTopicImpl = "RcsWrap"; for the RCS executables and make sure RCS is installed. Set $rcsDir in twiki/lib/TWiki.cfg to match the location of your RCS binaries. You can check this by issuing the command rcs at the prompt, it should result in something like "rcs: no input file".

Check that you have GNU diff, by typing diff -v - an error indicates you have a non-GNU diff, so install the GNU diffutils package and make sure that diff is on the PATH used by TWiki (see $safeEnvPath in the TWiki.cfg file).

Set $storeTopicImpl = "RcsLite"; for the Perl based RCS

Security issue: Directories twiki/data , twiki/templates and all their subdirectories should be set so that they are not visible through URLs. (Alternatively, move the directories to a place where they are not visible, and change the variables in twiki/lib/TWiki.cfg accordingly)

Step 4: Internationalisation Setup (Optional)

By default, TWiki is configured to support US ASCII letters (no accents) in WikiWords, and ISO-8859-1 (Western European) characters in page contents. If that's OK for you, skip this step.

If your Wiki will be used by non-English speakers, TWiki can be configured for Internationalisation ('I' followed by 18 letters, then 'N', or I18N). Specifically, TWiki will support suitable accented characters in WikiWords (as well as languages such as Japanese or Chinese in which WikiWords do not apply), and will support virtually any character set in the contents of pages. NOTE: TWiki does not currently support UTF-8, so you are advised not to use this - however, improved UTF-8 support is under development, see TWiki:Codev/ProposedUTF8SupportForI18N.

To configure internationalisation suppport:

Edit the TWiki.cfg file's Internationalisation section to set the $useLocale parameter to 1. TWiki will now use the I18N parameters set in the rest of this section.

Type the Unix/Linux command locale -a to find a suitable 'locale' for your use of TWiki. A locale that includes a dot followed by a character set is recommended, e.g. pl_PL.ISO-8859-2 for Poland. Consult your system administrator if you are not sure which locale to use.

In TWiki.cfg, set the $siteLocale parameter to your chosen locale, e.g. pl_PL.ISO-8859-2 for Poland.

Check your setup using testenv (download the latest testenv from TWiki:Support/SupportGuidelines if possible) - this provides some diagnostics for I18N setup, and in particular checks that your locale can be used successfully.

(For upgrade of TWiki I18N sites only:) If you were using TWiki:Codev.TWikiRelease01Feb2003 support for I18N, and are using Internet Explorer or Opera, you should re-configure your browser so that it sends URLs encoded with UTF-8 (supported since TWiki:Codev.TWikiRelease01Sep2004). If you are doing a new installation of TWiki, you can ignore this step - no browser reconfiguration is needed for TWiki Release 01-Sep-2004).

NOTE: This does not mean that TWiki supports UTF-8 as a site character set.

Try out your TWiki by creating pages in the Sandbox web that use international characters in WikiWords and checking that searching, WebIndex, Ref-By and other features are working OK.

Trouble with I18N?

If international characters in WikiWords do not seem to work, and you are on Perl 5.6 or higher, you may need to set the TWiki.cfg parameter $localeRegexes to 0 - this disables some features but enables TWiki to work even if your system has locales that do not work. Then, set the $upperNational and $lowerNational parameters to the valid upper and lower case accented letters for your locale.

NOTE: You will need to do the above workaround for Windows based servers (whether using Cygwin or ActiveState Perl), since Perl locales are not working on Windows as of Feb 2004.

If international characters in WikiWords aren't working, and you are on Perl 5.005 with working locales, keep $useLocale set to 1 and set $localeRegexes to 0, then set $upperNational and $lowerNational - if testenv generates the lists of characters for you, your locales are working so there is no need to set $localeRegexes to 0 in this case. See the comments in TWiki.cfg for more information.

Step 5: Configure Site-Wide Email Preferences

Edit the TWikiPreferences topic in the TWiki web (by pointing your browser to http://yourdomain.com/twiki/bin/view/TWiki/TWikiPreferences) to set the WIKIWEBMASTER email address, and other email settings required for registration and WebChangesAlert to work:

WIKIWEBMASTER should be set to the email address of the TWiki administrator

SMTPMAILHOST is typically set on Windows or other non-Unix/Linux systems, where sendmail or similar is not available. When this is set and the Perl module Net::SMTP is installed, TWiki will connect to this SMTP server (e.g. mail.yourdomain.com) to send email for user registration and WebChangesAlerts. If you do have a sendmail-type program, leave SMTPMAILHOST unset so that the external sendmail program is used instead (defined by $mailProgram in TWiki.cfg).

SMTPSENDERHOST is optional, and set to the domain name sending the email (e.g. twiki.yourdomain.com). For use where the SMTP server requires that you identify the TWiki server sending mail. If not set, Net::SMTP will guess it for you.

Step 6: Finish Up from Your Browser

Point your Web browser at http://yourdomain.com/twiki/bin/view and start TWiki-ing away!

Or, point to http://yourdomain.com/twiki/ to get the pre-TWiki index.html page, with a link to the view script. Customize this page if you want a public intro screen with a login link, instead of immediately calling up the .htaccess login dialog by going directly to view.

Edit the WebPreferences topic in each web, if necessary: set individual WEBCOPYRIGHT messages, and other preferences.

That's it for the standard installation of TWiki. Read on for server-level customization options.

Additional Server-Level Options

With your new TWiki installation up and running, you can manage most aspects of your site from the browser interface. Only a few functions require access to the server file system, via Telnet or FTP. You can make these server-level changes during installation, and at any time afterwards.

Enabling Authentication of Users

If TWiki is installed on a non-authenticated server - not using SSL - and you'd like to authenticate users:

Rename file .htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. The comment at the top of the file explains what need to be done, basically replace !FILE_path_to_TWiki! and !URL_path_to_TWiki! with paths specific to your installation. For the details of how this file works, consult the HTTP server documentation (for Apache server: [1], [2]).

NOTE: If you had to add a .cgi or .pl file extension to the bin scripts, make sure to do the same for edit, view, preview, and all the other script names in .htaccess.

The browser should ask for login name and password when you click on the Edit link. In case .htaccess does not have the desired effect, you need to enable it: Add "AllowOverride All" to the Directory [3] section of access.conf for your twiki/bin directory.

This applies only if you have root access: on hosted accounts, you shouldn't have this problem - otherwise, email tech support.

NOTE: In the TWiki distribution package, the twiki/data/.htpasswd.txt file contains several TWiki core team user accounts and a guest user account. You probably want to remove those accounts by deleting the entries in .htpasswd. Do not remove the guest user if you want to allow guest logins.

TWiki now supports several Password file format/encoding methods for Apache. Once you know what method is used by your Appache server, you can configure TWiki to create compatible .htpasswd entries by editing the $htpasswdFormatFamily, $htpasswdEncoding and $htpasswdFilename in the TWiki.cfg file. The supported options are htpasswd:plain, htpasswd:crypt, htpasswd:sha1, htdigest:md5

Copy the TWikiRegistrationPub topic to TWikiRegistration, overwriting old version of TWikiRegistration. Do that by either editing the topics in theTWiki web, or by renaming the .txt and .txt,v files in the twiki/data/TWiki directory.

Customization:

You can customize the registration form by deleting or adding input tags. 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 ensures that the fields are carried over into the user home page correctly.

NOTE: When a user registers, a new line with the username and encrypted password is added to the data/.htpasswd file. The .htpasswd file that comes with the TWiki installation includes user accounts for TWiki core team members that are used for testing on TWiki.org. You can edit the file and delete those lines.

WYSIWYG Editor

NOTE: User home topics are located in the TWiki.Main web - don't try to move them or create them in other webs. From any other web, user signatures have to point to TWiki.Main web, using a Main.UserName or %MAINWEB%.UserName format. (The %MAINWEB% variable is an advantage if you ever change the Main web name, but the standard Main.UserName is easier for users to enter, which is the bottom line!)

Windows Install Cookbook

Introduction

This cookbook is intended to get you up and running with TWiki on Windows quickly, with as few problems as possible. The 'cookbook' approach is simply to restrict the many choices that someone installing TWiki must make, so that a reasonably well-defined procedure can be followed - new users can simply follow the steps, while experts can use this as more of a guideline.

NOTE: This cookbook is not 100% complete (e.g. it doesn't cover authentication setup described by existing documentation), but it has been used successfully for over a year now - it is quite accurate and should get you started if you follow the instructions. Please provide feedback in TWiki:Codev.WindowsInstallCookbookComments.

NOTE: You will get the best results from following this cookbook exactly, using the same directories, etc - however, if you really do need to vary things, it should be fairly obvious what to do.

Scope

This document covers installation of the TWiki 01-Sep-2004 production release (TWiki:Codev/TWikiRelease01Sep2004) in the following environment - if you want to use a different environment, feel free to use this as a guideline only.

Windows-specific security holes fixed in this build (check latest version at http://httpd.apache.org, but don't use Apache 2.0 yet)

Unix tools

Cygwin 1.3.9

Simplest way to get a whole set of required tools

Perl

Cygwin perl-5.6.1-2

Comes with Cygwin, don't use Perl 5.8.0 yet

RCS

Cygwin rcs-5.7-2

Comes with Cygwin, includes a file corruption bugfix

Why this choice of packages? Because I've tried them, and they work well, without requiring a complicated setup... In particular, Apache is the commonest choice for TWiki on Unix/Linux, Cygwin Perl is very close to Unix Perl, and the Cygwin RCS is regularly updated, with a recent TWiki-relevant bug fix in Feb 2002. Cygwin also lets you install the Unix tools, Perl and RCS in a single step, saving quite a lot of time.

More recent minor versions should be OK, but they can introduce bugs.

Major version upgrades, such as Apache 2.0 and Perl 5.8, are very likely to cause problems - for example, Apache 2.0 is unable to authenticate users created by the current TWiki user registration script (due to a feature being removed in 2.0, see TWiki:Support.FailedAuthenticationWithApache2OnWinNT). Similarly, Perl 5.8 may introduce issues due to its Unicode features and has caused problems due to a bug in CGI.pm. Even though the Apache group says that Apache 2.0 is the best version, that's not true for TWiki at present. For more information, see TWiki:Codev.IssuesWithApache2dot0 and TWiki:Codev.IssuesWithPerl5dot8.

Alternatives

The following Windows operating systems have been tested following the instructions given here:

Using a different web server is certainly possible, but the setup required for each webserver varies greatly (see TWiki:Codev.TWikiOnWindows for pages about specific web servers). You may find it easiest to get a working system with Apache and then switch over to another web server.

Covering the whole range of additional possibilities, particularly web servers, would make this cookbook too complex, and is best handled as a separate activity.

If you have an older version of any component, do yourself a favour and upgrade it as part of the install process.

Pre-requisites and upgrades

You will need to have local administrator rights and be comfortable with Windows administration.

This cookbook is intended for a clean install, i.e. none of these components are already installed. However, since Cygwin and Apache's installation process is fairly upgrade-friendly, upgrades should work as well - take backups of all your data and config files first, though!

Text editing

Editing Cygwin files should be done with an editor that can handle Unix file format (see the Cygwin binary mode section below). The installation process suggests:

nano, a very simple text editor, installed optionally during Cygwin installation. Always launch nano with the -w command-line option to turn off wrapping of long lines.

vi, a more sophisticated editor that should be familiar to most UNIX users

These both non-GUI editors, but if you prefer to use a GUI editor you should install PFE, a freeware editor that supports Unix format files. PFE is available on download.com and Simtel.

The Unix/Windows Environment

It's a little known fact that you can use pathnames such as c:/apache almost everywhere in Windows - try it in a File Open dialogue box. The main exception is the Windows "DOS" command line shell - here, you must use double quotes around forward slashes, e.g. dir "c:/apache" will work fine.

The reason this matters is that '\' is a special character to Perl and other tools, so it's much easier to use '/' everywhere.

The Cygwin environment

TWiki:Codev.CygWin is a Unix-like environment for Windows - many of its tools support the c:/apache format, but it also provides a more Unixlike syntax, e.g. /usr/bin/rcs.exe, because some Unix tools ported onto Cygwin only support the Unix format.

When you launch a Cygwin shell, your existing PATH variable is translated from the Windows format to the Unix format, and the ';' separators in the Windows PATH are changed into ':' separators as required by Unix. A Cygwin tool (e.g. Cygwin Perl or Cygwin RCS) will always use the Unix PATH format, and will accept Unix format pathnames.

The Apache environment

Apache runs as a native Windows process and has nothing to do with Cygwin (at least the version used in this cookbook doesn't). Hence it supports c:/ pathnames in its config files and the first line of Perl CGI scripts.

If you need to use spaces in file names (not recommended), put double quotes around the file name in the httpd.conf file. There have been some security-related bugs in Apache with long pathnames, which are a bit more likely if you use spaces, so it's best to just avoid long names and using spaces.

The Perl environment

Once Perl has been launched by Apache, it is in Cygwin mode, and so is everything it launches, including ls, egrep, and the RCS tools that it (typically) launches with the bash shell.

If you need to use spaces in file names (not recommended), you may be able to put double quotes around the file name in the TWiki.cfg file - however, it's not clear whether all the TWiki code would work with this.

Installing Components

Enough background, let's get on with the installation.

TWiki (part 1)

Head to http://twiki.org, click the download link, and fill in the form to request a URL for download. You'll get an automated email, which should arrive by the time you need it.

Apache

Steps 1 and 2 can be shortcut by opening the self-installing executable on the Apache website that installs Apache 1.3.x. The painful details below are mainly helpful when detecting where things are going wrong.....

The file to download is apache_1.3.X-win32-x86-no_src.msi where 'X' is 20 or higher

Note that this is a Microsoft Installer format file (.MSI)

NOTE: If you are using Windows NT, download the .MSI installer (instmsi.exe) from the Apache Win32 download page - this enables you to install .MSI files. You may need to update the .MSI Installer if you have an old version under NT.

NOTE: The Apache package itself requires a download of around 2 MB, and up to 10 MB of free disk space once installed

2. Install Apache

Double-click the .MSI file to run the installer

Specify c:\ as the installation directory - this actually installs Apache into c:\apache (if you specify c:\apache, it installs into c:\apache\Apache). Putting Apache into c:\Program Files is not recommended for easy editing of Apache config files from Cygwin.

On Windows NT/2000 you can choose to run Apache as a service or as a normal program - see the Apache docs for details.

apache -k restart -n apache for Apache running as a Win2000 service (-n gives name of service)

Another useful command is apache -k stop.

Cygwin, Unix tools, Perl and RCS

4. Install Cygwin

Head to http://cygwin.com, and click the Install or update now! link. Save the setup.exe in a directory, e.g. c:\download\cygwin-dist.

Now run the Cygwin setup.exe file - this will also install Perl and RCS in one fell swoop.

Choose Internet install

On first page, accept the defaults (be sure that the default text file type is Unix to avoid problems with attachment uploads, and specify 'install for all users')

Select c:\download\cygwin-dist as the local package directory, and suitable proxy settings, then pick a local mirror site

In the package list screen, hit the View button until you get an alphabetical list that says Full to the right of the button.

Leave the radio button on Curr (Current)

The Current column shows what's installed on your system (if anything)

For each package, make sure the New column in the installer has a version number under it. If it says 'Skip' or 'Keep' (meaning it's already installed), single-click that word until a version number is shown. Make sure you select the following packages - in recent Cygwin setups you will have to select Perl 5.6.1 explicitly:

NOTE: Do not include lynx if you are upgrading from an older Cygwin installation (to avoid annoying DLL messages) - if you want Lynx, read the Cygwin FAQ entry and upgrade libncurses5.

Hit Next to do the installation.

NOTE: The mandatory packages require a download of about 12 MB - about half of this is Perl, which would be necessary even without Cygwin, and most of the rest is gcc, which is required for simple installation of Perl modules that use the C language. Something like 20 to 30 MB of free disk space should be enough for Cygwin, but I didn't test this (try a du -k / after a new install and let me know the last figure).

NOTE: The installer keeps a local copy of downloaded files, so it's easy to re-install without re-downloading.

Let the installer create the shortcuts suggested

You can always come back and re-run the installer again later if you missed anything.

Environment setup:

Set the HOME environment variable to c:\cygwin\home\YOURUSER, where YOURUSER is your userid, e.g. jsmith or administrator.

Windows NT, XP and 2000: Go into Control Panel, double-click the System icon, and select Advanced, then click Environment Variables. Under User Variables, click New.... Now type HOME (must be upper case) as the variable name, and c:\cygwin\home\YOURUSER as the value, and hit OK.

Windows 98 and ME - add to AUTOEXEC.BAT and reboot

You can also set TEMP to c:\temp at this point, if you prefer this to editing the Cygwin ~/.profile file. (HOME can't be set in the ~/.profile file.)

Create the c:\cygwin\home\YOURUSER directory

5. Test Cygwin

Launch the desktop icon - this runs the bash shell, which has command line editing features

Use the cursor up key to recall previous commands - normal PC editing keys can then be used to edit a command

TIP: When typing a directory or file name, hit the TAB key after the first few letters of the name - bash will 'complete' the name. If bash beeps at you, hit TAB again to see the files/directories that match the name so far, and type a bit more before hitting TAB. This saves a lot of time!

Type rcs -V - you should see the RCS version, 5.7

Type perl -v - you should see cygwin mentioned in the first line, and the Perl version, 5.6.1

This is very important - omitting this step leads to a partially working system that corrupts RCS files - without this, Cygwin tools (including Perl and RCS) will add unwanted carriage returns (Ctrl/M, '\r') to files in an attempt to translate between the Windows and Unix text file formats (Unix text files only use line feeds ('\n').

This configures /twiki (known as a 'mount point') to map onto c:/twiki and for that directory tree to always be in binary mode, and does the same for /c, mapping it onto c:/. The last-but-one command sets binary as the default for any unmounted drives (e.g. z:/, aka /cygdrive/z).

It is very important that all lines in the output of mount say 'binmode' under Flags

If the lines for C:\cygwin directories do not, you should uninstall and then re-install Cygwin to ensure that binary attachment uploads will work.

You can now refer to files using Unix paths, e.g. /twiki/bin/view or /c/apache/Announcement - see the Cygwin documentation for more details on this.

Now test this, still using the Cygwin shell:

Type cd /twiki

Type echo hi >t

Type cat -v t - you should see hi as the output

If you see filename errors, your mounts did not work for some reason - check your typing

If you see hi^M as output, your /twiki directory is not in binary mode

Clean up by doing rm t

This setup is written to the Windows registry, so there's no need to put these commands into a .profile file. For more information on binary vs text mode, see this User Guide section and this FAQ entry.

TWiki (part 2)

7. Download TWiki

Download the latest TWiki release from http://twiki.org/ and save it in the c:/twiki directory.

8. Install TWiki

Unzip the ZIP file under c:/twiki using WinZip, or by going into Cygwin and doing the following - you can hit the TAB key to complete filenames after you've typed the first part:

$ cd /twiki
$ unzip TWiki20011201.zip

Configuring components

Now that all the components are installed, you need to configure them.

Configuring Apache

The setup given here is fairly simple, in that it allows only TWiki to be served by the web server. For more complex setups, you can investigate the Alias and ScriptAlias commands that are left commented out in this configuration.

NOTE: This needs reviewing for security holes and to ensure nothing is missed, though this config does work.

1. Configure Apache (part 1)

Using a suitable text editor (see #TextEditing, above) edit c:/apache/conf/httpd.conf as follows - this tells Apache where TWiki lives, and removes the need to tinker with the Windows environment settings.

Note the trailing '/' characters in various places - they are important!

Create the c:\temp directory, by typing mkdir c:\temp in a DOS command line window

Configuring TWiki

NOTE: It should be possible to use c:/twiki format pathnames for Cygwin, given the above binmode setup, but I have not tested this fully - a Cygwin Perl test script does generate binary mode files in this configuration, so it should work with RCS as well (really need a small RCS file corruption test case). Watch out for RCS file corruption carefully if you do try c:/twiki pathnames with Cygwin, and do report your experiences...

NOTE: Some recent versions of Cygwin (e.g. 1.3.10) seem to create 'symbolic links' from fgrep and egrep to grep, requiring the settings for these commands to point directly to grep (with suitable flags to provide fgrep and egrep behaviour).

If for some reason the edit goes wrong, just type cp .backup/* . (while within the bin directory) to restore the original distribution files. Use ls -a to see the .backup directory, and ls -a .backup to view its contents.

Optional step: you can do 'rm *~' to clean out the backups made by Perl, but that's not essential as all the original files cannot be executed. If you do this, type the command very carefully, as a space after the '*' will wipe out all files in this directory!

5. Minor changes to TWiki scripts

TWiki Dec 2001 release only - fixed in Feb 2003 release

If using the Dec 2001 release, you now need to make some minor edits to files in the c:/twiki/bin directory, using a suitable editor (remember to use nano -w filename if you prefer nano to vi - or just use the Windows PFE editor).

Edit the register script in /twiki/bin - change line 200 to read as follows (insert the MIME::Base64:: part):

Perl module installation

6. Installing required Perl modules

Some additional Perl modules are needed, above and beyond the standard modules installed with Cygwin. Fortunately, there is an automated tool that makes it easy to do this - it's called cpan, and goes to the Perl module archive site, http://www.cpan.org/, to download all required modules, and then build and install them.

Note: if you are unable to get cpan working in your environment, don't panic; you can still install the modules manually. In this case, follow the instructions in CPAN: The Hard Way.

First of all, you need to get the cpan tool configured and working - this is only necessary once. From the Cygwin shell, type the following (putting the export command in ~/.profile is recommended to make this setting persistent). Without the TEMP variable, some modules may fail to install on Windows 2000 and higher.

$ export TEMP=/c/temp
$ cpan

Lots of questions about configuration and preferences - just hit Enter until you
get to the questions about mirror sites, but answer the questions about FTP proxies etc
if you are behind a proxy-based firewall. The CPAN tool will fetch a series of files,
some quite large, as part of this setup process, so be patient...

NOTE: If you are behind a non-proxy-based firewall that requires the use of passive FTP, the initial downloads of files using Net::FTP may appear to hang - just wait 5 or more minutes, however, and the CPAN tool should eventually hit on ncftpget, which is part of Cygwin and does work OK. If this doesn't work and you are behind a typical NAT-based firewall, try doing the following at the Cygwin shell before running cpan - this forces Net::FTP to use passive FTP, letting it get through such firewalls:

$ export FTP_PASSIVE=1

If this works, add this line to your ~/.profile file for future use.

Once some initial files are downloaded, you are asked to select your continent and country, and then mirror sites - just type the number of the mirror sites you want to use (pick a few in case one is down):

Eventually, you'll get to the cpan installer's shell prompt, where you need to install a few modules - the tool will do all the work for you.

NOTE: You will need to have previously installed the Cygwin make and gcc packages, which are required by the CPAN installer (gcc is required for modules that include C language code) - you can install them now by launching Cygwin's setup.exe from c:/download/cygwin-dist (no need to exit the CPAN installer).

cpan shell -- CPAN exploration and modules installation (v1.59_54)
cpan> install Net::SMTPMay already be installed - if it is, try 'force install', since it's useful to be able to set
firewall and passive FTP configuration when using Net::FTP. Make sure you answer 'Y' to the question
about whether you want to configure this package.
cpan> install Digest::SHA1Lots of output about how CPAN finds, builds and installs the module - watch for
any errors, though it should work fine if you have installed the Cygwin packages listed above (particularly 'gcc' and 'make').
cpan> install MIME::Base64May already be installed.

CPAN: The Hard Way

If you find that cpan doesn't work for you, perhaps because you are behind an uncooperative corporate firewall, you may have to fall back on installing modules manually. In this case, you need to read the CPAN INSTALL page and visit the CPAN search site to search for each module you require. Usually installation simply involves downloading the module distribution into a temporary directory and unpacking it (a .tar.gz or .tgz file is unpacked using tar zxvf file). Then do the following:

$ perl Makefile.PL
$ make
$ make test
$ make install

The make test step should not be skipped - for example, one known problem is with the Digest::SHA1 module on Windows NT, which does not pass its tests and does not work. This causes problems with password encoding. In this event you can use another encoding scheme or switch to unencoded passwords. There may be other problems on the various Windows configurations, and you can save yourself a lot of time.

Re-locking RCS files

7. Re-locking files

First, some testing: in your browser, go to http://yourdomain.com/bin/testenv - this provides a lot of detail, including warnings. Write down the Apache server's userid that is given by this script - typically either 'system' or 'administrator' - I'll assume 'system' from now on.

If the testenv script doesn't work, go back and check the configuration of the Apache httpd.conf file, and TWiki.cfg. Have a look at the Apache error log, c:/apache/logs/error_log, and the TWiki error log, /twiki/data/log*.txt.

This 'system' user must own the locks on the RCS files, which are shipped with the lock held by 'nobody'. The reason this matters is that no revisions will be tracked by RCS unless the Apache userid matches that of the RCS file locks.

You can re-lock files using rcs -u and rcs -l, but it's a painfully manual process. Instead, just use Perl again to mass-edit all the RCS files, as follows:

NOTE: The 'NR <= 10' part of the Perl command ensures that it only operates on the first 10 lines, to avoid editing the body of RCS files for topics that happen to include the text 'nobody:' (like this one...)

If something goes wrong: to restore your existing files from the backup, just type tar xzvf all-files.tar.gz and all your files, both .txt and .txt,v, will be back as they were before the edits.

You have now re-locked all the RCS files and are almost ready to start using TWiki!

Email setup

8. Email setup for notification and registration

You need to set the SMTPMAILHOST in TWikiPreferences to an SMTP email host that is reachable and currently working. Otherwise you may get a confusing message from TWiki (fixed in TWiki:Codev.TWikiRelease01Feb2003) when registering new users or running mailnotify (for WebNotify), along the lines of:

There are other settings to be made in TWikiPreferences, e.g. the WIKIWEBMASTER and (probably) the SMTPSENDERHOST (normally your mail server or TWiki server). See the TWikiInstallationGuide for more details, what's listed here is just enough to let you run the basic tests.

Testing your TWiki installation

It is important to test your TWiki installation before you release it to other users or put any significant data into it.

Here are the main things to test:

testenv - use http://yourdomain.com/bin/testenv and check for warnings

If you are having installation trouble, download the latest testenv from TWiki:Codev/TWikiAlphaRelease and install it in c:/twiki/bin. (From TWiki.org, just click CVSget:bin/testenv to get this script)

Page viewing (view script) - click around a few pages and make sure the links are OK

RCS diffs (rdiff script) - click on the Diffs link and on the '>' links at bottom of page

Edit a page, and register as a new user - tests page creation, use of register script to create a new user entry in /twiki/data/.htpasswd (the Apache password file), ability to send email via Net::SMTP, and whether SMTPMAILHOST was set correctly in TWikiPreferences (if it is unset it will not use Net::SMTP and will almost inevitably fail silently).

If you get a failure to register or send email, check the Apache error log, and that all CPAN modules were installed correctly in Step 6, Installing required Perl modules.

Try typing tail -30 /c/apache/logs/error_log to see last 30 errors from Apache

Edit a page - check revision increased and set to current date/time

Edit the same page using another browser or PC, logging in as a different user - check there's a lock message (which you can override) and no double lines

Check the Apache error_log file to see if there are any RCS errors so far

Index - tests whether ls and grep are working

Search - more tests for whether ls and grep are working

Attachments - tests access to /twiki/pub directory.

Try a binary attachment upload and check the number of bytes in the file has not changed - if it has, see the Install Cygwin section's note on the default text file type.

Check the Apache error_log file again

Troubleshooting

If anything doesn't work, go back and check the configuration of the Apache httpd.conf file, and TWiki.cfg. Have a look at the Apache error log, c:/apache/logs/error_log, and the TWiki error log, /twiki/data/log*.txt, and if necessary enable debugging on selected scripts (the commands are right at the top of each script) - the results go into /twiki/data/debug.txt. There is also a /twiki/data/warning.txt file that contains less serious messages.

Permissions

By default, it only implements the Unix 'write' and 'execute' permissions bits - the former is controlled by the Windows Read-Only attribute, while the latter is automatically assigned to files named *.exe or *.com, and to files whose first line is a shebang (i.e. #!/bin/something). This is what has been used for this cookbook.

You can enable the 'ntea' or 'ntsec' models, which will increase security but are also likely to introduce permission problems.

I have not had any problems with TWiki permissions on Windows, unlike Linux/Unix, which is probably because I'm using the default security model for Cygwin. If you use the other models, you may still be OK if you have local admin rights, and Apache is running as the SYSTEM user (which it uses if started as a service). If you do have trouble in this area, see the TWikiInstallationGuide's advice, some of which will apply to TWiki:Codev.CygWin, and log any issues in TWiki:Codev.WindowsInstallCookbookComments.

Depending on the Perl version used (Cygwin or TWiki:Codev.ActivePerl), the TWiki.cfg file uses a mixture of Unix and Cygwin format paths - stick to the format used in the installation step for TWiki.cfg

And many more enhancements, see the complete change log at TWikiHistory

Automated Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release

With the 01-Sep-2004 Release, for the first time, comes a helper script for upgrading from a previous version. This feature is currently at beta stage, it has only been sanity tested under Unix. It should be worth giving it a try, it won't mess up your existing
TWiki installation because it leaves that untouched.

Assuming all goes well, UpgradeTwiki will give you the final instructions.

There are a few points worth noting:

UpgradeTwiki may not be able to merge all the changes you made in your existing TWiki into the new installation, but it will tell you which ones it couldn't deal with

UpgradeTwiki creates the new installation in a new directory tree. It makes a complete copy of all your existing data, so:

Clearly you need to point it to a location where there is enough space

If you have symlinks under your data/ directory in your existing installation, these are reproduced as actual directories in the new structure. It is up to you to pull these sub-directories out again and re-symlink as needed

UpgradeTwiki doesn't deal with custom templates or Plugins, you will have to reinstall these in the new installation

If you have done tricky stuff with $OS in your existing TWiki.cfg file, then you will need to manually examine the new TWiki.cfg file and possibly put your tricky changes in there manually

If you use it, and would be kind enough to add your experiences to TWiki:Codev.UpgradeTwiki, it would be much appreciated. The report of your experience will help to make UpgradeTwiki more robust.

Manual Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release

The following steps describe the upgrade assuming that $TWIKIROOT is the root of your current 01-Feb-2003 release. As written this will require some downtime. A process for switching over without downtime is described at the end of this section.

Make sure that the directories and files below $TWIKIROOT/pub/TWiki are writable by your cgi-script user

Move all files in pub/icn directory from the temporary location to your $TWIKIROOT/pub/icn directory

Verify installation:

Execute the $TWIKIROOT/bin/testenv script from your browser (e.g. http://localhost/bin/testenv) to see if it reports any issues; address any potential problems

Test your updated TWiki installation to see if you can view, create, edit and rename topics; upload and move attachments; register users

Test if the installed Plugins work as expected. You should see the list of installed Plugins in TWiki.WebHome

Note: These steps assume a downtime during the time of upgrade. You could install the new version in parallel to the existing one and switch over in an instant without affecting the users. As a guideline, install the new version into $TWIKIROOT/bin1, $TWIKIROOT/lib1, $TWIKIROOT/templates1, $TWIKIROOT/data/TWiki1 (from data/TWiki), $TWIKIROOT/pub/TWiki1 (from pub/TWiki), and configure TWiki.cfg to point to the same data and pub directory like the existing installation. Once tested and ready to go, reconfigure $TWIKIROOT/bin1/setlib.cfg and $TWIKIROOT/lib1/TWiki.cfg, then rename $TWIKIROOT/bin to $TWIKIROOT/bin2, $TWIKIROOT/bin1 to $TWIKIROOT/bin. Do the same with the lib, templates and data/TWiki directories.

Known Issues

TWiki User Authentication

TWiki site access control and user activity tracking options

TWiki does not authenticate users internally, it depends on the REMOTE_USER environment variable. This variable is set when you enable Basic Authentication (.htaccess) or SSL "secure server" authentication (https protocol).

TWiki uses visitor identification to keep track of who made changes to topics at what time and to manage a wide range of personal site settings. This gives a complete audit trail of changes and activity.

Authentication Options

No special installation steps are required if the server is already authenticated. If it isn't, you have these options for controlling user access:

No login at all: Forget about authentication to make your site completely public - anyone can browse and edit freely, in classic Wiki mode. All visitors are assigned the TWikiGuest default identity, so you can't track individual user activity.

How: Default, no web server configuration necessary

No login to view; require login to edit: Keeping track of who changed what and when, while keeping view access unrestricted is desirable in most TWiki deployments. This option is not suitable if you need TWikiAccessControl for view restricted content since TWiki does not know who a user is when looking at content.

No login to view unless necessary; require login to edit: You prefer not to bother the user with login for unrestricted content, but you need TWikiAccessControl for view restricted content. There are two ways to accomplish this:

How 1: Use Basic Authentication with Partial Authentication (described below)

How 2: Use one of the Session TWiki:Plugins where you give the user the option to login and logout.

Require login to view and edit: Most restrictive, but TWiki knows who the user is at all times. There are two ways to accomplish this:

Partial Authentication

Tracking by IP address is an experimental feature, enabled in lib/TWiki.cfg. It lets you combine open access to some functions, with authentication on others, with full user activity tracking:

Normally, the REMOTE_USER environment variable is 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.

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.

Enable this feature by setting the $doRememberRemoteUser flag in TWiki.cfg. TWiki then persistently stores the IP address/username pairs in the file, $remoteUserFilename, which is "$dataDir/remoteusers.txt" by default.

Copy the view script to viewauth (or better, create a symbolic link)

Add viewauth to the list of authenticated scripts in the twiki/bin/.htaccess file. The view script should not be listed in the .htaccess file.

This approach can fail if the IP address changes due to dynamically assigned IP addresses or proxy servers.

Quick Authentication Test - Use the %WIKIUSERNAME% variable to return your current identity:

You are Main.guest

TWiki Username vs. Login Username

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

Login Username: When you login to the intranet, you use your existing login username, ex: pthoeny. This name is normally passed to TWiki by the REMOTE_USER environment variable, and used internally. Login Usernames are maintained by your system administrator.

TWiki Username: Your name in WikiNotation, ex: PeterThoeny, is recorded when you register using TWikiRegistration; doing so also generates a personal home page in the Main web.

TWiki can automatically map an Intranet (Login) Username to a TWiki Username, provided that the username pair exists in the TWikiUsers topic. This is also handled automatically when you register.

In the original TWiki distribution, in twiki/data, there are two registration form topics, TWikiRegistration and TWikiRegistrationPub. The original form includes an intranet Login Username field. For Basic Authentication, the original form is replaced by the Pub version. If you started using TWiki on Basic Authentication and want to change, you have to switch back forms for future use, and manually correct the existing entries, by editing TWikiUsers, adding the Login Username for each member - PeterThoeny - pthoeny - 01 Jan 1999 - and also in the .htpasswd file, where you can either replace the WikiNames or duplicate the entries and have both, so both usernames will work.

NOTE:To correctly enter a WikiName - your own or someone else's - be sure to include the Main web name in front of the Wiki username, followed by a period, and no spaces. Ex:

Main.WikiUsername or %MAINWEB%.WikiUsername

This points WikiUser to the TWiki.Main web, where user registration pages are stored, no matter which web it's entered in. Without the web prefix, the name appears as a NewTopic? everywhere but in the Main web.

Changing Passwords

Change and reset passwords using forms on regular pages. Use TWikiAccessControl to restrict use as required.

TWiki Access Control

Restricting read and write access to topics and webs, by Users and groups

TWikiAccessControl allows you restrict access to single topics and entire webs, by individual user and by user Groups, in three areas: view; edit & attach; and rename/move/delete. Access control, combined with TWikiUserAuthentication, lets you easily create and manage an extremely flexible, fine-grained privilege system.

An Important Control Consideration

Open, freeform editing is the essence of WikiCulture - what makes TWiki different and often more effective than other collaboration tools. For that reason, it is strongly recommended that decisions to restrict read or write access to a web or a topic are made with care - the more restrictions, the less Wiki in the mix. Experience shows that unrestricted write access works very well because:

Peer influence is enough to ensure that only relevant content is posted.

Peer editing - the ability for anyone to rearrange all content on a page - keeps topics focussed.

Authentication vs. Access Control

Access control: Restrict access to content based on users and groups once a user is identified.

Users and Groups

Access control is based on the familiar concept of Users and Groups. Users are defined by their WikiNames. They can then be organized in unlimited combinations by inclusion in one or more user Groups. For convenience, Groups can also be included in other Groups.

Managing Users

A user can create an account in TWikiRegistration. The following actions are performed:

WikiName and encrypted password are recorded in .htpasswd if authentication is enabled.

A confirmation e-mail is sent to the user.

A user home page with the WikiName of the user is created in the Main web.

Users can be authenticated using Basic Authentication (htaccess) or SSL (secure server). In either case, TWikiUserAuthentication is required in order to track user identities, and use User and Group access control.

The default visitor name is TWikiGuest. This is the non-authenticated user.

Managing Groups

Groups are defined by group topics created in the Main web, like the TWikiAdminGroup. To create a new group:

EditTWikiGroups by entering a new topic with a name that ends in Group. Example:

SomeGroup

Set Preferences for two Variables in the new group topic:

Set GROUP = < list of Users and/or Groups >

Set ALLOWTOPICCHANGE = < list of Users and/or Groups >

The GROUP variable is a comma-separated list of Users and/or other Groups. Example:

Set GROUP = Main.SomeUser, Main.OtherUser, Main.SomeGroup

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. (This prevents Users not in the Group from editing the topic to give themselves or others access. For example, for the TWikiAdminGroup topic write:

Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup

Restricting Write Access

You can define who is allowed to make changes to a web or a topic.

Deny Editing by Topic

Denying editing of a topic also restricts file attachment; both privileges are assigned together.

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

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, with a comma-delimited list. Example:

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.

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

Restricting Read Access

You can define who is allowed to see a web.

Deny Viewing by Topic

Technically it is possible to restrict read access to an individual topic based on DENYTOPICVIEW / ALLOWTOPICVIEW preferences variables, provided that the view script is authenticated. However this setup is not recommended since all content is searchable within a web - a search will turn up view restricted topics.

Deny Viewing by Web

You can define restrictions of who is allowed to view a TWiki web. You can restrict access to certain webs to selected Users and Groups, by:

obfuscating webs: Insecure but handy method to hide new webs until content is ready for deployment.

authenticating all webs and restricting selected webs: Topic access in all webs is authenticated, and selected webs have restricted access.

authenticating and restricting selected webs only: Provide unrestricted viewing access to open webs, with authentication and restriction only on selected webs.

Obfuscate Webs

The idea is to keep a web hidden by not publishing its URL and by preventing the all webs search option from accessing obfuscated webs. Do so by enabling the NOSEARCHALL variable in WebPreferences:

Set NOSEARCHALL = on

This setup can be useful to hide a new web until content its ready for deployment.

Obfuscating webs is insecure, as anyone who knows the URL can access the web.

Authenticate all Webs and Restrict Selected Webs

Use the following setup to authenticate users for topic viewing in all webs and to restrict access to selected webs:

Restrict view access to selected Users and Groups. Set one or both of these variables in its WebPreferences topic:

Set DENYWEBVIEW = < list of Users and Groups >

Set ALLOWWEBVIEW = < list of Users and Groups >

Note:DENYWEBVIEW is evaluated before ALLOWWEBVIEW. Access is denied if the authenticated person is in the DENYWEBVIEW list, or not in the ALLOWWEBVIEW list. Access is granted in case DENYWEBVIEW and ALLOWWEBVIEW is not defined.

Hide the web from an "all webs" search. Enable this restriction with the NOSEARCHALL variable in its WebPreferences topic:

Set NOSEARCHALL = on

Addview to the list of authenticated scripts in the .htaccess file.

This method only works if the view script is authenticated, which means that all Users have to login, even for read-only access. (An open guest account, like TWikiGuest, can get around this, allowing anyone to login to a common account with, for example, view-only access for public webs.) TWikiInstallationGuide has more on Basic Authentication, using the .htaccess file.

Authenticate and Restricting Selected Webs Only

Use the following setup to provide unrestricted viewing access to open webs, with authentication only on selected webs:

Restrict view access to selected Users and Groups. Set one or both of these variables in its WebPreferences topic:

Set DENYWEBVIEW = < list of Users and Groups >

Set ALLOWWEBVIEW = < list of Users and Groups >

Note:DENYWEBVIEW is evaluated before ALLOWWEBVIEW. Access is denied if the authenticated person is in the DENYWEBVIEW list, or not in the ALLOWWEBVIEW list. Access is granted in case DENYWEBVIEW and ALLOWWEBVIEW is not defined.

Hide the web from an "all webs" search. Enable this restriction with the NOSEARCHALL variable in its WebPreferences topic:

Set NOSEARCHALL = on

Enable the $doRememberRemoteUser flag in lib/TWiki.cfg as described in TWikiUserAuthentication. TWiki will now remember the IP address of an authenticated user.

Copy the view script to viewauth (or better, create a symbolic link)

Addviewauth to the list of authenticated scripts in the .htaccess file. The view script should not be listed in the .htaccess file.

When a user accesses a web where you enabled view restriction, TWiki will redirect from the view script to the viewauth script once (this happens only if the user has never edited a topic). Doing so will ask for authentication. The viewauth script shows the requested topic if the user could log on and if the user is authorized to see that web.

Authenticating webs is not very secure, as there is a way to circumvent the read access restriction. It can be useful in certain situations - for example, to simplify site organization and clutter, by hiding low traffic webs - but is not recommended for securing sensitive content.

Hiding Control Settings

To hide access control settings from normal browser viewing, place them in comment markers.

The SuperAdminGroup

By mistyping a user or group name in the ALLOWTOPICCHANGE setting, it's possible to lock a topic so that no-one can edit it from a browser. To avoid this, you can create Web-based superusers:

Set the $superAdminGroup variable in lib/TWiki.cfg to the name of a group of Users who are always allowed to edit/view topics.

TWiki Text Formatting

Working in TWiki is as easy as typing in text - exactly like email. You don't need to know HTML, though you can use it if you prefer. Links to topics are created automatically when you enter WikiWords. And TWiki shorthand gives you all the power of HTML with a simple coding system that takes no time to learn. It's all laid out below - refer back to this page in a pop-up window from the Edit screen.

TWiki Editing Shorthand

Formatting Command:

Example: You write:

You get:

Paragraphs:
Blank lines will create new paragraphs.

1st paragraph
2nd paragraph

1st paragraph

2nd paragraph

Headings:
At least three dashes at the beginning of a line, followed by plus signs and the heading text. One plus creates a level 1 heading (most important), two pluses a level 2 heading; the maximum is level 6. Note: A Table of Content can be created automatically with the %TOC% variable, see TWikiVariables. Any heading text after !! is excluded from the TOC; for example, write ---+!! text if you do not want to list a header in the TOC.

---++ Sushi
---+++ Maguro

Sushi

Maguro

Bold Text:
Words get bold by enclosing them in * asterisks.

*Bold*

Bold

Italic Text:
Words get italic by enclosing them in _ underscores.

_Italic_

Italic

Bold Italic:
Words get _bold italic by enclosing them in _ double-underscores.

__Bold italic__

Bold italic

Fixed Font:
Words get shown in fixed font by enclosing them in = equal signs.

Note: Make sure there is no space between the text and the bold, italic, or other indicators (* _ __ = ==).

_This works_,
_this not _

This works,
_this not _

Verbatim Mode:
Surround code excerpts and other formatted text with <verbatim> and </verbatim> tags. Note: Use <pre> and </pre> tags instead if you want that HTML code is interpreted. Note: Each tag must be on a line by itself.

Definition List:
Three spaces, a dollar sign, the term, a colon, a space, followed by the definition.

$ Sushi: Japan
$ Dim Sum: S.F.

Sushi

Japan

Dim Sum

S.F.

Table:
Any number of lines of text. Each line is one row of the table consisting of one or more cells. Each cell starts and ends with a vertical bar '|'. Any spaces at the beginning of a line are ignored.Notes:•
| *bold* | cells are displayed as table headers.•
| center-spaced | cells are displayed center aligned.•
| right-spaced | cells are displayed right aligned.•
| 2 colspan || cells are displayed as multi-span columns (i.e., a cell with no text spans a column).•
|^| cells with a caret indicate follow-up rows of multi-span rows (this functionality is provided by TablePlugin).•
If a row contains a large amount of text, and you want it to be more readable while editing the table, split the row into multiple text lines by ending each line with a backslash character '\'.•
Table cells wrap automatically as determined by the browser.

WikiWord Links:
CapitalizedWordsStuckTogether (or WikiWords) will produce a link automatically. Note: In case you want to link to a topic in a different TWiki web write Otherweb.TopicName. (The link label is the the name of the web in case the is WebHome, else it is the topic name)

Forced Links:
You can create a forced internal link by enclosing words in double square brackets.
Note: Text within the brackets may contain optional spaces; the topic name is formed by capitalizing the initial letter and by removing the spaces; for example, [[text formatting FAQ]] links to topic TextFormattingFAQ. You can also refer to a different web and use anchors.
Note: To "escape" double square brackets that would otherwise be a correct link, prefix the leading left square brackets with an exclamation point, that is, begin with ![[....

Specific Links:
Create a link where you can specify the link text and the link reference separately, using nested square brackets like [[reference][text]]. Internal link references (e.g. WikiSyntax) and external link references (e.g. http://TWiki.org/) are supported.
Note: The same Forced Links rules apply for internal link references.
Note: For external link references, you can simply use a space instead of ][ to separate the link URL from the descriptive text.
Note: Anchor names can be added as well, like [[WebHome#MyAnchor][go home]] and [[http://gnu.org/#Action][GNU Action]].

Anchors:
You can define a link reference inside a TWiki topic (called an anchor name) and link to that. To define an anchor write #AnchorName at the beginning of a line. The anchor name must be a WikiWord. To link to an anchor name use the [[MyTopic#MyAnchor]] syntax. You can omit the topic name if you want to link within the same topic.

Prevent a Link:
Prevent a WikiWord from being linked by prepending it with an exclamation point.

!SunOS

SunOS

Disable Links:
You can disable automatic linking of WikiWords by surrounding text with <noautolink> and </noautolink> tags.
Note: Each tag must be on a line by itself.
Note: This also works for TWiki tables, but only if you add a blank line between the end of the table and the closing </noautolink> tag (known issue of the TablePlugin).

<noautolink>
RedHat &
SuSE
</noautolink>

RedHat &
SuSE

Mailto: Links:
To create 'mailto:' links that have more descriptive link text, specify subject lines or message bodies, or omit the email address, you can write [[mailto:user@domain descriptive text]].

Using HTML

You can use just about any HTML tag without a problem - however, there are a few usability and technical considerations to keep in mind.

HTML and TWiki Usability

TIP: On collaboration pages, it's preferable NOT to use HTML, and to use TWiki shorthand instead - this keeps the text uncluttered and easy to edit.

NOTE: TWiki is designed to work with a wide range of browsers and computer platforms, holding to HTML 4.0 and XHTML 1.0 compatibility in the standard installation - adding raw HTML, particularly browser-specific tags (or any other mark-up that doesn't degrade well) will reduce compatibility.

TWiki HTML Rendering

If you need to save HTML frequently, you may want to check out TWiki:Plugins/GenHTMLAddon - it will "generate a directory containing rendered versions of a set of TWiki pages together with any attached files."

NOTE: The opening and closing angle brackets - <...> - of an HTML tag must be on the same line, or the tag will be broken.

This feature allows you to enter an unclosed angle bracket - as a greater than or less than symbol - and have it automatically rendered as if you had entered its HTML character, &lt;, ex: a < b

If you're pasting in preformatted HTML text and notice problems, check the file in a text processor with no text wrap. Also, save without hard line breaks on text wrap, in your HTML editing program.

TWiki and JavaScript

You can use JavaScript for your TWiki applications. Since TWiki rendering might interfere with JavaScript code you need to escape it with HTML comments and <pre> tags:

Hyperlinks

Being able to create links without any formatting required is a core TWiki feature, made possible with WikiWords. New TWiki linking rules are a simple extension of the syntax that provide a new set of flexible options.

Internal Links

GoodStyle is a WikiWord that links to the GoodStyle topic located in the current TWiki web.

NotExistingYet? is a topic waiting to be written. Create the topic by clicking on the ?. (Try clicking, but then, Cancel - creating the topic would wreck this example!)

You can also write [[http://yahoo.com Yahoo home page]] as an easier way of doing external links with descriptive text for the link, such as Yahoo home page.

TWiki Variables

Variables are names that are enclosed in percent signs % that are expanded on the fly.

%TOC% : Automatically generates a table of contents based on headings in a topic - see the top of this page for an example.

%WEB% : The current web, is TWiki.

%TOPIC% : The current topic name, is TextFormattingRules.

%ATTACHURL% : The attachment URL of the current topic. Example usage: If you attach a file to a topic you can refer to it as %ATTACHURL%/image.gif to show the URL of the file or the image in your text.

%INCLUDE{"SomeTopic"}% : Server side include, includes another topic. The current TWiki web is the default web. Example: %INCLUDE{"TWiki.SiteMap"}%

%SEARCH{"sushi"}% : Inline search showing the search result embedded in a topic. FormattedSearch gives you control over formatting, used to create web-based applications.

To "escape" a variable, prefix it with an exclamation point. Write: !%SOMEVARIABLE% to get: %SOMEVARIABLE%.

TWikiPlugin Formatting Extensions

Plugins provide additional text formatting capabilities and can extend the functionality of TWiki into many other areas. For example, the optional SpreadSheetPlugin lets you create a spreadsheet with the same basic notation used in TWiki tables.

Available Plugins are located in the Plugins web on TWiki.org. Currently enabled plugins on this TWiki installation, as listed by %PLUGINDESCRIPTIONS%:

DefaultPlugin: This plugin can be used to specify some simple custom rendering rules. It also renders depreciated *_text_* as bold italic text.

Common Editing Errors

TWiki formatting rules are fairly simple to use and quick to type. However, there are some things to watch out for, taken from the TextFormattingFAQ:

Q: Text enclosed in angle brackets like <filename> is not displayed. How can I show it as it is?

A: The '<' and '>' characters have a special meaning in HTML, they define HTML tags. You need to escape them, so write '&lt;' instead of '<', and '&gt;' instead of '>'. Example: Type 'prog &lt;filename&gt;' to get 'prog <filename>'.

TWiki Variables

Special text strings expand on the fly to display user data or system info

TWikiVariables are text strings - %VARIABLE% - that expand into content whenever a page is rendered for viewing. VARIABLES are replaced by data, either user-entered or automatically generated by TWiki (like the date, or the current username). There are predefined variables, and Preference variables that you can configure. You can also define custom variables, with new names and values.

Notes:

To leave a variable unexpanded, precede it with an exclamation point, e.g. type !%TOPIC% to get %TOPIC%.

Variables are expanded relative to the topic they are used in, not the topic they are defined in.

Predefined Variables

Most predefined variables return values that were either set in the lib/twiki.cfg file, when TWiki was installed, or taken from server info (like current username, or date and time). Many of the variables let you format the appearance of the display results.

Take the time to thoroughly read through ALL preference variables. If you actively configure your site, review variables periodically. They cover a wide range of functions, and it can be easy to miss the one perfect variable for something you have in mind. For example, see %INCLUDINGTOPIC%, %INCLUDE%, and the mighty %SEARCH%.

Sort the results of search by the topic names, topic creation time, last modified time, last editor, or named field of TWikiForms. The sorting is done web by web; in case you want to sort across webs, create a formatted table and sort it with TablePlugin's initsort

Sort by topic name

limit="all"limit="16"

Limit the number of results returned. This is done after sorting if order is specified

SPACEDTOPIC -- topic name, spaced and encoded

STARTINCLUDE -- start position of topic text if included

If present in included topic, start to include text from this location up to the end, or up to the location of the %STOPINCLUDE% variable. A normal view of the topic shows everyting exept the %STARTINCLUDE% variable itself.

TOC -- table of contents of current topic

TOC{"Topic"} -- table of contents

Syntax: %TOC{"SomeTopic" ...}%

Table of Contents. Shows a TOC that is generated automatically based on headings of a topic. Headings in WikiSyntax ("---++ text") and HTML ("<h2>text</h2>") are taken into account. Any heading text after "!!" is excluded from the TOC; for example, write "---+!! text" if you do not want to list a header in the TOC

WEB -- name of current web

WEBLIST{"format"} -- index of all webs

List of all webs. Hidden webs are excluded, e.g. webs with a NOSEARCHALL=on preference variable. The "format" defines the format of one web item. The $name variable gets expanded to the name of the web, $qname gets expanded to double quoted name, $marker to marker where web matches selection.

List of users and groups who are allowed to change topics in the TWiki web. (More in TWikiAccessControl)

%ALLOWWEBRENAME%

WL

List of users and groups who are allowed to rename topics in the TWiki web. (More in TWikiAccessControl)

%ATTACHLINKBOX%

SL , UL

Default state of the link check box in the attach file page. Check box is initially checked if value is set to CHECKED , unchecked if empty. If checked, a link is created to the attached file at the end of the topic. Value is:

%DENYTOPICCHANGE%

(any topic)

List of users and groups who are not allowed to change the current topic. (More in TWikiAccessControl)

%DENYTOPICCHANGE%

%DENYTOPICRENAME%

(any topic)

List of users and groups who are not allowed to rename the current topic. (More in TWikiAccessControl)

%DENYTOPICRENAME%

%DENYWEBCHANGE%

WL

List of users and groups who are not allowed to change topics in the TWiki web. (More in TWikiAccessControl)

%DENYWEBRENAME%

WL

List of users and groups who are not allowed to rename topics in the TWiki web. (More in TWikiAccessControl)

%DONTNOTIFYCHECKBOX%

SL , UL

Default state of the "Minor Changes, Don't Notify" (DontNotify) check box in preview. Check box is initially checked if Set DONTNOTIFYCHECKBOX = checked="checked", or unchecked if empty. Value is:

Exclude web from a web="all" search (set variable to on for hidden webs)

%RELEASEEDITLOCKCHECKBOX%

SL , UL

Default state of the "Release edit lock" (UnlockTopic) check box in preview. Checkbox is initially checked if Set RELEASEEDITLOCKCHECKBOX = checked="checked", or unchecked if empty. If checked, make sure to click on Edit to do more changes; do not go back in your browser to the edit page, or you risk that someone else will edit the topic at the same time! Value is:

Note: There are some more useful variables defined in the TWikiPreferences like %BR% for line break, colors like %RED% for colored text and small icons like %H% for a Help icon.

Setting Preferences

The syntax for Preferences Variables is the same anywhere in TWiki (on its own TWiki bullet line, including nested bullets): [multiple of 3 spaces] * [space] Set [space] VARIABLENAME [space] = [value]Examples:

Set VARIABLENAME = value

Set VARIABLENAME = value

Creating Custom Variables

You can add your own Preference Variables for us across an entire site or a single web, using the standard Preferences syntax. Whatever you include in your Variable will be expanded on display, exactly as if it had been entered directly. You can place formatted text, page links, image paths.

Example: Create a custom logo variable the TWiki web

To place a logo anywhere in a web by typing %MYLOGO%, define the Variable on the web's WebPreferences page, and upload a logo file, ex: mylogo.gif. You can upload by attaching the file to WebPreferences, or, to avoid clutter, to any other topic in the same web, ex: LogoTopic:

File Attachments

Each topic can have one or more files of any type attached to it by using the Attach screen to upload (or download) files from your local PC. Attachments are stored under revision control: uploads are automatically backed up; all previous versions of a modified file can be retrieved.

What Are Attachments Good For?

File Attachments can be used to create powerful customized groupware solutions, like file sharing and document management systems, and quick Web page authoring.

Document Management System

You can use Attachments to store and retrieve documents (in any format, with associated graphics, and other media files); attach documents to specific TWiki topics; collaborate on documents with full revision control; distribute documents on a need-to-know basis using web and topic-level access control; create a central reference library that's easy to share with an user group spread around the world.

File Sharing

For file sharing, FileAttachments on a series of topics can be used to quickly create a well-documented, categorized digital download center for all types of files: documents; graphics and other media; drivers and patches; applications; anything you can safely upload!

Web Authoring

Through your Web browser, you can easily upload graphics (or sound files, or anything else you want to link to on a page) and place them on a single page, or use them across a web, or site-wide.

NOTE: You can also add graphics - any files - directly, typically by FTP upload. This requires FTP access, and may be more convenient if you have a large number of files to load. FTP-ed files can't be managed using browser-based Attachment controls. You can use your browser to create TWikiVariables shortcuts, like this %H% = .

Uploading Files

Click on the Attach link at the bottom of the page. The Attach screen lets you browse for a file, add a comment, and upload it. The uploaded file will show up in the File Attachment table.

NOTE: The topic must already exist. It is a two step process if you want to attach a file to a non-existing topic; first create the topic, then add the file attachment.

Any type of file can be uploaded. Some files that might pose a security risk are renamed, ex: *.php files are renamed to *.php.txt so that no one can place code that would be read in a .php file.

The previous upload path is retained for convenience. In case you make some changes to the local file and want to upload it, again you can copy the previous upload path into the Local file field.

TWiki can limit the file size. This is defined by the %ATTACHFILESIZELIMIT% variable of the TWikiPreferences, currently set at 10000 KB.

It's not recommended to upload files greater than a few hundred K through a browser. Large files can be extremely slow-loading, and often time out. Use an FTP site for large file uploads.

The first table is a list of all attachments, including their attributes. An h means the attachment is hidden, it isn't listed when viewing a topic.

The second table is all the versions of the attachment. Click on View to see that version. If it's the most recent version, you'll be taken to an URL that always displays the latest version, which is usually what you want.

To change the comment on an attachment, enter a new comment and then click Change properties. Note that the comment listed against the specific version will not change, however the comment displayed when viewing the topic does change.

To hide/unhide an attachment, enable the Hide file checkbox, then click Change properties.

Known Issues

Unlike topics, attachments are not locked during editing. As a workaround, you can change the comment to indicate an attachment file is being worked on - the comment on the specific version isn't lost, it's there when you list all versions of the attachment.

TWiki Forms

Overview

By adding form-based input to freeform content, you can structure topics with unlimited, easily searchable categories. When forms are enabled for a web and selected in a topic, a single form appears in edit mode, and the contents are rendered as a table when viewed on the display page. You can define unlimited forms per web. For each topic, you can select a template if more than one is defined, or remove forms entirely. Form input values are stored as TWikiMetaData; all data is saved.

Form Templates replace TWikiCategoryTables from the 01-Dec-2000 version of TWiki. - see #FormsVsCategoryTables

Defining a Form Template

A Form Template is simply a page containing your form, defined as a table where each row is one form field.

Form Template Elements

form template - a set of fields defining a form (replaces category table definition)

Implementation Notes: This format allows you to define field items with or without WikiNames, depending on your needs.

Topics can be protected in the usual manner, using TWikiAccessControl, to limit who can change the form template and/or individual value lists.

[[...]] links can be used to force a link (at present, the [[...][...]] format is not supported).

The Tooltip message column is used as a tooltip for the field name (only if field name is a WikiName) - you only see the tooltip In edit.

The first item in the list is the default item. Alternative initial values can be set in a topic template, like WebTopicEditTemplate, with field=value, or, for checkboxes, field=1.

The topic definition is not read when a topic is viewed.

Enabling Forms by Web

Forms are enabled on a per web basis. The WEBFORMS variable in WebPreferences is optional and defines a list of possible form templates. Example:

Set WEBFORMS = BugForm, FeatureForm, BookLoanForm

With WEBFORMS enabled, an extra button is added to the edit view. If the topic doesn't have a Form, an Add Form button appears at the end of the topic. If a Form is present, a Change button appears in the top row of the Form. The buttons open a screen that enables selection of a form specified in WEBFORMS, or the No form option.

Including Forms in New Topics

A default Form Template (new topics get this default form) can be provided by creating the WebTopicEditTemplate topic in a web and adding a form to it. Initial Form values can be set there.

Additionally a new topic can be given a Form using the formtemplate parameter in the URL. Initial values can then be provided in the URLs or as form values:

other than checkboxes: name, ex: ?BugPriority=1

checkbox: namevalue=1, ex: ?ColorRed=1.
Boxes with a tick must be specified.

Setting Up Multiple Form Options

The optional WEBFORMS variable defines alternative forms that can be selected by pressing Change in edit mode.

A topic template can use any form.

New topics with a form are created by simple HTML forms asking for a topic name. For example, you can have a SubmitExpenseReport topic where you can create new expense reports, a SubmitVacationRequest topic, and so on. These can specify the required template topic with its associated form.

Form Data Storage

The form topic name, fields and values are stored as TWikiMetaData - the order of the field/value pairs is the same as in the template.

Importing Category Table Data

On upgrading from the previous TWiki, a Form Template topic has to be built for each web that used a Category Table, recreating the fields and values from the old twikicatitems.tmpl. The replacement Form Template must be set as the first item in the WebPreferences variable WEBFORMS. If missing, pages will display, but attempting to edit results in an error message.

The new Form Template system should work with old Category Table data with no special conversion. Data is assigned to Meta variables the first time an imported topic is edited and saved in the new system.

NOTE: If things aren't working correctly, there may be useful entries in data/warning.txt.

Using Forms For Settings

Example process to change your WebPreferences to use forms instead of {3 spaces}* Set statements:

Edit WebPreferences, jump straight down to the form ignoring all the textarea stuff, and set as you like

if everything works as you like it, you can delete the Set statements (the form overrides set if they are both used).

Notes:

If it isn't working, double check that the S attribute has been specified (S for Setting).
If you change the form, the changes will not take affect until you edit and save the preferences' topics again.

A possibly unwanted side effect for using forms for the SKINS setting in their personal user topic: because the User Preferences are final you can't have different skins for different webs as the user's setting always wins. A workaround is to simply omit SKIN in the form.

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

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.

Legend:• script refers to the script name, e.g view, edit• Script refers to the same, but with the first character capitalized, e.g View• skin refers to the skin name, e.g dragon, pattern• Skin refers to the same, but with the first character capitalized, e.g Dragon• %WEB% refers to the current web

Additionally (and primarily for use in %TMPL:INCLUDE{}%) the template name may be a wiki topic name, specified as Web.Topic, in which case the search is:

All template topics are located in the TWiki web. The WebTopicEditTemplate can be overloaded. When you create a new topic, TWiki locates a topic to use as a content template according to the following search order:

A topic name specified by the templatetopic CGI parameter.

WebTopicEditTemplate in the current web

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:

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:

New example topic:
(date format is YYYYxMMxDD)

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:

If set, TWiki will complain if a topic of the same name already exists

templatetopic

The name of the template topic, e.g. topic used to copy the initial content

topicparent

Sets the parent topic

TopicClassification

Assuming the template topic has a form with a field called "TopicClassification", it will set the value of the field

contenttype

Optional parameter that defines the application type to write into the CGI header. Defaults to text/html. May be used to invoke alternative client applications

anyname

Any parameter can passed to the new topic; if the template topic contains %URLPARAM{"anyname"}%, it will be replaced by its value

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"}%

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.

TWiki Skins

Overview

Skins are customized TWikiTemplates files. You can use skins to change the look of a TWiki topic, for example, the layout of the header and footer. Rendered text between header and footer does not change. You can also use skins to define an alternate view, like a view optimized for printing.

Defining Skins

Skin files are located in the twiki/templates directory and are named with the syntax: <scriptname>.<skin>.tmpl. For example, the Printable skin for the view template is view.print.tmpl.

Use the existing TWikiTemplates (like view.tmpl) or skin files as a base for your own skin, name it for example view.myskin.tmpl.

Broadcast message at the beginning of your view template, can be used to alert users of scheduled downtimes; is set in TWikiPreferences

The "Go" Box and Navigation Box

The %WEBTOPICLIST% includes a "Go" box to jump to a topic. The box also understand URLs, e.g. you can type http://www.google.com/ to jump to an external web site. The feature is handy if you build a skin that has a select box of frequently used links, like Intranet home, employee database, sales database and such. A little JavaScript gets into action on the onSelect method of the select tag to fill the selected URL into the "Go" box field, then submits the form.

Here is an example form that has a select box and the "Go" box for illustration purposes. You need to have JavaScript enabled for this to work:

Using Cascading Style Sheets

Although work is underway at TWiki:Codev.CssClassNames, the regular templates files currently do not use style sheets. Many skin developers, however, choose to use them; it helps in separating style from content.

Example: To use a style sheet for the broadcast message, add this to view.myskin.tmpl:

Then add a div tag to the %BROADCASTMESSAGE% variable located after the #PageTop anchor or after the opening form tag:

<div class="broadcastmessage"> %BROADCASTMESSAGE% </div>

Attachment Tables

Controlling the look and feel of attachment tables is a little bit more complex than for the rest of a skin. By default the attachment table is a standard TWiki table, and the look is controlled in the same ay as other tables. In a very few cases you may want to change the content of the table as well.

The format of standard attachment tables is defined through the use of special TWiki template macros which by default are defined in the templates/twiki.tmpl template using the %TMPL:DEF macro syntax described in TWikiTemplates. These macros are:

The attributes of the file as seen on the upload screen e.g "h" for a hidden file

Note: it is easy to change the look and feel for an entire site by editing the twiki.tmpl template file. However, to simplify upgrading, you should avoid doing this. Instead, write a skin-specific template file e.g. attach.myskin.tmpl and use %TMPL:INCLUDE{attach.myskin.tmpl}% to include it in each of your skin files. As long as it it included after twiki.tmpl, your macro definitions will override the defaults defined there.

TWiki Formatted Search Results

Inline search feature allows flexible formatting of search result

The %SEARCH{...}% variable documented in TWikiVariables has a fixed format for the search result, that is, a table consisting of topic names and topic summaries. Use the format="..." parameter to specify a customized format of the search result. The string of the format parameter is typically a bullet list or table row containing variables (such as %SEARCH{ "food" format="| $topic | $summary |" }%).

Syntax

Two parameters can be used to specify a customized search result:

1. header="..." parameter

Use the header parameter to specify the header of a search result. It should correspond to the format of the format parameter. This parameter is optional. Example: header="| *Topic:* | *Summary:* |"

2. format="..." parameter

Use the format parameter to specify the format of one search hit.
Example: format="| $topic | $summary |"

Formatted topic text. In case of a multiple="on" search, it is the line found for each search hit.

$locked

LOCKED flag (if any)

$date

Time stamp of last topic update, e.g. 15 Sep 2019 - 07:35

$isodate

Time stamp of last topic update, e.g. 2019-09-15T07:35Z

$rev

Number of last topic revision, e.g. 1.4

$username

Login name of last topic update, e.g. jsmith

$wikiname

Wiki user name of last topic update, e.g. JohnSmith

$wikiusername

Wiki user name of last topic update, like Main.JohnSmith

$createdate

Time stamp of topic revision 1.1

$createusername

Login name of topic revision 1.1, e.g. jsmith

$createwikiname

Wiki user name of topic revision 1.1, e.g. JohnSmith

$createwikiusername

Wiki user name of topic revision 1.1, e.g. Main.JohnSmith

$summary

Topic summary

$formname

The name of the form attached to the topic; empty if none

$formfield(name)

The field value of a form field; for example, $formfield(TopicClassification) would get expanded to PublicFAQ. This applies only to topics that have a TWikiForm

$formfield(name, 10)

Form field value, "- " hyphenated each 10 characters

$formfield(name, 20, -<br />)

Form field value, hyphenated each 20 characters with separator "-<br />"

$formfield(name, 30, ...)

Form field value, shortended to 30 characters with "..." indication

$pattern(reg-exp)

A regular expression pattern to extract some text from a topic (does not search meta data; use $formfield instead). In case of a multiple="on" search, the pattern is applied to the line found in each search hit.• Specify a RegularExpression that covers the whole text (topic or line), which typically starts with .*, and must end in .*• Put text you want to keep in parenthesis, like $pattern(.*?(from here.*?to here).*)• Example: $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the email address from a bullet of format * Email: ...• This example has non-greedy .*? patterns to scan for the first occurance of the Email bullet; use greedy .* patterns to scan for the last occurance • Limitation: Do not use .*) inside the pattern, e.g. $pattern(.*foo(.*)bar.*) does not work, but $pattern(.*foo(.*?)bar.*) does • Note: Make sure that the integrity of a web page is not compromised; for example, if you include an HTML table make sure to include everything including the table end tag

$n or $n()

New line

$nop or $nop()

Is a "no operation". This variable gets removed; useful for nested search

Everybody can edit any page, this is scary. Doesn't that lead to chaos? Answer...

Nested Search

Search can be nested. For example, search for some topics, then form a new search for each topic found in the first search. The idea is to build the nested search string using a formatted search in the first search.

Here is an example. Let's search for all topics that contain the word "culture" (first search), and let's find out where each topic found is linked from (second search).

Now let's nest the two. We need to escape the second search, e.g. the first search will build a valid second search string. Note that we escape the second search so that it does not get evaluated prematurely by the first search:

Note: Nested search can be slow, especially if you nest more then 3 times. Nesting is limited to 16 levels. For each new nesting level you need to "escape the escapes", e.g. write $dollarpercntSEARCH{ for level three, $dollardollarpercntSEARCH{ for level four, etc.

Search with conditional output

A regular expression search is flexible, but there are limitations. For example, you cannot show all topics that are up to exactly one week old, or create a report that shows all records with invalid form fields or fields within a certain range, etc. You need some additional logic to format output based on a condition:

Specify a search which returns more hits then you need

For each search hit apply a spreadsheet formula to determine if the hit is needed

TWiki Meta Data

Overview

TWikiMetaData uses META variables to store topic data that's separate from the main free-form content. This includes program-generated info like FileAttachment and topic movement data, and user-defined TWikiForms info. Use META variables to format and display Meta Data.

Meta Data Syntax

Format is the same as in TWikiVariables, except all fields have a key.

%META:<type>{key1="value1" key2="value2" ...}%

Order of fields within the meta variables is not defined, except that if there is a field with key name, this appears first for easier searching (note the order of the variables themselves is defined).

Each meta variable is on one line.

\n (new line) is represented in values by %_N_ and " (double-quotes) by %_Q_%.

META:TOPICMOVED

This is optional, exists if topic has ever been moved. If a topic is moved more than once, only the most recent META:TOPICMOVED meta variable exists in the topic, older ones are to be found in the rcs history.

META:TOPICPARENT

The topic from which this was created, WebHome if done from Go, othewise topic where ? or form used. Normally just topic, but is full web.topic format if parent is in a different Web. Renaming a Web will then only break a few of these references or they can be scanned and fixed.

Recommended Sequence

There is no absolute need for Meta Data variables to be listed in a specific order within a topic, but it makes sense to do so a couple of good reasons:

form fields remain in the order they are defined

the diff function output appears in a logical order

The recommended sequence is:

META:TOPICINFO

META:TOPICPARENT (optional)

text of topic

META:TOPICMOVED (optional)

META:FILEATTACHMENT (0 or more entries)

META:FORM (optional)

META:FIELD (0 or more entries; FORM required)

Viewing Meta Data in Page Source

When viewing a topic the Raw Text link can be clicked to show the text of a topic (i.e., as seen when editing). This is done by adding raw=on to URL. raw=debug shows the meta data as well as the topic data, ex: debug view for this topic

Rendering Meta Data

Meta Data is rendered with the %META% variable. This is mostly used in the view, preview and edit scripts.

Note: Rendering meta data is currently not supported in topic text. As a workaround, use FormattedSearch on the current topic only to render form fields.

Show form field value. Parameter: name="field_name". Example:%META{ "formfield" name="TopicClassification" }%

%META{"attachments"}%

Show attachments, except for hidden ones. Options: all="on": Show all attachments, including hidden ones.

%META{"moved"}%

Details of any topic moves.

%META{"parent"}%

Show topic parent. Options: dontrecurse="on": By default recurses up tree, at some cost. nowebhome="on": Suppress WebHome. prefix="...": Prefix for parents, only if there are parents, default "". suffix="...": Suffix, only appears if there are parents, default "". separator="...": Separator between parents, default is " > ".

Known Issues

At present, there is no Meta Data support for Plugins. However, the format is readily extendable and the Meta.pm code that supports the format needs only minor alteration.

TWiki Plugins

Overview

You can add Plugins to extend TWiki's functionality, without altering the core program code. A plug-in approach lets you:

add virtually unlimited features while keeping the main TWiki code compact and efficient;

heavily customize an installation and still do clean updates to new versions of TWiki;

rapidly develop new TWiki functions in Perl using the Plugin API.

Everything to do with TWiki Plugins - demos, new releases, downloads, development, general discussion - is available at TWiki.org, in the TWiki:Plugins web.

Preinstalled Plugins

TWiki comes with a set of Plugins as part of the standard installation.

DefaultPlugin: Optionally handles some legacy variables from older versions of TWiki. You can control this option from TWikiPreferences. (Perl programmers can also add rules for simple custom processing.)

EmptyPlugin: Is a fully functional module, minus active code; it does nothing and serves as a template for new Plugin development

CommentPlugin: Allows users to quickly post comments to a page without an edit/preview/save cycle.

InterwikiPlugin: Use it for shorthand linking to remote sites, ex: TWiki:Plugins expands to TWiki:Plugins on TWiki.org. You can edit the predefined set of of Wiki-related sites, and add your own

TablePlugin: Control attributes of tables and sorting of table columns

Installing Plugins

Each TWikiPlugin comes with full documentation: step-by-step installation instructions, a detailed description of any special requirements, version details, and a working example for testing.

Most Plugins can be installed in three easy steps, with no programming skills required:

Download the zip file containing the Plugin, documentation, and any other required files, from TWiki:Plugins.

Distribute the files to their proper locations - unzip the zip archive in your TWiki installation directory - if have a standard TWiki installation, this will distribute automatically. Otherwise, place the files according to the directory paths listed on the Plugin top in TWiki:Plugins.

Check the demo example on the Plugin topic: if it's working, the installation was fine!

Special Requests: Some Plugins need certain Perl modules to be preinstalled on the host system. Plugins may also use other resources, like graphics, other modules, applications, templates. In these cases, detailed instructions are in the Plugin documentation.

Each Plugin has a standard release page, located in the TWiki:Plugins web at TWiki.org. In addition to the documentation topic (SomePlugin), there's a separate development page.

Doc page: Read all available info about the Plugin; download the attached distribution files.

Checking that Plugins are Working on a Live Server

A Note on Plugin Performance

The performance of the system depends on the number of Plugins installed and on the Plugin implementation. Some Plugins impose no measurable performance decrease, some do. For example, outsidePREHandler is an expensive callback function, or a Plugin might use many Perl libraries that need to be initialized with each page view (unless you run mod_perl). It is recommended to measure the performance with and without a new Plugin. Example for Unix:time wget -qO /dev/null http://fpmac116.usc.es/twiki/bin/view/TWiki/AbcPlugin

In case you need to install an "expensive" Plugin and you need its functionality only in one web you can place the Plugin topic into that web. TWiki will initialize the Plugin only if the Plugin topic is found (which won't be the case for other webs.)

Managing Plugins

When you finish installing a Plugin, you should be able to read the user instructions and go. In fact, some Plugins require additional settings or offer extra options that you have to select. Also, you may want to make a Plugin available only in certain webs, or temporarily disable it. And may want to list all available Plugins in certain topics. You can handle all of these management tasks with simple procedures.

Setting Preferences

Installed Plugins can be toggled on or off, site-wide or by web, through TWikiPreferences and individual WebPreferences:

All Plugin modules present in the lib/TWiki/Plugins directory are activated automatically unless disabled by the DISABLEDPLUGINS Preferences variable in TWikiPreferences. You can optionally list the installed Plugins in the INSTALLEDPLUGINS Preferences variable. This is useful to define the sequence of Plugin execution, or to specify other webs than the TWiki web for the Plugin topics. Settings in TWikiPreferences are:

Set INSTALLEDPLUGINS = DefaultPlugin, ...

Set DISABLEDPLUGINS = EmptyPlugin, ...

Plugin execution order in TWiki is determined by searching Plugin topics in a specific sequence: First, full web.topicname name, if specified in INSTALLEDPLUGINS; next, the TWiki web is searched; and finally, the current web.

Plugin-specific settings are done in individual Plugin topics. Two settings are standard for each Plugin:

One line description, used to form the bullets describing the Plugins in the TextFormattingRules topic:

Set SHORTDESCRIPTION = Blah blah woof woof.

Debug Plugin, output can be seen in data/debug.txt. Set to 0=off or 1=on:

Set DEBUG = 0

The settings can be retrieved as Preferences variables like %<pluginname>_<var>%, ex: %DEFAULTPLUGIN_SHORTDESCRIPTION% shows the description of the DefaultPlugin.

Listing Active Plugins

Plugin status variables let you list all active Plugins wherever needed. There are two list formats:

The %PLUGINDESCRIPTIONS% variable displays a bullet list with a one-line description of each active Plugins. This variable is based on the %<plugin>_SHORTDESCRIPTION% Preferences variables of individual topics and is shown in TextFormattingRules.

TablePlugin: Control attributes of tables and sorting of table columns

The TWiki Plugin API

The Application Programming Interface (API) for TWikiPlugins provides the specifications for hooking into the core TWiki code from your external Perl Plugin module. The Plugin API is new to the Production version of TWiki with the 01-Sep-2001 release.

Available Core Functions

The TWikiFuncModule (lib/TWiki/Func.pm) implements ALL official Plugin functions. Plugins should ONLY use functions published in this module.

If you use functions not in Func.pm, you run the risk of creating security holes. Also, your Plugin will likely break and require updating when you upgrade to a new version of TWiki.

Predefined Hooks

In addition to TWiki core functions, Plugins can use predefined hooks, or call backs, listed in the lib/TWiki/Plugins/EmptyPlugin.pm module.

All but the initPlugin are disabled. To enable a call back, remove DISABLE_ from the function name.

For best performance, enable only the functions you really need. NOTE: outsidePREHandler and insidePREHandler are particularly expensive.

Most Plugins use either the commonTagsHandler or startRenderingHandler for rendering tasks:

commonTagsHandler: Use it to expand %XYZPLUGIN% and %XYZPLUGIN{...}% variables

startRenderingHandler: Use it for your own rendering rules or to overload TWiki's internal rendering like [[links]]

Plugin Version Detection

To eliminate the incompatibility problems bound to arise from active open Plugin development, a Plugin versioning system is provided for automatic compatibility checking.

All modules require a $VERSION='0.000' variable, beginning at 1.000.

The initPlugin handler should check all dependencies and return TRUE if the initialization is OK or FALSE if something went wrong.

The Plugin initialization code does not register a Plugin that returns FALSE (or that has no initPlugin handler).

$TWiki::Plugins::VERSION in the TWiki::Plugins module contains the TWiki Plugin API version, currently 1.025.

You can also use the %PLUGINVERSION{}% variable to query the Plugin API version or the version of installed Plugins.

Creating Plugins

With a reasonable knowledge of the Perl scripting language, you can create new Plugins or modify and extend existing ones. Basic plug-in architecture uses an Application Programming Interface (API), a set of software instructions that allow external code to interact with the main program. The TWiki Plugin API Plugins by providing a programming interface for TWiki.

The DefaultPlugin Alternative

DefaultPlugin can handle some outdated TWiki variables, found, for example, in sites recently updated from an old version. Settings are in DefaultPlugin topic. You can also add your own simple custom processing rules here, though in all but very simple cases, writing a new Plugin is preferable.

Anatomy of a Plugin

A basic TWiki Plugin consists of two elements:

a Perl module, ex: MyFirstPlugin.pm

a documentation topic, ex: MyFirstPlugin.txt

The Perl module can be a block of code that connects with TWiki alone, or it can include other elements, like other Perl modules (including other Plugins), graphics, TWiki templates, external applications (ex: a Java applet), or just about anything else it can call.
In particular, files that should be web-accessible (graphics, Java applets ...) are best placed as attachments of the MyFirstPlugin topic. Other needed Perl code is best placed in a lib/TWiki/Plugins/MyFirstPlugin/ directory.

The Plugin API handles the details of connecting your Perl module with main TWiki code. When you're familiar with the Plugin API, you're ready to develop Plugins.

Creating the Perl Module

Copy file lib/TWiki/Plugins/EmptyPlugin.pm to <name>Plugin.pm. The EmptyPlugin.pm module contains mostly empty functions, so it does nothing, but it's ready to be used. Customize it. Refer to the Plugin API specs for more information.

If your Plugin uses its own modules and objects, you must include the name of the Plugin in the package name. For example, write Package MyFirstPlugin::Attrs; instead of just Package Attrs;. Then call it using:

Writing the Documentation Topic

The Plugin documentation topic contains usage instructions and version details. It serves the Plugin files as FileAttachments for downloading. (The doc topic is also included in the distribution package.) To create a documentation topic:

Plugin Info: <Version, credits, history, requirements - entered in a form, displayed as a table. Both are automatically generated when you create or edit a page in the TWiki:Plugins web.>"

Packaging for Distribution

A minimum Plugin release consists of a Perl module with a WikiName that ends in Plugin, ex: MyFirstPlugin.pm, and a documentation page with the same name(MyFirstPlugin.txt).

Distribute the Plugin files in a directory structure that mirrors TWiki. If your Plugin uses additional files, include them ALL:

lib/TWiki/Plugins/MyFirstPlugin.pm

data/TWiki/MyFirstPlugin.txt

pub/TWiki/MyFirstPlugin/uparrow.gif [a required graphic]

Create a zip archive with the Plugin name (MyFirstPlugin.zip) and add the entire directory structure from Step 1. The archive should look like this:

lib/TWiki/Plugins/MyFirstPlugin.pm

data/TWiki/MyFirstPlugin.txt

pub/TWiki/MyFirstPlugin/uparrow.gif

Publishing for Public Use

You can release your tested, packaged Plugin to the TWiki community through the TWiki:Plugins web. All Plugins submitted to TWiki.org are available for download and further development in TWiki:Plugins/PluginPackage. Publish your Plugin in these steps:

Link from the doc page to a new, blank page named after the Plugin, and ending in Dev, ex: MyFirstPluginDev. This is the discussion page for future development. (User support for Plugins is handled in TWiki:Support.)

TWiki::Func Module Documentation

Official list of stable TWiki functions for Plugin developers

Description

This module defines official funtions that Plugins
and add-on scripts can use to interact with the TWiki engine and content.

Plugins should only use functions published in this module. If you use
functions in other TWiki libraries you might impose a security hole and
you will likely need to change your Plugin when you upgrade TWiki.

The version of the TWiki::Func module is defined by the VERSION number of the
TWiki::Plugins module, currently 1.025. This can be shown by the
%PLUGINVERSION{}% variable. The "Since" field in the function documentation
refers to the VERSION number and the date that the function was addded.

Functions: CGI Environment

getSessionValue( $key ) ==> $value

Description:

Get a session value from the Session Plugin (if installed)

Parameter: $key

Session key

Return: $value

Value associated with key; empty string if not set; undef if session plugin is not installed

Since:

TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

setSessionValue( $key, $value ) ==> $result

Description:

Set a session value via the Session Plugin (if installed)

Parameter: $key

Session key

Parameter: $value

Value associated with key

Return: $result

"1" if success; undef if session plugin is not installed

Since:

TWiki::Plugins::VERSION 1.000 (17 Aug 2001)

getSkin( ) ==> $skin

Description:

Get the name of the skin, set by the SKIN preferences variable or the skin CGI parameter

Notes: TWiki internally precompiles several regular expressions to represent various string entities
in an I18N-compatible manner. Plugins are encouraged to use these in matching where appropriate.
The following are guaranteed to be present; others may exist, but their use is unsupported and
they may be removed in future TWiki versions. Those which are marked "CC" are for use within
character classes and may not produce the desired results outside of them.

The dependencies are expressed as a list of hashes. Each hash contains
the name of a package and (optionally) a boolean constraint on the VERSION
variable in that package. It is usually used from the initPlugin method
like this:

Copyright and License

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details, published at
http://www.gnu.org/copyleft/gpl.html

NOTE: Above text is copied from the TWiki::Plugins/PerlDocPlugin output of TWiki::Func in twiki format. In case you want to get dynamically updated documentation based on the actual Perl module, install the PerlDocPlugin and replace above text with %PERLDOC{"TWiki::Func"}%.

TWiki Site Tools

Utilities for searching, navigation, and monitoring site activity

TWikiSiteTools include utilities for navigating, searching and keeping up with site activity. Preferences can be configured by web or site-wide. You are currently in the TWiki web. In particular, TWiki provides two highly configurable, automated site monitoring tools, WebNotify, to email alerts when topics are edited, and WebStats, to generate detailed activity reports.

WebNotify Recent Changes Alert

Each TWiki web has an automatic email alert service that sends a list of recent changes on a preset schedule, like once a day. Users can subscribe and unsubscribe using WebNotify in each web. The Perl script mailnotify is called by a background process at regular intervals. The script sends an automated email to subscribed users if topics were changed in a web since the script was last run.

Format: TWiki handles entries in bullet list (<space><space><space>*) format containing the WikiName of a user; a WikiName with e-mail address; or a TWikiGroup. Examples:

Main.FredBloggs

Main.FredBloggs - secondary@home.com

Main.EngineeringGroup

The first entry is the default form, the notification gets sent to the e-mail address specified in the user's home page. The second entry lists an alternative e-mail address. The third entry specifies a group, the notification gets sent to each member of the group.

You can also use %MAINWEB% instead of Main, but this is not necessary even if you have renamed the main web by configuring $mainWebname in TWiki.cfg.

Configuring Outgoing Mail

TWiki will use the Net::SMTP module if it is installed on your system. Set this with the SMTPMAILHOST variable in TWikiPreferences.

The notify e-mail uses the default changes.tmpl template, or a skin if activated in the TWikiPreferences.

mailnotify also relies on two hidden files in each TWiki/data/[web] directory: .changes and .mailnotify. Make sure both are writable by your web server process. .changes contains a list of changes; go ahead and make this empty. .mailnotify contains a timestamp of the last time notification was done.

You can use an external mail program, like sendmail, if the Net::SMTP module is not installed. Set the program path in $mailProgram in TWiki.cfg.

Net::SMTP can be easily disabled (ex: if there is an installation error) by setting SMTPMAILHOST in TWikiPreferences to an empty value.

You can set a separate SMTPSENDERHOST variable to define the mail sender host (some SMTP installations require this).

Setting the Automatic Email Schedule

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
0 2 * * * (cd /path/to/twiki/bin; ./mailnotify -q)

The above line will run mailnotify nightly at 02:00. The -q switch suppresses all normal output.

For ISP installations: Many ISPs don't allow hosted accounts direct cron access, as it's often used for things that can heavily load the server. Workaround scripts are available.

On Windows NT/2000: You can use a scheduled task if you have administrative privileges.
Note: AT on an NT machine is pretty limited.
Microsoft lists several third-party
replacements. TWiki:Codev/CronTabWin is a free scheduler for Windows.

WebStatistics Site Usage Log

You can generate a listing manually, or on an automated schedule, of visits to individual pages, on a per web basis. Compiled as a running total on a monthly basis. Includes totals for Topic Views, Topic Saves, Attachment Uploads, Most Popular Topics with number of views, and Top Contributors showing total of saves and attachment uploads. Previous months are saved.

Configuring for Automatic Operation

You can automatically generate usage statistics for all webs. To enable this:

Make sure variable $doLogTopicView, $doLogTopicSave and $doLogTopicUpload in TWiki.cfg are set. This will generate log file entries (see below).

The WebStatistics topic 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 many 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)

Generating Statistics Manually by URL

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

WebChanges

To check for the most recently edited topics while on-site, use the WebChanges link, usually located on the upper toolbar. It lists the most recently modified topics, newest first, along with the first couple of lines of the page content.

This is simply a preset SEARCH. The number of topics listed by the limit parameter.:

Managing Topics

Overview

You can use browser-based controls to change a topic's name, move it to another TWiki web, or delete it to a hidden Trash web.

How to Rename/Move/Delete a Topic

Click on [More] (bottom right of page) on the topic to be changed, then, in the new screen, on [Rename/move]. You can now rename and/or move/delete in one operation:

Move/Delete: Select the target web if other than the current web - choose Trash to delete a topic.

Rename: Enter the new topic name - default is current name NOTE: You'll be warned if any of the topics to be affected are locked (being edited), or if there is a name conflict.

Prevent updates by unchecking individual items on the list of referring links - these topics will NOT to be updated with the new name (by default, all referring links will be updated).

Click on [Rename/Move]: the topic will be renamed and links to the topic updated as requested.

If any of the referring pages are locked then they will be listed: you can correct these later by again pressing [Rename/Move].

There is a Put back feature that allows you to undo a Rename/Move/Delete - an instruction line and undo link will appear at the bottom of the modified topic. This allows you to revert from the last modification only.

Deleted Topics: How to Clear the Trash

Deleted topics are moved to a special Trash web - they are NOT physically erased from the server. All webs share Trash - in case of a name conflict with a topic already Trash, the user is alerted and asked to choose a new name.

The Trash web should be be cleared periodically, by archiving (saving) the text and RCS files if required (recommended), then deleting them from the Trash directory.

This can only be done from on the server, not through the browser.

Since simple FTP access to the Trash directory is all that's required for maintenance, it's possible to grant Trash admin privileges to multiple users, while strictly limiting server access.

%<nop>METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%"
title="This topic used to exist and was moved to: "}%

How Rename/Move Works

%SEARCH%, with a special template, finds and displays all occurrences of the topic name in other topics, site-wide. These referring links are by default automatically changed to the new topic and/or web name. This includes relevant TWikiMetaData definitions.

User can omit one or more topics from the update list by unchecking them.

<pre> and <verbatim> are honoured - no changes are made to text within these areas.

The topic is moved (if locks allow).

References are changed (locks and permissions permitting).

Any referring topics that can't be changed due to locks are listed - user can take note and change them at another time.

How Referring Topics Are Found

Referring topics are found using the %SEARCH% variable - see the template searchrenameview.tmpl. First, matching topics in the current web are listed - matches are to topic. Next, all webs (including the current one) are listed that match web.topic. Because %SEARCH% is used, webs marked in WebPreferences as NOSEARCHALL will not show up in the search for references to the topic being changed.

Changed references are kept are as short as possible, ex: topic is used in preference to web.topic.

Effect of User Access Settings

User permissions affect the Rename function in various ways. To rename a topic, you need both ALLOWTOPICCHANGE and ALLOWTOPICRENAME permission for that topic. To alter referring topics, you need change permission. See TWikiAccessControl for information on setting up access permissions.

Special Considerations

Consider carefully whether to make browser-based Rename/Move/Delete widely available, or to restrict it to an administrator/moderator group. Allowing all users to easily manipulate topics can be extremely useful in refactoring a busy web or site. However, there are at least two significant potential drawbacks to take into account:

When referring links are updated, the modified topics appear in WebChanges, creating the impression that editorial changes were made. This can undermine the usefulness of WebChanges.

Due to current limitations, fairly heavy use of Rename/Move/Delete functions can lead to an accumulation of minor technical problems (ex: broken links) and usability issues (ex: user confusion). If Rename... is used heavily, these negatives will obviously increase, in number and effect.

Ultimately, the size, objectives, and policies of your TWiki site, the real-world behavior of your user group, and most importantly, the initial TWiki site management leadership, will determine the most effective implementation of this feature, and the success of the site overall.

Known Issues

Rename/Move is fairly complicated due to the dynamic generation of links. Ideally, it would be possible to run the required part of rendering in a way that would allow identification of the text to be changed. Unfortunately, these hooks don't exist in TWiki at present. Instead, %SEARCH% is used with a special template to show the text to be changed, and the selected topics are then altered. One drawback is that search can show matches that will not be updated due to case differences. Other mismatches with actual rendered output are also possible as the approaches are so different.

Managing Webs

Adding webs is a web based operation; renaming and deleting webs are manual operations done directly on the server

Overview

A TWikiSite is divided into webs; each one represents one subject, one area of collaboration. Administrators can add/rename/delete webs.

Choose Web Template

There are two methods used to create a new web. First you can use a specially designed TemplateWeb. This is an invisible web that begins with an underscore "_" character. All topics in the _default template web will be copied into your new web.

The second method is to use an existing web as a template web. This may be useful if you already have a web that you like to use as a starting point. Only topics that have names beginning with Web... (like "WebHome", "WebNotify", etc.) are copied.

In either case you will want to be sure to verify that your new web has all the custom modifications that you desire.

Adding a New Web

Create a new web by filling out this form. Note: It is not recommended to create a new web for each little project. You can organize content within a web using TWikiForms and FormattedSearch. Cross-linking topics and search is easier if there are only a few larger webs.

Name of new web:

Enter a short name of up to 10 characters. The name must start with an upper case letters, followed by optional upper or lower case letters or numbers

Enter a short description of the web. Write Web.TopicName instead of just TopicName if you include links. This will list the web in the SiteMap (leave field empty if you prefer not to update the directory.)

Use to...

Continue the sentence describing the intended use. This is also for the SiteMap

Exclude web from "search all":

No Yes

Specify if you want to exclude the web from a "search all webs" search. Note that the SiteMap will not list the web if you select Yes.

Notes:

Attachments will NOT get copied over along with their topics

The manage script while creating the new web will update the following variables in the WebPreferences: WEBBGCOLOR, SITEMAPLIST, SITEMAPWHAT, SITEMAPUSETO and NOSEARCHALL. These variables are used to dynamically generate the SiteMap

This script does not edit the TWiki.TWikiPreferences file to update the WIKIWEBLIST. This must be done by hand

As of TWiki Release 01 Sep 2004, a web name can be a WikiWord. Prior to that it could be only UPPER or UPPERlower. A side effect of this is that if you do use a wiki name, %WEB% must be written as <nop>%WEB% or else it will try to link to a non-existing topic of that name

Renaming or Deleting a Web

Renaming or deleting a web requires direct access to the installation files on the host server. There are currently no browser-based equivalents of the Rename/move/delete topic tools for working with webs.

Prepare your site: Search each web for links to the target web, searching topic text for Oldwebname., including the dot so you'll find references like Oldwebname.SomeTopic

Make changes as required, to Newwebname.SomeTopic or better yet, to %MAINWEB%.SomeTopic

Edit the TWikiPreferences topic: Rename or delete the web from the WIKIWEBLIST variable

Login to the TWiki server, via Telnet or FTP

Go to twiki/data and rename or remove the web directory

Go to twiki/templates and rename or remove the web directory if present

Renaming the MAINWEB

If you plan to rename the Main web, remember that TWiki stores user and group topics in %MAINWEB%, default named Main. That means, every WikiName signature - Main.SomeUserName - points to it and would need updating (unless the variable, %MAINWEB%.SomeUserName, is used throughout).

Removing User Accounts

To remove a user account:

Edit the data/.htpasswd file to delete their entry (only applies if you are using a .htpasswd file)

Remove the FredQuimby line from the Main.TWikiUsers topic

Remove user from all groups and from all the ALLOWWEB/ALLOWTOPIC... declarations, if any.Note: Otherwise this is a security hole as the first one to re-register with this name will be granted the permissions of the previous user.

Note: Consider leaving the user topic file in place so their past signatures and revision author entries don't end up looking like AnUncreatedTopic?. If you want to make it clear the user is inactive on your site (e.g. PeterThoeny?) or has been banished add a note to that effect and write protect the page (TWikiAccessControl). The existance of the UserName topic prevent that user name from being re-used.

Appendix A: TWiki Filesystem

Annotated directory and file listings, for the 01-Sep-2004 TWiki production release.

Who and What is This Good For?

Interested Users and Site Administrators can find out in simple terms what each part of TWiki actually does. Adventurous Adminstrators with server access to files (via telnet, ssh or ftp) can also figure out where to look to make minor modifications, like changing hardcode text or color. Software Developers can get an at-a-glance overview of TWiki code architecture.

Directory Structure

You can rename the root TWiki directory - twiki - to whatever you like by changing it in the TWiki.cfg configuration file. However, to keep the current installation and future upgrades simple, you should leave the five main subdirectories intact:

Files under twiki/pub

The pub directory stores topic-related files, including images used by TWiki and FileAttachments. Attachments are stored in subdirectories created with the related topic name. You can also upload files directly for and link manually (but not through Attach) Partial file list:

Files under twiki/data

TWiki topics: data stored as individual text files and rendered by TWiki for display as regular Web pages. Each active web has its own subdirectory. The TWiki distribution includes a number of start-up webs - Main, TWiki, and Sandbox - with documentation and demo content, a Trash web for browser-based, recoverable topic deletion, and a _default directory containing a core topic set required to start a new web. Partial file list:

Display if rename done, but some references not changed (topics were locked)

search.tmpl

Search screen

searchbookview.tmpl

Search results with full topic content

searchformat.tmpl

Search screen for formatted search

searchmeta.tmpl

Search screen

searchrenameview.tmpl

Used by rename to list references to topic being renamed

twiki.tmpl

Master template: definitions are used by other templates

view.plain.tmpl

Skin for bare bone topic view without header/footer but with HTML head and body tags

view.print.tmpl

Skin for printable topic view with a simple header/footer

view.rss.tmpl

Skin for topic view in RDF XML format

view.text.tmpl

Skin for topic text only, without HTML head and body tags, and no form and attachments

view.tmpl

Main topic view - the standard regular Web page

TWiki File System Snapshot

The following partial directory listings from a Linux installation show typical file permissions and ownership. This is provided for general debugging use only and isn't an exact representation of the current distribution.

On an ISP installation... The user and group - twiki twiki - will probably be your domain or login name, eg: yourdomain yourdomain and can't be changed; same for nobody nobody files further down. Also, in the bin directory, scripts might need a .cgi (sometimes .pl) extension.

Appendix B: TWiki CSS

Listing of CSS class names emitted from TWiki core code and standard plugins, for the 01-Aug-2004 TWiki production release.

Who should read this document?

More or less all html elements generated by TWiki core code now have Cascading Style Sheet (CSS) tags. Skin builders and others who want to change the appearance of the default TWiki installation or any of the skins can use this document to see what styles can be created for these html elements.

Appendix C: Encode URLs With UTF8

Current Status

To simplify use of internationalised characters within WikiWords and attachment names, TWiki now supports UTF-8 URLs, converting on-the-fly to virtually any character set, including ISO-8859-*, KOI8-R, EUC-JP, and so on.

Support for UTF-8 URL encoding avoids having to configure the browser to turn off this encoding in URLs (the default in Internet Explorer, Opera Browser and some Mozilla Browser URLs) and enables support of browsers where only this mode is supported (e.g. Opera Browser for Symbian smartphones). A non-UTF-8 site character set (e.g. ISO-8859-*) is still used within TWiki, and in fact pages are stored and viewed entirely in the site character set - the browser dynamically converts URLs from the site character set into UTF-8, and TWiki converts them back again.

System requirements are updated as follows:

ASCII or ISO-8859-1-only sites do not require any additional CPAN modules to be installed.

Perl 5.8 sites using any character set do not require additional modules, since CPAN:Encode is installed as part of Perl.

This feature still works on Perl 5.005_03 as per TWikiSystemRequirements, or Perl 5.6, as long as CPAN:Unicode::MapUTF8 is installed.

ISO-2022-*, HZ-* and other 'non-ASCII-safe' multi-byte character sets are now specifically excluded from use as the site character set, since they interfere with TWiki ML; however, many multi-byte character sets work fine, e.g. EUC-JP, GB2312, etc.

It's now possible to override the site character set defined in the $siteLocale setting in TWiki.cfg - this enables you to have a slightly different spelling of the character set in the server locale (e.g. 'eucjp') and the HTTP header sent to the browser (e.g. 'euc-jp').

This feature should also support use of Mozilla Browser with TWiki:Codev.TWikiOnMainframe (as long as mainframe web server can convert or pass through UTF-8 URLs) - however, this specific combination is not tested. Other browser-server combinations should not have any problems.

Details of Implementation

The overall plan for UTF-8 support for TWiki is described in two phases in TWiki:/Codev.ProposedUTF8SupportForI18N - this page addresses the first phase, in which UTF-8 is supported for URLs only.

UTF-8 URL translation to virtually any character set is supported as of TWiki Release 01 Sep 2004, but full UTF-8 support (e.g. pages in UTF-8) is not supported yet - this will be phase 2.

The code automatically detects whether a URL is UTF-8 or not, taking care to avoid over-long and illegal UTF-8 encodings that could introduce TWiki:Codev.MajorSecurityProblemWithIncludeFileProcessing (tested against a comprehensive UTF-8 test file, which IE 5.5 fails quite dangerously, and Opera Browser passes). Any non-ASCII URLs that are not valid UTF-8 are then assumed to be directly URL-encoded as a single-byte or multi-byte character set (as now), e.g. EUC-JP.

The main point is that you can use TWiki with international characters in WikiWords without changing your browser setup from the default, and you can also still use TWiki using non-UTF-8 URLs. This works on any Perl version from 5.005_03 onwards and corresponds to Phase 1 of TWiki:Codev.ProposedUTF8SupportForI18N. You can have different users using different URL formats transparently on the same server.

UTF-8 URLs are automatically converted to the current $siteCharset (from the TWiki.cfg locale setting), using modules such as CPAN:Encode if needed.

TWiki generates the whole page in the site charset, e.g. ISO-8859-1 or EUC-JP, but the browser dynamically UTF-8 encodes the attachment's URL when it's used. Since Apache serves attachment downloads without TWiki being involved, TWiki's code can't do its UTF-8 decoding trick, so TWiki URL-encodes such URLs in ISO-8859-1 or whatever when generating the page, to bypass this URL encoding, ensuring that the URLs and filenames seen by Apache remain in the site charset.

TWiki:Codev.TWikiOnMainframe uses EBCDIC web servers that typically translate their output to ASCII, UTF-8 or ISO-8859-1 (and URLs in the other direction) since there are so few EBCDIC web browsers. Such web servers don't work with even ISO-8859-1 URLs if they are URL encoded, since the automated translation is bypassed for URL-encoded characters. For TWiki on Mainframe, TWiki assumes that the web server will automatically translate UTF-8 URLs into EBCDIC URLs, as long as URL encoding is turned off in TWiki pages.

Format changed of %GMTIME{"..."}% and %SERVERTIME{"..."}% variables. Format is now "$hour:$min" instead of "hour:min". More in TWikiVariables. Attention: Check your existing topics when you upgrade TWiki!

New TWikiPreferences variables %HTTP_EQUIV_ON_VIEW% , %HTTP_EQUIV_ON_EDIT% and %HTTP_EQUIV_ON_PREVIEW% that define the <meta http-equiv="..."> meta tags for the TWiki templates. This can be used for example to set a document expiration time.

Uploading a file (topic file attachment) will optionally create a link to the uploaded file at the end of the topic. The preference variable %ATTACHLINKBOX% controls the default state of the link check box in the attach file page.

Edit preferences topics to set TWiki variables. There are three level of preferences Site-level (TWikiPreferences), web-level (WebPreferences in each web) and user-level preferences (for each of the TWikiUsers). With this, discontinue use of server side include of wikiwebs.inc , wikiwebtable.inc , weblist.inc , webcopyright.inc and webcolors.inc files.

New variable %SCRIPTSUFFIX% / $scriptSuffix containing an optional file extension of the TWiki Perl script. Templates have been changed to use this variable. This allows you to rename the Perl script files to have a file extension like for example ".cgi".

New variable %SCRIPTURLPATH% / $scriptUrlPath containing the script URL without the domain name. Templates have been changed to use this variable instead of %SCRIPTURL% . This is for performance reasons.

Inline search. New variable %SEARCH{"str" ...}% to show a search result embedded in a topic text. TWikiVariables has more on the syntax. Inline search combined with the category table feature can be used for example to create a simple bug tracking system.

Access statistics. Each web has a WebStatistics topic that shows monthy statistics with number of topic views and changes, most popular topics, and top contributors. (It needs to be enabled, TWikiDocumentation has more.)

Search path for include files in %INCLUDE:"file.inc"% variable. Search first in the current web, then in parent data directory. Useful to overload default include text in the data directory by web-specific text, like for example webcopyright.inc text.

01-Jul-1999 Release

Separate wiki.pm into configuration (wikicfg.pm) and TWiki core (wiki.pm) . This is to ease the upgrade of TWiki installations, it also allows customized extensions to TWiki without affecting the TWiki core.

Possible to view complete revision history of a topic on one page. Access at the linked date in the Changes page, or the Diffs link at the bottom of each topic, e.g. Topic TWikiHistory . { Edit Ref-By Diffs r1.3 > r1.2 > r1.1 } Revision r1.3 1998/11/10 01:34 by PeterThoeny

1998 Releases

Possible to add a category table to a TWiki topic. This permits storing and searching for more structured information. Editing a topic shows a HTML form with the usual text area and a table with selectors, checkboxes, radio buttons and text fields. TWikiDocumentation has more on setup. The TWiki.Know web uses this category table to set classification, platform and OS version.

Added revision control using RCS. Each topic has now a list of revisions at the bottom and a revision info, e.g. Topic TWikiHistory . { Edit Ref-By r1.3 r1.2 r1.1 } Revision r1.3 1998/10/26 01:34:00 by TWiki:Main.PeterThoeny