BBO BlinkenArea > TWiki > TWikiDocumentation BlinkenArea webs:
BlinkenArea | Main | TWiki | Sandbox | (Recycle Bin)
TWiki . { Welcome | Register | Changes | Topics | Index | Search }
BlinkenArea.TWikiDocumentation
144 pixels ought to be enough for anybody

Home
Ziele
BlinkenArea
BlinkenLights

News
Presse
Links
Forum
MailList
Join

Audio,Video
Projekte
Protokolle
Dateiformate
Troia
bluebox

WTH
ICMP
CBCamp
CCCamp
CCCongress
EasterHack

Stats
Users
SiteMap
TWikiDoku
SiteTools
Translate
WebChanges

Impressum
Imprint
Datenschutzerklärung
Privacy Policy

RSS and Mail notification
powered by: [Powered by Eventphone]

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: Read the most up to date version of this document at http://TWiki.org/cgi-bin/view/TWiki/TWikiDocumentation

Related Topics: TWikiSite, TWikiHistory, TWikiPlannedFeatures, TWikiEnhancementRequests

TWiki System Requirements

Server and client requirements for TWiki 01-Feb-2003

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.

Required Server Environment
Resource Unix Windows*
Perl 5.005_03 or higher (5.6.1 recommended,
5.8.0 not recommended yet, see TWiki:Codev.UsingPerl58OnRedHat8)
Non-standard Perl modules Net::SMTP (or sendmail) Net::SMTP, MIME::Base64, Digest::SHA1
RCS 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)
Other external programs ls, fgrep, egrep
Cron/scheduler cron cron equivalents
Web server Apache 1.3 is well supported; Apache 2.0 is not recommended yet (see TWiki:Support.FailedAuthenticationWithApache2OnWinNT).
For other servers, CGI support, authentication, extended path required

ALERT! * 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.

Client Requirements

The TWiki standard installation has extremely low browser requirements:

  • HTML 3.2 compliant
  • generates XHTML 1.0 pages that are compatible with HTML 3.2
  • minimal use of JavaScript in the user interface (degrades gracefully)
  • no cookies
  • no CSS

You can easily add functionality, by customizing TWikiTemplates, for one, while tailoring the browser requirements to your situation.

Known Issues

  • The TWikiPlugins feature currently does not have compatibility guidelines for developers. Plugins can require just about anything - browser-specific functions, stylesheets (CSS), Java applets, cookies, specific Perl modules,... - check the individual Plugin specs.
    • HELP Plugins included in the TWiki distribution do not add requirements.

-- MikeMannix? - 12 Jan 2002

TWiki Installation Guide

Installation instructions for the TWiki 01-Feb-2003 production release. Update notes for the new RCS configuration are marked Dataframework.

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. Documentation for other platforms is somewhat limited:

Standard Installation

Request and download the TWiki 01-Feb-2003 distribution in Unix ZIP format from http://TWiki.org/download.html. Please review the AdminSkillsAssumptions before you install TWiki.

Step 1: Create & Configure the Directories

ALERT! 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 /etc/httpd/httpd.conf with only ExecCGI option.
  • The twiki/pub directory of TWiki must be set so that it is visible as a URL. Add /home/httpd/twiki to file httpd.conf with normal access options (copy from /home/httpd/html ).
  • Now add ScriptAlias for /twiki/bin and Alias for /twiki to file httpd.conf .
    ALERT! NOTE: The ScriptAlias must 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.

Example httpd.conf entries: 
 ScriptAlias /twiki/bin/ "/home/httpd/twiki/bin/"
 Alias /twiki/ "/home/httpd/twiki/"
 <Directory "/home/httpd/twiki/bin">
    Options +ExecCGI
    SetHandler cgi-script
    Allow from all
 </Directory>
 <Directory "/home/httpd/twiki/pub">
    Options FollowSymLinks +Includes
    AllowOverride None
    Allow from all
 </Directory>
 <Directory "/home/httpd/twiki/data">
    deny from all
 </Directory>
 <Directory "/home/httpd/twiki/templates">
    deny from all
 </Directory>

  • Restart Apache by /etc/rc.d/rc5.d/S85httpd restart .
  • Test that the twiki/bin directory is CGI-enabled by trying visiting it in your browser:
    • Enter the URL for the bin directory, http://yourdomain.com/twiki/bin/.
    • Your settings are OK if you get a message like "Forbidden. You don't have permission to access /twiki/bin/ on this server".
    • Settings are NOT correct if you get something like "Index of /twiki/bin" - recheck your httpd.conf file.

Step 1 for Non-Root Accounts

To install TWiki on a system where you don't have Unix/Linux root (administrator) privileges, for example, on a hosted Web account or an intranet server administered by someone else:

  • Download and unzip TWiki on your local PC
  • Using the table below, create a directory structure on your host server
  • Upload the TWiki files by FTP (transfer as text except for the image files in pub)
TWiki dir: What it is: Where to copy: Example:
twiki start-up pages root TWiki dir /home/smith/twiki/
twiki/bin CGI bin CGI-enabled dir /home/smith/twiki/bin
twiki/lib library files same level as twiki/bin /home/smith/twiki/lib
twiki/pub public files htdoc enabled dir /home/smith/twiki/pub
twiki/data topic data dir secure from public access /home/smith/twiki/data
twiki/templates web templates dir secure from public access /home/smith/twiki/templates

If you are not able to create 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 edit the setlib.cfg file in the bin directory: 

    # -------------- Change these settings if required

    $twikiLibPath = '/some/other/path/lib';   # Path to lib directory containing TWiki.pm

You can also edit $localPerlLibPath in the setlib.cfg file 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.

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.
    • IMPORTANT: On ISP-hosted accounts, Perl CGI scripts usually require a .cgi extension to run. Some systems need .pl, the regular Perl extension. Modify all twiki/bin script filenames if necessary.
  • 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.
  • HELP 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).
      • TIP 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 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/data directory 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.
  • HELP 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, ex www-data, or delete them all - new files will be automatically created the first time each topic is edited. A simple way to change ownership is with a search-and-replace in all files; for example, using perl: 
cd twiki/data
perl -pi~ -e 's/nobody:/www-data:/' */*,v

Step 3: Set the Main Configuration 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)
  • Test your settings by running the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. Check if your twiki/lib/TWiki.cfg configuration file settings are correct.

Step 4: Configure Site-Wide Email Preferences

  • From your web browser, edit the TWikiPreferences topic in the TWiki:TWiki web 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.
  • You may want to set up other TWikiPreferences later on.

Step 5: Finish Up from Your Browser

  • Point your Web browser at http://yourdomain.com/twiki/bin/view and start TWiki-ing away!
    • TIP 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.
  • Enable email notification of topic changes, TWikiSiteTools has more.
  • Edit the WebNotify topic in all webs and add the users you want to notify.
  • Add the TWiki:Main/PoweredByTWikiLogo to your Main topic.
  • You can add new %VARIABLES%. Define site-level variables in the TWikiPreferences topic. See also: TWikiVariables.

That's it for the standard virgin 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:
    1. Rename file .htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. For details, consult the HTTP server documentation (for Apache server: [1], [2]). In particular, the following red part needs to be configured correctly:
      Redirect /urlpathto/twiki/index.html http://yourdomain.com/urlpathto/twiki/bin/view
      AuthUserFile /filepathto/twiki/data/.htpasswd
      ErrorDocument 401 /urlpathto/twiki/bin/oops/TWiki/TWikiRegistration?template=oopsauth
      • ALERT! 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.
      • HELP 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.
      • ALERT! 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.
    2. 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.
    • You can customize the default user home page in NewUserTemplate.
  • Register yourself in the TWikiRegistration topic.
    • ALERT! 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.
  • Create a new topic to check if authentication works.
  • Edit the TWikiAdminGroup topic in the TWiki:Main web to include users with system administrator status.
  • Edit the TWikiPreferences topic in the TWiki:TWiki web to set access privileges.
  • Edit the WebPreferences topic in each web, if necessary: set access priviliges.

That's it for a basic new web set-up!

Optionally, you can also:

  • Create custom web-specific templates in a new twiki/templates/Someweb directory (otherwise, templates are inherited from twiki/templates).
  • Add TWikiForms for form-based page input that's stored separately from the main free-form topic text.

ALERT! NOTE: User home topics are located in the BlinkenArea.Main web - don't try to move them or create them in other webs. From any other web, user signatures have to point to BlinkenArea.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!

TWiki File System Info

See Appendix A: TWiki File System for an installed system snapshot and descriptions of all files in the TWiki 01-Sep-2001 distribution.

-- PeterThoeny - 28 Dec 2002
-- MikeMannix - 16 May 2002

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. Please read TWiki:Codev.WindowsModPerlInstallCookbook in case you use mod_perl.

There is a huge volume of existing material on TWiki about installing on Windows, and I'm indebted to the many contributors for this - the aim of this cookbook is to synthesise the many tips into a recipe that works.

  • NOTE: This cookbook is probably incomplete (e.g. it doesn't cover authentication setup), but it has now been successfully tried out by a few people - it is quite accurate and should get you started if you follow the instructions. Please consider it beta quality, and 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.

-- RichardDonkin? - 24 Feb 2002

Recent updates

  • 30 Nov 2002 - added binutils to list of Cygwin packages, and added warning not to use Apache 2.0
  • 20 Nov 2002 - update to avoid TWiki:Support.InstallDigestSHA1Fails when installing Digest::SHA1 on Windows 2000
  • 12 Nov 2002 - setting SMTPMAILHOST for user registration and notification
  • 03 Sep 2002 - linked to TWiki:Codev.WindowsModPerlInstallCookbook
  • 20 Jul 2002 - added flags to grep commands in TWiki.cfg
  • 27 Jun 2002 - more updates to list of required Cygwin packages
  • 20 Jun 2002 - added creation of c:/twiki directory
  • 17 Jun 2002 - updates to list of required Cygwin packages
  • 15 Jun 2002 - various notes on Cygwin installation and troubleshooting: use of 'Unix' as default text file type (i.e. for mounting c:/cygwin directories) is essential for binary attachment uploads to work properly
  • 27 Apr 2002 - update to settings for egrep and fgrep on some Cygwin versions (fix from TWiki:Main.DavidLeBlanc)
  • 21 Apr 2002 - updates on download sizes and free disk space requirements, improved post-installation testing, and brief coverage of TWiki:Codev.WindowsInstallModNTLM to avoid TWiki:Codev.ForgettingPasswords
  • 18 Apr 2002 - updates on Apache installation, setting TZ variable, and creation of c:\temp, based on comments by TWiki:Main.MaryDeMarco
  • 3 Apr 2002 - added pcre to list of Cygwin packages (required by grep), fixed bug in Apache config (Apache doesn't allow '#' comments on same line as config)
  • 19 Mar 2002 - comment about Windows 98
  • 18 Mar 2002 - fix for register script committed to TWiki:Codev.TWikiAlphaRelease - most users can ignore this for now, but the edits in step 5 will eventually go away
  • 14 Mar 2002 - minor fix to section on Apache environment
  • 13 Mar 2002 - added a link to another Windows text editor
  • 4 Mar 2002 - changed status to beta, notes about using spaces in file names, pointer on TWiki authentication setup, overview of Cygwin permissions and security issues
  • 3 Mar 2002 - minor update to include uname -a command to check Cygwin DLL version, and delete Apache config's PassEnv line
  • 27 Feb 2002 - various improvements to Cygwin and Perl Net::SMTP installation sections, based on comments in TWiki:Codev.WindowsInstallCookbookComments by TWiki:Main.MartinWittmann. Also linked to a Windows editor that understands Unix/Cygwin file formats.
  • 25 Feb 2002 - clarified changes required to register, fixed minor typo in Cygwin binary mode section, after beta testing by TWiki:Main.JerryWard (thanks!)

Scope

This document covers installation of the TWiki -1-Feb-2003 production release in the following environment - if you want to use a different environment, feel free to use this as a guideline only.

Component Name, version Comment
Operating System Windows 2000 Should also work for Windows NT
Web Server Apache 1.3.26 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
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.

NEW 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 (see TWiki:Support.FailedAuthenticationWithApache2OnWinNT) users created by the current TWiki user registration script (due to a feature being removed in 2.0), and Perl 5.8 may introduce issues due to its Unicode features. Even though the Apache group says that Apache 2.0 is the best version, that's not true for TWiki.

Alternatives

There are doubtless other combinations of components that may work - in particular:

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

Checking versions

If you already have some of these add-ons installed, here's how to check the versions - this assumes you have TWiki:Codev.CygWin already installed: 

   $ : Cygwin DLL version is the number in 1.3.x format
   $ uname -r
   $ less c:/your-apache-dir/Announcement
   $ perl -v
   $ rcs -V

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 to 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 is best done with an editor that can handle Unix file format (see the Cygwin binary mode section below) - the installation process includes nano, a non-GUI editor, but if you prefer to use a GUI editor, you should first install PFE, a freeware editor that supports Unix format files. PFE is available on download.com and Simtel.

Another good TWiki:Codev.OpenSource editor is SciTE (aka WSciTE), available at http://www.scintilla.org/SciTE.html.

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 Win2000 cmd.exe 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 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

1. Download Apache

  • Check at http://httpd.apache.org/ for any security announcements
  • Check the latest 1.3.x version number on this page
  • Find a local mirror using http://www.apache.org/dyn/closer.cgi - choose httpd, then binaries, then win32
  • 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) - this is supported by Windows 2000.

  • 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.
  • You can choose to run Apache as a Win2000 service or as a normal program - see the Apache docs for details.

3. Test Apache

  • If necessary, start apache, either as a Win2000 service (using Admin Tools | Computer Management, or by typing apache -k start -n apache) or standalone (by typing apache -k start)
  • Point your browser at http://yourdomain.com/ to see the Apache intro page.

Congratulations, you now have a working web server!

To restart Apache after changing its config, type:

  • apache -k restart for standalone Apache process running in another window
  • 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 Cygwin 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:
    • bash
    • binutils
    • diffutils
    • gcc
    • grep
    • gzip
    • make
    • nano
    • ncftp
    • pcre
    • perl (5.6.1-2 or higher)
    • rcs (5.7-2 or higher)
    • tar
    • textutils
    • unzip
    • w32api
    • wget (optional, useful for Perl install and TWiki:Codev.ReadWriteOfflineWiki)
    • 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

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
  • Type grep home /etc/passwd - you should see some output.

The Cygwin User Guide is well worth reading for some background on how Cygwin works.

6. Configure Cygwin for binary mode

  • 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').
  • Stay in the Cygwin (bash) shell, and type the following (use only forward slashes, i.e. '/'): 
   $ mkdir /twiki /c c:/twiki
   $ mount -b -s c:/twiki /twiki
   $ mount -b -s c:/ /c
   $ mount -b -c /cygdrive
   $ mount
   Device              Directory           Type         Flags
   C:\cygwin\bin       /usr/bin            system       binmode
   C:\cygwin\lib       /usr/lib            system       binmode
   C:\cygwin           /                   system       binmode
   c:\twiki            /twiki              system       binmode
   c:                  /c                  system       binmode
  • 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 the URL that PeterThoeny sent you, 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 (e.g. Cygwin's 'nano', or the Windows PFE editor, unless you already know 'vi'), edit c:/apache/conf/httpd.conf as follows - this tells Apache where TWiki lives, and removes the need to tinker with the Windows 2000 environment settings.

  • If you are using nano, always launch it with nano -w filename - this turns off wrapping of long lines.
  • 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
  • Edit the following lines, some of which already exist in the file: 

# Change this to point to the Apache administrator (e.g. you)
ServerAdmin you@yourdomain.com

# Replaces DocumentRoot "C:/apache/htdocs"
DocumentRoot "C:/twiki"

# Replaces <Directory "C:/apache/htdocs">
<Directory "C:/twiki">

  • Add the following lines - the Alias and ScriptAlias lines can be omitted in this setup 

# Alias /twiki/ "C:/twiki/"
# ScriptAlias /twiki/bin/ "C:/twiki/bin/"
<Directory  "C:/twiki/bin/">
    # RD: Changed None to All in next line, to enable .htaccess
    AllowOverride All
    Allow From All
    Options  ExecCGI
    SetHandler cgi-script
</Directory>

# Environment setup required to run Apache as service or as a
# standalone process.
<IfModule mod_env.c>
   # Adjust TZ for your server timezone, e.g. EST5EDT - put the non-daylight-savings
   # timezone code first (e.g. EST or GMT), followed by the number of hours that it's behind GMT 
   # during non-daylight-savings time (use '-5' for timezones in advance of GMT).
   SetEnv TZ GMT0BST
   SetEnv RCSINIT -x,v/
   # Adjust TEMP and TMP for your server and create directories if necessary
   SetEnv TEMP c:/temp
   SetEnv TMP c:/temp
   SetEnv LOGNAME system
   SetEnv HOME c:/twiki
</IfModule>

2. Configure Apache (part 2)

Add an AddHandler line to the <IfModule mod_mime.c> section of httpd.conf - this removes the need to rename all the TWiki CGI scripts later in the installation.

  • Note the trailing '.' on the AddHandler line. 
#
# Document types
#
<IfModule mod_mime.c>
    # TWiki setup - avoid renaming scripts
    AddHandler cgi-script .
</IfModule>

Configuring TWiki

3. Configure TWiki

Edit the TWiki config file, c:/twiki/lib/TWiki.cfg (or in Cygwin terms, /twiki/lib/TWiki.cfg) as follows:

  • 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). 

# variables that need to be changed when installing on a new server:
# ==================================================================
#                   http://your.domain.com/twiki : link of TWiki icon in upper left corner :
$wikiHomeUrl      = "http://yourdomain.com/bin/view";
#                   Host of TWiki URL :    (Example "http://myhost.com:123")
$defaultUrlHost   = "http://yourdomain.com";
#                   /bin : cgi-bin path of TWiki URL:
$scriptUrlPath    = "/bin";
#                   /pub : Public data path of TWiki URL (root of attachments) :
$pubUrlPath       = "/pub";

# NOTE: Next three settings should be valid absolute pathnames using Cygwin; if using
# TWiki:Codev.ActiveState Perl, use z:/twiki format pathnames if your TWiki directory is not on C:.

#                   Public data directory, must match $pubUrlPath :
$pubDir           = "/twiki/pub";
#                   Template directory :
$templateDir      = "/twiki/templates";
#                   Data (topic files) root directory :
$dataDir          = "/twiki/data";

....

#                   Set ENV{'PATH'} explicitly for taint checks ( #!perl -T option ) :
#                   (Note: PATH environment variable is not changed if set to "")

# On Windows, $safeEnvPath needs only one component, the directory where RCS is installed
# - used by 'rcsdiff' to run 'co' program, so PATH must be correct.

# Unix/Linux setting:
# $safeEnvPath      = "/bin:/usr/bin";

# Using Cygwin perl, so can use Unix-like paths, with ':' as separator.
# Note that /usr/bin and /bin are identical due to default /usr/bin mount
# in Cygwin.  Must NOT use 'c:/foo' type paths, as ':' is taken as separator
# meaning that 'c' is interpreted as a pathname, giving Perl taint error.
$safeEnvPath      = "/bin";

# If using ActiveState perl, use Windows paths instead
# $safeEnvPath      = "c:/cygwin/bin";

...

#                   RCS directory (find out by 'which rcs') :
$rcsDir           = "c:/cygwin/bin";

...

#                   Unix egrep command :
$egrepCmd         = "/bin/grep -E";
#                   Unix fgrep command :
$fgrepCmd         = "/bin/grep -F";

For the cookbook install using Cygwin Perl, there's no more TWiki.cfg editing to be done, so you can get onto the next section. 

#                   NOTE: When using ActiveState Perl, you must specify
#                   a full Windows-style pathname, using '\\' for backslashes,
#                   for the ls, egrep and fgrep commands, because Cygwin's shell
#                   is not used - forward slashes are OK in Windows everywhere
#                   except in the cmd.exe shell. Drive letters are OK - e.g.
#                   'c:\\foo\\ls' will work.  When using Cygwin perl, just
#                   use the default '/bin/ls' type settings.
#
#                   Unix ls command :
$lsCmd            = "c:\\cygwin\\bin\\ls";
#                   Unix egrep command :
$egrepCmd         = "c:\\cygwin\\bin\\grep";
#                   Unix fgrep command :
$fgrepCmd         = "c:\\cygwin\\bin\\grep";

Editing the CGI scripts

4. Editing the Shebang lines

Now to edit the curiously named 'shebang lines' at the top of the TWiki CGI scripts...

  • You must use the Cygwin shell to do this (unless you are a Perl expert) - don't use the Windows command shell, cmd.exe (aka DOS Prompt)
  • Then do the following, which quickly edits the 19 or so files, using Perl - the important lines are in bold.
  • Type the Perl line very carefully
    • If you do mis-type the perl line, you can restore from the .backup directory and re-run the command, as it will only edit the original files, not the backups with '~' suffixes. 

$ cd /twiki/bin

$ ls
attach   geturl         oops     rdiff     save        testenv  viewfile
changes  installpasswd  passwd   register  search      upload
edit     mailnotify     preview  rename    statistics  view

$ mkdir .backup 
$ cp * .backup

$ head -1 view
#!/usr/bin/perl -wT

$ perl -pi~ -e 's;#!/usr/bin/perl;#!c:/cygwin/bin/perl;' *[a-z]

$ head -1 view
#!c:/cygwin/bin/perl -wT

$ ls
attach    geturl          oops      rdiff      save         testenv   viewfile~
attach~   geturl~         oops~     rdiff~     save~        testenv~  view~
changes   installpasswd   passwd    register   search       upload
changes~  installpasswd~  passwd~   register~  search~      upload~
edit      mailnotify      preview   rename     statistics   view
edit~     mailnotify~     preview~  rename~    statistics~  viewfile

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

As an interlude, 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): 

         return $user . ':{SHA}' . MIME::Base64::encode_base64(Digest::SHA1::sha1($passwd));

Perl module installation

6. Installing required Perl modules

Some additional Perl modules are needed for the register script to work properly. 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. Here's what you need to do:

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): 

...
(28) Turkey
(29) Ukraine
(30) United Kingdom

Select your country (or several nearby countries) [] 30

(1) ftp://cpan.teleglobe.net/pub/CPAN
(2) ftp://ftp.clockerz.net/pub/CPAN/
(3) ftp://ftp.demon.co.uk/pub/CPAN/
(4) ftp://ftp.flirble.org/pub/languages/perl/CPAN/
(5) ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
(6) ftp://ftp.plig.org/pub/CPAN/
(7) ftp://mirror.uklinux.net/pub/CPAN/
(8) ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
(9) ftp://usit.shef.ac.uk/pub/packages/CPAN/
Select as many URLs as you like,
put them on one line, separated by blanks [] 4 7 8

Enter another URL or RETURN to quit: []
New set of picks:
  ftp://ftp.flirble.org/pub/languages/perl/CPAN/
  ftp://mirror.uklinux.net/pub/CPAN/
  ftp://sunsite.doc.ic.ac.uk/packages/CPAN/

Eventually, you'll get to the CPAN tool'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::SMTP
May 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::SHA1
Lots 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::Base64
May already be installed.

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...) 

$ cd /twiki/data

$ : Make a backup of all files
$ tar czvf all-files.tar.gz */*

$ : Test edit a single file to check your typing
$ perl -pi~~~ -e 'NR <= 10 && s/nobody:/system:/ ' Main/WebIndex.txt,v

$ diff Main/WebIndex.txt,v Main/WebIndex.txt,v~~~
5c5
<       system:1.2; strict;
---
>       nobody:1.2; strict;

$ : Now edit all the RCS files at once - use cursor-up to recall previous command
$ perl -pi~~~ -e 'NR <= 10 && s/nobody:/system:/ ' */*,v

$ : Check for any remaining files not edited
$ grep 'strict;$' */*,v | grep -v system

$ : Clean up - type this very carefully 
$ rm */*~~~

  • 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 to an SMTP email host that is reachable and currently working. Otherwise you'll get a confusing message from TWiki when registering new users or running mailnotify (for WebNotify), along the lines of: 

   Software Error: Can't call method "mail" on an undefined value at ../lib/TWiki/Net.pm line 187.

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
  • 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 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.

See TWiki:Codev.TWikiPatches in case there are patches (i.e. specific code changes) for particular problems that may affect you (e.g. TWiki:Codev.ChangePasswordOnWin2K).

If you find that the Index feature doesn't work, or topic name searches fail, you should check you have set $egrepCmd and $fgrepCmd correctly, as mentioned above.

Permissions

TWiki:Codev.CygWin has several models for how it does security:

  • 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.

Next Steps

See the TWikiInstallationGuide for other setup. In particular, you'll probably want to refer to the section on basic authentication - remember to use c:/twiki type filenames (i.e. Windows format) since you are using Apache for Windows.

Improved authentication

You may want to investigate TWiki:Codev.WindowsInstallModNTLM, which describes how to add an Apache module so that TWiki:Codev.InternetExplorer users are automatically authenticated based on their Windows domain login - this avoids TWiki:Codev.GettingTheUsernameWrong and TWiki:Codev.ForgettingPasswords, which are usually very common among TWiki users.

Improved performance

See TWiki:Codev.WindowsModPerlInstallCookbook and TWiki:Codev.ModPerl for information on installing TWiki under Apache's mod_perl - this is somewhat more complex and follows a different model, so it's best to get some experience with TWiki, Apache and Perl first.

Format of filenames

In your TWiki on Windows installation, it's worth remembering that:

  • Apache configuration files (e.g. the .htaccess file and c:/apache/conf/httpd.conf) always use Windows format paths, with forward slashes, e.g. c:/twiki
  • The same is true for the first line of the TWiki Perl scripts (since this line is interpreted by Apache), e.g. c:/cygwin/bin/perl
  • All other lines in the Perl scripts use Unix format paths, e.g. /twiki (using Cygwin Perl as per this cookbook)
  • 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
  • RCS always uses Unix format paths, e.g. /twiki

Credits

Material in this cookbook is heavily based on the enormous number of contributions in TWiki:Codev.TWikiOnWindowsArchive and related topics - too many people to thank, but have a look at the contributor list to TWiki:Codev.TWikiOnWindowsArchive to get an idea!

People who've tested or reviewed this document and provided valuable feedback include:

ALERT! Comments welcome at TWiki:Codev.WindowsInstallCookbookComments

-- PeterThoeny - 30 Jan 2003

TWiki Upgrade Guide

Upgrade from the previous TWiki 01-Dec-2001 production release to TWiki 01-Feb-2003

Overview

This guide describes how to upgrade from TWiki 01-Dec-2001 to TWiki 01-Feb-2003. The new version involves several new features and numerous enhancements to the previous version.

Upgrade Requirements

  • To upgrade from a 01-Dec-2001 standard installation to the latest 01-Feb-2003 TWiki Production Release, follow the instructions below.

  • To upgrade from a Beta of the new release, or if you made custom modifications to the application, read through all new reference documentation, then use the procedure below as a guideline.

Major Changes from TWiki 01-Dec-2001

  • Form and script to create new webs
  • Enhanced Plugin API to manipulate topic data with new functions in TWikiFuncModule: readTopicText, saveTopicText, setTopicEditLock, checkTopicEditLock
  • New Plugin hooks registrationHandler, beforeEditHandler, afterEditHandler, beforeSaveHandler, writeHeaderHandler, redirectCgiQueryHandler, getSessionValueHandler, setSessionValueHandler
  • Internationalization ('I18N') support 8-bit character sets in WikiWords, such as ISO-8859-15, KOI8-R
  • Possible to omit e-mail address in WebNotify, in which case the e-mail is taken from the user's home page; if the WikiName is a group name, a notification is sent to all members of the group
  • New data storage framework that lets you use external RCS commands for revision control, or a new native Perl implementation that does not depend on the external RCS commands (not recommended yet for production use, see TWiki:Codev/RcsLite)
  • New AND search; with regular expression enabled, use the semicolon ";" as the AND operator in %SEARCH{}% variable, FormattedSearch and WebSearch
  • Many more enhancements, see the complete change log at TWikiHistory

Upgrade Procedure from 01-Dec-2001 to 01-Feb-2003 Release

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

  1. Back up and prepare:
    • Back up all existing TWiki directories $TWIKIROOT/bin, $TWIKIROOT/pub, $TWIKIROOT/data, $TWIKIROOT/templates, $TWIKIROOT/lib.
    • Create a temporary directory and unpack the ZIP file there.
  2. Update files in TWiki root:
    • Overwrite all *.html and *.txt files in $TWIKIROOT with the new ones.
  3. Update template files:
    • Overwrite all template files in $TWIKIROOT/templates with the new ones.
      • If you have customized your templates, make sure to merge those changes to the new files.
    • If you have customized skins or loaded new skins, make sure to merge or apply those changes to the new files.
    • Specific changes to templates and skins:
      • Replace %WIKIHOMEURL% with %WIKILOGOURL%
      • Replace img tag's src=%PUBURLPATH%/wikiHome.gif with src=%WIKILOGOIMG%
      • Replace img tag's alt="TWiki Home" with alt="%WIKILOGOALT%"
      • Replace meta tag's charset=iso-8859-1" with charset=iso-8859-15"
      • Add %TOPIC% to form action of GoBox
      • For internationalized sites, URL encode webs and topics in all form actions, e.g. replace .../view%SCRIPTSUFFIX%/%WEB%/%TOPIC%" with .../view%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%/%TOPIC%"}%
  4. Update script files:
    • Overwrite all script files in $TWIKIROOT/bin with the new ones.
      • If necessary, change the script names to include the required extension, e.g. .cgi
    • Edit $TWIKIROOT/bin/setlib.cfg and point $twikiLibPath to the absolute file path of $TWIKIROOT/lib
    • Edit $TWIKIROOT/bin/.htaccess to include a directive for the new manage script:
      <Files "manage">
          require valid-user
      </Files>
    • Pay attention to the file and directory permissions, the scripts need to be executable, e.g. chmod 775 $TWIKIROOT/bin/*
    • If on Non-Unix host, make sure the correct path to the perl interpreter is changed in the first line of every script file. See also WindowsInstallCookbook.
  5. Update library files:
    • Overwrite the TWiki.cfg configuration file in $TWIKIROOT/lib with the new one.
    • Restore the configuration values from the backup. You typically need to configure just the ones in the section "variables that need to be changed when installing on a new server".
    • Overwrite the TWiki.pm library in $TWIKIROOT/lib with the new one.
    • Copy and overwrite all subdirectories below $TWIKIROOT/lib with the new ones. Make sure to preserve any extra Plugins you might have in $TWIKIROOT/lib/TWiki/Plugins
    • Pay attention to the file and directory permissions, the library files should not be executable, e.g. chmod -R 664 $TWIKIROOT/lib/*
  6. Update data files:
    • Run the bin/testenv script from the browser (e.g. http://localhost/bin/testenv) to verify if the cgi-scripts are running as user nobody.
      • In case not: The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed to the user of your cgi-scripts, e.g. www-data:
      • Change the lock user in the temporary twiki/data/* directories where you unzipped the installation package: A simple way to switch the locker of the RCS files is to use sed in the :
        for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done
    • In the temporary twiki/data/TWiki directory where you unzipped the installation package:
      • Remove the files you do not want to upgrade: InterWikis.*, TWikiRegistration.*, TWikiRegistrationPub.*, WebNotify.*, WebPreferences.*, WebStatistics.* and all WebTopic* files.
    • Rename in the temporary directory the file $TWIKIROOT/data/TWiki/TWikiPreferences.* to TWikiPreferencesSave.*.
    • Move all remaining *.txt and *.txt,v files from the temporary data/TWiki directory to your $TWIKIROOT/data/TWiki directory, overwriting the existing ones.
    • Merge your original TWikiPreferencesSave.txt settings into $TWIKIROOT/data/TWiki/TWikiPreferences.txt.
    • Move the data/_default directory from the temporary location to your $TWIKIROOT/data directory.
    • Move the data/Sandbox directory from the temporary location to your $TWIKIROOT/data directory
      (The Test web has been renamed to Sandbox in this release.)
      • There are now two webs in parallel (Test and Sandbox) for the purpose of testing (experimenting) TWiki.
        Move all relevant topics from Test web to Sandbox web, or motivate the users to do.
    • Make sure that the directories and files below $TWIKIROOT/data are writable by your cgi-script user.
  7. Adapt the other webs (all other than TWiki and _default):
    • Merge the new files WebHome.txt and WebPreferences.txt of your other webs to make sure, you have the improvements applied also in your other webs.
  8. Update pub files:
    • Move all subdirectories below pub/TWiki from your temporary directory into your $TWIKIROOT/pub/TWiki directory.
    • 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.
  9. Update TWikiPreferences to authorize users to create webs:
    • Add ALLOWWEBMANAGE to the FINALPREFERENCES list so that nobody can overwrite the setting:
      • Set FINALPREFERENCES = WIKIWEBMASTER, PREVIEWBGIMAGE, SMTPMAILHOST, SMTPSENDERHOST, ALLOWWEBMANAGE
    • Set users or groups allowed to create new webs:
  10. Verify installation:
    • Execute the $TWIKIROOT/bin/testenv script from your browser (e.g. http://localhost/bin/testenv) to see if it reports any issues; fix 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 TextFormattingRules.

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

-- PeterThoeny - 01 Feb 2002
-- MartinRaabe? - 15 Jan 2003

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 three standard options for controlling user access:

  1. 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.
  2. Use SSL (Secure Sockets Layer; HTTPS) to authenticate and secure the whole server.
  3. Use Basic Authentication (.htaccess) to control access by protecting key scripts: attach, edit=, installpasswd, preview, rename, save, upload using the .htaccess file. The TWikiInstallationGuide has step-by-step instructions.

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.

  • ALERT! 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:

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.

BlinkenArea internally manages two usernames: Login Username and TWiki Username.

  • 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.

  • ALERT! 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. verification and clearer rewrite to follow in a bit. also link to original installation mention.

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 BlinkenArea.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.

Change password



Sorry, this function is disabled

Please contact STephanKambor or StefanSchuermans for a new password.

Packaging and Publishing Skins

See TWiki:Plugins/SkinPackagingHowTo

Activating Skins

A skin can be activated in two ways:

The ?skin=name URL parameter overrides the SKIN Preference value.

-- PeterThoeny - 05 Jan 2003

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

Variables that can be used in the format string:

Name: Expands To:
$web Name of the web
$topic Topic name
$topic(20) Topic name, "- " hyphenated each 20 characters
$topic(30, -<br />) Topic name, hyphenated each 30 characters with separator "-<br />"
$topic(40, ...) Topic name, shortended to 40 characters with "..." indication
$text Formatted topic text
$locked LOCKED flag (if any)
$date Time stamp of last topic update, like 25 Aug 2008 - 12:31
$isodate Time stamp of last topic update, like 2008-08-25T12:31Z
$rev Number of last topic revision, like 1.4
$wikiusername Wiki user name of last topic update, like Main.JohnSmith
$username User name of last topic update, like JohnSmith
$summary Topic summary
$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. For example, $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the email address from a bullet of format * Email: ....
$n or $n() New line
$nop or $nop() Is a "no operation". This variable gets removed; useful for nested search
$quot Double quote ("). Alternatively write \" to escape it
$percnt Percent sign (%)
$dollar Dollar sign ($)

Note: For $pattern(reg-exp), specify a RegularExpression that scans from start to end and contains the text you want to keep in parenthesis, like $pattern(.*?(from here.*?to here).*). You need to make sure that the integrity of a web page is not compromised; for example, if you include a table make sure to include everything including the table end tag.

Examples

Bullet list showing topic name and summary

Write this:

%SEARCH{ "FAQ" scope="topic" nosearch="on" nototal="on" header="   * *Topic: Summary:*" format="   * [[$topic]]: $summary" }%

To get this:

  • Topic: Summary:
  • TWikiFAQ: Frequently Asked Questions About TWiki This is a real FAQ, and also a demo of one easily implemented knowledge base solution. See how it's done, click Edit . SEARCH ...
  • TWikiFaqTemplate: FAQ: Answer: Back to: NOP TWikiFAQ WIKIUSERNAME DATE
  • TextFormattingFAQ: Text Formatting FAQ The most frequently asked questions about text formatting are answered. Also, TextFormattingRules contains the complete TWiki shorthand system ...

Table showing form field values of topics with a form

Write this in the Know web:

| *Topic:* | *OperatingSystem:* | *OsVersion:* |
%SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" scope="text" regex="on" nosearch="on" nototal="on" format="| [[$topic]] | $formfield(OperatingSystem) | $formfield(OsVersion) |" }%

To get this:

Topic: OperatingSystem: OsVersion:
IncorrectDllVersionW32PTH10DLL OsWin 95/98
WinDoze95Crash OsWin 95

Extract some text from a topic using regular expression

Write this:

%SEARCH{ "__Back to\:__ TWikiFAQ" scope="text" regex="on" nosearch="on" nototal="on" header="TWiki FAQs:" format="   * $pattern(.*?FAQ\:[\n\r]*([^\n\r]+).*) [[$topic][Answer...]]" }%

To get this:

TWiki FAQs:

  • How do I delete or rename a topic? Answer...
  • How do I delete or rename a file attachment? Answer...
  • Why does the topic revision not increase when I edit a topic? Answer...
  • Why does this Wiki scramble the email-adresses? Answer...
  • TWiki has a GPL (GNU General Public License). What is GPL? Answer...
  • How do you log off? Suppose I log in with the guest username but later I want to use another username, how do I log off from the guest user name? Answer...
  • My pages always have very big spaces between paragraphs when i use HTML-Tags in the Wiki-editor Answer...
  • I've problems with the WebSearch. There is no Search Result on any inquiry. By clicking the Index topic it's the same problem. Answer...
  • What happens if two of us try to edit the same topic simultaneously? Answer...
  • I would like to install TWiki on my server. Can I get the source? Answer...
  • So what is this WikiWiki thing exactly? Answer...
  • 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).

  • First search:
    • %SEARCH{ "culture" format="   * $topic is referenced by: (list all references)" nosearch="on" nototal="on" }%
  • Second search. For each hit we want this search:
    • %SEARCH{ "(topic found in first search)" format="   $topic" nosearch="on" nototal="on" }%
  • 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:
    • Use $percnt to escape the leading percent of the second search
    • Use \" to escape the double quotes
    • Use $dollar to escape the $ of $topic
    • Use $nop to escape the }% sequence

Write this:

%SEARCH{ "culture" format="   * $topic is referenced by:$n      * $percntSEARCH{ \"$topic\" format=\"   $dollartopic\" nosearch=\"on\" nototal=\"on\" }$nop%" nosearch="on" nototal="on" }%

To get this:

-- PeterThoeny - 16 May 2002

TWiki Meta Data

Additional topic data, program-generated or from TWikiForms, is stored in META variable name/value pairs

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_%.

Example of Format 
%META:TOPICINFO{version="1.6" date="976762663" author="PeterThoeny" format="1.0"}%
   text of the topic
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
   by="JohnTalintyre" date="976762680"}%
%META:TOPICPARENT{name="NavigationByTopicContext"}%
%META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
%META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
%META:FORM{name="WebFormTemplate"}%
%META:FIELD{name="OperatingSystem" value="OsWin"}%
%META:FIELD{name="TopicClassification" value="PublicFAQ"}%

Meta Data Specifications

The current version of Meta Data is 1.0, with support for the following variables.

META:TOPICINFO

Key Comment
version Same as RCS version
date integer, unx time, seconds since start 1970
author last to change topic, is the REMOTE_USER
format Format of this topic, will be used for automatic format conversion

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:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%

Key Comment
from Full name, i.e., web.topic
to Full name, i.e., web.topic
by Who did it, is the REMOTE_USER, not WikiName
date integer, unx time, seconds since start 1970

Notes:

  • at present version number is not supported directly, it can be inferred from the RCS history.
  • there is only one META:TOPICMOVED in a topic, older move information can be found in the RCS history.

META:TOPICPARENT

Key Comment
name 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.

META:FILEATTACHMENT

Key Comment
name Name of file, no path. Must be unique within topic
version Same as RCS revision
path Full path file was loaded from
size In bytes
date integer, unx time, seconds since start 1970
user the REMOTE_USER, not WikiName
comment As supplied when file uploaded
attr h if hidden, optional

Extra fields that are added if an attachment is moved:

Key Comment
movedfrom full topic name - web.topic
movedby the REMOTE_USER, not WikiName
movedto full topic name - web.topic
moveddate integer, unx time, seconds since start 1970

META:FORM

Key Comment
name A topic name - the topic represents one of the TWikiForms. Can optionally include the web name (i.e., web.topic), but doesn't normally

META:FIELD

Should only be present if there is a META:FORM entry. Note that this data is used when viewing a topic, the form template definition is not read.

Key Name
name Ties to entry in TWikiForms template, is title with all bar alphanumerics and . removed
title Full text from TWikiForms template
value Value user has supplied via form

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
  • text of topic
  • META:TOPICMOVED (optional)
  • META:TOPICPARENT (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.

Current support covers:

Variable usage: Comment:
%META{"form"}% Show form data, see TWikiForms.
%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.

-- JohnTalintyre? - 29 Aug 2001
-- MikeMannix? - 03 Dec 2001
-- PeterThoeny - 10 Jan 2002

TWiki Plugins

Plug-in enhanced feature add-ons, with a Plugin API for developers

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 three 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.

  • InterwikiPlugin is preinstalled but can be disabled or removed. 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.

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:

  1. Download the zip file containing the Plugin, documentation, and any other required files, from TWiki:Plugins.
  2. 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.
  3. 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.
  • Dev page: Post feature requests, bug reports and general dev comments; topic title ends in Dev (SomePluginDev).
  • User support: Post installation, how to use type questions (and answers, if you have them) in the TWiki:Support web.

On-Site Pretesting

To test new Plugins on your installation before making them public, you may want to use one of these two approaches:

  • Method 1: Safely test on-the-fly by creating separate Production and Test branches in your live TWiki installation.
    • Duplicate the twiki/bin and twiki/lib directories for the Test version, adjusting the paths in the new lib/TWiki.cfg, the twiki/data; the twiki/templates and twiki/pub directories are shared.
    • Test Plugins and other new features in the Test installation until you're satisfied.
      • ALERT! If you modify topics using the new features, live users will likely see unfamiliar new META tags showing up on their pages - to avoid this, create and edit test-only topics to try out new features.
    • Copy the modified files to the Production installation. You can update a TWiki installation live and users won't even notice.

  • Method 2: List the Plugin being tested in the DISABLEDPLUGINS variable in TWikiPreferences. Redefine the DISABLEDPLUGINS variable in the Sandbox web and do the testing there.

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 BlinkenArea 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:

  1. One line description, used to form the bullets describing the Plugins in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Blah blah woof woof.
  2. 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 %ACTIVATEDPLUGINS% variable lists activated Plugins by name. (This variable is displayed in TWikiPreferences for debugging use.)
  • 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.

DEMO: Automatically List Active Plugins Using Variables

Using %ACTIVATEDPLUGINS%:
On this TWiki site, the active Plugins are: DefaultPlugin, CommentPlugin, EditTablePlugin, InterwikiPlugin, RenderListPlugin, SlideShowPlugin, SmiliesPlugin, SpreadSheetPlugin, TablePlugin.

Using %PLUGINDESCRIPTIONS%:
You can use any of these active TWiki Plugins:

  • DefaultPlugin: This plugin can be used to specify some simple custom rendering rules. It also renders deprecated *_text_* as bold italic text.
  • CommentPlugin: Allows users to quickly post comments to a page without an edit/preview/save cycle.
  • EditTablePlugin: Edit TWiki tables using edit fields, date pickers and drop down boxes
  • InterwikiPlugin: Link ExternalSite:Page text to external sites based on aliases defined in the InterWikis topic.
  • RenderListPlugin: Render bullet lists in a variety of formats
  • SlideShowPlugin: Create web based presentations based on topics with headings.
  • SmiliesPlugin: Render smilies as icons, like  %:-)% for smile or  :cool: for cool!
  • SpreadSheetPlugin: Add spreadsheet calculation like "$SUM( $ABOVE() )" to tables located in BlinkenArea topics.

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.

ALERT! 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.

Plugin Version Detection

To eliminate the incompatibility problems bound to arise from active open Plugin development, a Plugin versioning system and an API GetVersion detection routine are 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).

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: 

  use TWiki::Plugins::MyFirstPlugin::Attrs;
  $var = MyFirstPlugin::Attrs->new();

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:

  1. Copy the Plugin topic template from TWiki.org. To copy the text, go to TWiki:Plugins/PluginPackage and:
    • enter the Plugin name in the "How to Create a Plugin" section
    • click Create
    • select all in the Edit box & copy
    • Cancel the edit
    • go back to your site to the TWiki web
    • In the GoBox enter your Plugin name, for example MyFirstPlugin, press enter and create the new topic
    • paste & save new Plugin topic on your site
  2. Customize your Plugin topic.
    • In case you plan to publish your Plugin at TWiki.org, use Interwiki names for author names, like TWiki:Main/TWikiGuest.
  3. Save your topic, for use in packaging and publishing your Plugin.

OUTLINE: Doc Topic Contents
Check the Plugins web on TWiki.org for the latest Plugin doc topic template. Here's a quick overview of what's covered:

Syntax Rules: <Describe any special text formatting that will be rendered.>"

Example: <Include an example of the Plugin in action. Possibly include a static HTML version of the example to compare if the installation was a success!>"

Plugin Global Settings: <Description and settings for custom Plugin %VARIABLES%, and those required by TWiki.>"

  • Plugins Preferences <If user settings are needed, explain... Entering values works exactly like TWikiPreferences and WebPreferences: six (6) spaces and then:>"
    • Set <EXAMPLE = value added>

Plugin Installation Instructions: <Step-by-step set-up guide, user help, whatever it takes to install and run, goes here.>"

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).

  1. 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]
  2. 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. Publish your Plugin in three steps:

  1. Post the Plugin documentation topic in the TWiki:Plugins web:
  2. Attach the distribution zip file to the topic, ex: MyFirstPlugin.zip
  3. 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.)

-- AndreaSterbini? - 29 May 2001
-- PeterThoeny - 29 Jan 2003
-- MikeMannix? - 03 Dec 2001

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.

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

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

getSkin( ) ==> $skin

Description: Get the name of the skin, set by the SKIN preferences variable or the skin CGI parameter
Return: $skin Name of skin, e.g. "gnu". Empty string if none

getUrlHost( ) ==> $host

Description: Get protocol, domain and optional port of script URL
Return: $host URL host, e.g. "http://example.com:80"

getScriptUrl( $web, $topic, $script ) ==> $url

Description: Compose fully qualified URL
Parameter: $web Web name, e.g. "Main"
Parameter: $topic Topic name, e.g. "WebNotify"
Parameter: $script Script name, e.g. "view"
Return: $url URL, e.g. "http://example.com:80/cgi-bin/view.pl/Main/WebNotify"

getScriptUrlPath( ) ==> $path

Description: Get script URL path
Return: $path URL path of TWiki scripts, e.g. "/cgi-bin"

getViewUrl( $web, $topic ) ==> $url

Description: Compose fully qualified view URL
Parameter: $web Web name, e.g. "Main". The current web is taken if empty
Parameter: $topic Topic name, e.g. "WebNotify"
Return: $url URL, e.g. "http://example.com:80/cgi-bin/view.pl/Main/WebNotify"

getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) ==> $url

Description: Compose fully qualified "oops" dialog URL
Parameter: $web Web name, e.g. "Main". The current web is taken if empty
Parameter: $topic Topic name, e.g. "WebNotify"
Parameter: $template Oops template name, e.g. "oopslocked"
Parameter: $param1 ... $param4 Parameter values for %PARAM1% ... %PARAM4% variables in template, optional
Return: $url URL, e.g. "http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked&param1=joe"

getPubUrlPath( ) ==> $path

Description: Get pub URL path
Return: $path URL path of pub directory, e.g. "/pub"

getCgiQuery( ) ==> $query

Description: Get CGI query object. Important: Plugins cannot assume that scripts run under CGI, Plugins must always test if the CGI query object is set
Return: $query CGI query object; or 0 if script is called as a shell script

writeHeader( $query )

Description: Prints a basic content-type HTML header for text/html to standard out
Parameter: $query CGI query object
Return: none

redirectCgiQuery( $query, $url )

Description: Redirect to URL
Parameter: $query CGI query object
Parameter: $url URL to redirect to
Return: none, never returns

Functions: Preferences

extractNameValuePair( $attr, $name ) ==> $value

Description: Extract a named or unnamed value from a variable parameter string
Parameter: $attr Attribute string
Parameter: $name Name, optional
Return: $value Extracted value

  • Example:
    • Variable: %TEST{ "nameless" name1="val1" name2="val2" }%
    • First extract text between {...} to get: "nameless" name1="val1" name2="val2"
    • Then call this on the text:
      my $noname = TWiki::Func::extractNameValuePair( $text );
      my $name1  = TWiki::Func::extractNameValuePair( $text, "name1" );
      my $name2  = TWiki::Func::extractNameValuePair( $text, "name2" );

getPreferencesValue( $key, $web ) ==> $value

Description: Get a preferences value from TWiki or from a Plugin
Parameter: $key Preferences key
Parameter: $web Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
Return: $value Preferences value; empty string if not set

  • Example for Plugin setting:
    • MyPlugin topic has: * Set COLOR = red
    • Use "MYPLUGIN_COLOR" for $key
    • my $color = TWiki::Func::getPreferencesValue( "MYPLUGIN_COLOR" );

  • Example for preferences setting:
    • WebPreferences topic has: * Set WEBBGCOLOR = #FFFFC0
    • my $webColor = TWiki::Func::getPreferencesValue( "WEBBGCOLOR", "Sandbox" );

getPreferencesFlag( $key, $web ) ==> $value

Description: Get a preferences flag from TWiki or from a Plugin
Parameter: $key Preferences key
Parameter: $web Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
Return: $value Preferences flag "1" (if set), or "0" (for preferences values "off", "no" and "0")

  • Example for Plugin setting:
    • MyPlugin topic has: * Set SHOWHELP = off
    • Use "MYPLUGIN_SHOWHELP" for $key
    • my $showHelp = TWiki::Func::getPreferencesFlag( "MYPLUGIN_SHOWHELP" );

getWikiToolName( ) ==> $name

Description: Get toolname as defined in TWiki.cfg
Return: $name Name of tool, e.g. "TWiki"

getMainWebname( ) ==> $name

Description: Get name of Main web as defined in TWiki.cfg
Return: $name Name, e.g. "Main"

getTwikiWebname( ) ==> $name

Description: Get name of TWiki documentation web as defined in TWiki.cfg
Return: $name Name, e.g. "TWiki"

Functions: User Handling and Access Control

getDefaultUserName( ) ==> $loginName

Description: Get default user name as defined in TWiki.cfg's $defaultUserName
Return: $loginName Default user name, e.g. "guest"

getWikiName( ) ==> $wikiName

Description: Get Wiki name of logged in user
Return: $wikiName Wiki Name, e.g. "JohnDoe"

getWikiUserName( $text ) ==> $wikiName

Description: Get Wiki name of logged in user with web prefix
Return: $wikiName Wiki Name, e.g. "Main.JohnDoe"

wikiToUserName( $wikiName ) ==> $loginName

Description: Translate a Wiki name to a login name based on Main.TWikiUsers topic
Parameter: $wikiName Wiki name, e.g. "Main.JohnDoe" or "JohnDoe"
Return: $loginName Login name of user, e.g. "jdoe"

userToWikiName( $loginName, $dontAddWeb ) ==> $wikiName

Description: Translate a login name to a Wiki name based on Main.TWikiUsers topic
Parameter: $loginName Login name, e.g. "jdoe"
Parameter: $dontAddWeb Do not add web prefix if "1"
Return: $wikiName Wiki name of user, e.g. "Main.JohnDoe" or "JohnDoe"

isGuest( ) ==> $flag

Description: Test if logged in user is a guest
Return: $flag "1" if yes, "0" if not

permissionsSet( $web ) ==> $flag

Description: Test if any access restrictions are set for this web, ignoring settings on individual pages
Parameter: $web Web name, required, e.g. "Sandbox"
Return: $flag "1" if yes, "0" if no

checkAccessPermission( $type, $wikiName, $text, $topic, $web ) ==> $flag

Description: Check access permission for a topic based on the TWiki.TWikiAccessControl rules
Parameter: $type Access type, e.g. "VIEW", "CHANGE", "CREATE"
Parameter: $wikiName WikiName of remote user, i.e. "Main.PeterThoeny"
Parameter: $text Topic text, optional. If empty, topic $web.$topic is consulted
Parameter: $topic Topic name, required, e.g. "PrivateStuff"
Parameter: $web Web name, required, e.g. "Sandbox"
Return: $flag "1" if access may be granted, "0" if not

Functions: Content Handling

webExists( $web ) ==> $flag

Description: Test if web exists
Parameter: $web Web name, required, e.g. "Sandbox"
Return: $flag "1" if web exists, "0" if not

topicExists( $web, $topic ) ==> $flag

Description: Test if topic exists
Parameter: $web Web name, optional, e.g. "Main"
Parameter: $topic Topic name, required, e.g. "TokyoOffice", or "Main.TokyoOffice"
Return: $flag "1" if topic exists, "0" if not

getRevisionInfo( $web, $topic ) ==> ( $date, $loginName, $rev )

Description: Get revision info of a topic
Parameter: $web Web name, optional, e.g. "Main"
Parameter: $topic Topic name, required, e.g. "TokyoOffice"
Return: ( $date, $loginName, $rev ) List with: ( last update date, login name of last user, minor part of top revision number ), e.g. ( "01 Jan 2003", "phoeny", "5" )

checkTopicEditLock( $web, $topic ) ==> ( $oopsUrl, $loginName, $unlockTime )

Description: Check if topic has an edit lock by a user
Parameter: $web Web name, e.g. "Main", or empty
Parameter: $topic Topic name, e.g. "MyTopic", or "Main.MyTopic"
Return: ( $oopsUrl, $loginName, $unlockTime ) The $oopsUrl for calling redirectCgiQuery(), user's $loginName, and estimated $unlockTime in minutes. The $oopsUrl and $loginName is empty if topic has no edit lock.

setTopicEditLock( $web, $topic, $lock ) ==> $oopsUrl

Description: Lock topic for editing, or unlock when done
Parameter: $web Web name, e.g. "Main", or empty
Parameter: $topic Topic name, e.g. "MyTopic", or "Main.MyTopic"
Parameter: $lock Set to 1 to lock topic, 0 to unlock
Return: $oopsUrl Empty string if OK; the $oopsUrl for calling redirectCgiQuery() in case lock is already taken when trying to lock topic

readTopicText( $web, $topic, $rev, $ignorePermissions ) ==> $text

Description: Read topic text, including meta data
Parameter: $web Web name, e.g. "Main", or empty
Parameter: $topic Topic name, e.g. "MyTopic", or "Main.MyTopic"
Parameter: $rev Topic revision to read, optional. Specify the minor part of the revision, e.g. "5", not "1.5"; the top revision is returned if omitted or empty.
Parameter: $ignorePermissions Set to "1" if checkAccessPermission() is already performed and OK; an oops URL is returned if user has no permission
Return: $text Topic text with embedded meta data; an oops URL for calling redirectCgiQuery() is returned in case of an error

saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) ==> $oopsUrl

Description: Save topic text, typically obtained by readTopicText(). Topic data usually includes meta data; the file attachment meta data is replaced by the meta data from the topic file if it exists.
Parameter: $web Web name, e.g. "Main", or empty
Parameter: $topic Topic name, e.g. "MyTopic", or "Main.MyTopic"
Parameter: $text Topic text to save, assumed to include meta data
Parameter: $ignorePermissions Set to "1" if checkAccessPermission() is already performed and OK
Parameter: $dontNotify Set to "1" if not to notify users of the change
Return: $oopsUrl Empty string if OK; the $oopsUrl for calling redirectCgiQuery() in case of error

  • Example:
    my $oopsUrl = TWiki::Func::setTopicEditLock( $web, $topic, 1 );
    if( $oopsUrl ) {
        TWiki::Func::redirectCgiQuery( $query, $oopsUrl );   # assuming valid query
        return;
    }
    my $text = TWiki::Func::readTopicText( $web, $topic );        # read topic text
    # check for oops URL in case of error:
    if( $text =~ /^http.*?\/oops/ ) {
        TWiki::Func::redirectCgiQuery( $query, $text );
        return;
    }
    # do topic text manipulation like:
    $text =~ s/old/new/g;
    # do meta data manipulation like:
    $text =~ s/(META\:FIELD.*?name\=\"TopicClassification\".*?value\=\")[^\"]*/$1BugResolved/;
    $oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text
    TWiki::Func::setTopicEditLock( $web, $topic, 0 );             # unlock topic
    if( $oopsUrl ) {
        TWiki::Func::redirectCgiQuery( $query, $oopsUrl );
        return;
    }

getPublicWebList( ) ==> @webs

Description: Get list of all public webs, e.g. all webs that do not have the NOSEARCHALL flag set in the WebPreferences
Return: @webs List of all public webs, e.g. ( "Main",  "Know", "TWiki" )

getTopicList( $web ) ==> @topics

Description: Get list of all topics in a web
Parameter: $web Web name, required, e.g. "Sandbox"
Return: @topics Topic list, e.g. ( "WebChanges",  "WebHome", "WebIndex", "WebNotify" )

Functions: Rendering

expandCommonVariables( $text, $topic, $web ) ==> $text

Description: Expand all common %VARIABLES%
Parameter: $text Text with variables to expand, e.g. "Current user is %WIKIUSER%"
Parameter: $topic Current topic name, e.g. "WebNotify"
Parameter: $web Web name, optional, e.g. "Main". The current web is taken if missing
Return: $text Expanded text, e.g. "Current user is TWikiGuest"

renderText( $text, $web ) ==> $text

Description: Render text from TWiki markup into XHTML as defined in TWiki.TextFormattingRules
Parameter: $text Text to render, e.g. "*bold* text and =fixed font="
Parameter: $web Web name, optional, e.g. "Main". The current web is taken if missing
Return: $text XHTML text, e.g. "<b>bold</b> and <code>fixed font</code>"

internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) ==> $text

Description: Render topic name and link label into an XHTML link. Normally you do not need to call this funtion, it is called internally by renderText()
Parameter: $pre Text occuring before the TWiki link syntax, optional
Parameter: $web Web name, required, e.g. "Main"
Parameter: $topic Topic name to link to, required, e.g. "WebNotify"
Parameter: $label Link label, required. Usually the same as $topic, e.g. "notify"
Parameter: $anchor Anchor, optional, e.g. "#Jump"
Parameter: $createLink Set to "1" to add question linked mark after topic name if topic does not exist;
set to "0" to suppress link for non-existing topics
Return: $text XHTML anchor, e.g. "<a href="/cgi-bin/view/Main/WebNotify#Jump">notify</a>"

search text( $text ) ==> $text

Description: This is not a function, just a how-to note. Use: expandCommonVariables("%SEARCH{...}%" );
Parameter: $text Search variable
Return: "$text" Search result in TWiki.FormattedSearch format

formatGmTime( $time, $format ) ==> $text

Description: Format the time to GM time
Parameter: $time Time in epoc seconds
Parameter: $format Format type, optional. Default e.g. "31 Dec 2002 - 19:30", can be "iso" (e.g. "2002-12-31T19:30Z"), "rcs" (e.g. "2001/12/31 23:59:59", "http" for HTTP header format (e.g. "Thu, 23 Jul 1998 07:21:56 GMT")
Return: $text Formatted time string

Functions: File I/O

getDataDir( ) ==> $dir

Description: Get data directory (topic file root)
Return: $dir Data directory, e.g. "/twiki/data"

getPubDir( ) ==> $dir

Description: Get pub directory (file attachment root). Attachments are in $dir/Web/TopicName
Return: $dir Pub directory, e.g. "/htdocs/twiki/pub"

readTemplate( $name, $skin ) ==> $text

Description: Read a template or skin file. Embedded template directives get expanded
Parameter: $name Template name, e.g. "view"
Parameter: $skin Skin name, optional, e.g. "print"
Return: $text Template text

readFile( $filename ) ==> $text

Description: Read text file, low level. NOTE: For topics use readTopicText()
Parameter: $filename Full path name of file
Return: $text Content of file

saveFile( $filename, $text )

Description: Save text file, low level. NOTE: For topics use saveTopicText()
Parameter: $filename Full path name of file
Parameter: $text Text to save
Return: none

writeWarning( $text )

Description: Log Warning that may require admin intervention to data/warning.txt
Parameter: $text Text to write; timestamp gets added
Return: none

writeDebug( $text )

Description: Log debug message to data/debug.txt
Parameter: $text Text to write; timestamp gets added
Return: none

Copyright and License

Copyright (C) 2000-2003 Peter Thoeny, Peter@Thoeny*-r-e-m-o-v-e-*.com

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

-- PeterThoeny - 31 Dec 2002

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.

TWiki handles WebNotify entries that include the WikiName of a user or a TWikiGroup and an optional e-mail address. Example entries in WebNotify: 

    * 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

BlinkenArea 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.

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

  • TIP 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
15,45 * * * * (cd ~twiki/public_html/bin; ./mailnotify -q)
The above line will call mailnotify at 15 minutes and 45 minutes past every hour. 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 (as of 2001-11-20, none of them free).

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 entries in file twiki/data/log<date>.txt .
    • 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 most systems. Example crontab entry:
      0 0 * * * (cd /path/to/TWiki/bin; ./statistics >/dev/null 2>&1)
    • There is a workaround in case you can't run the script as user nobody : Run the utility twiki/bin/geturl in your cron job and specify the URL of the twiki/bin/statistics script as a parameter. Example:
      0 0 * * * (cd /path/to/TWiki/bin; ./geturl mydomain.com /urlpath/to/TWiki/bin/statistics >/dev/null 2>&1)

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

WebSearch

WebSearch is an extremely fast and flexible search facility, part of the core TWiki feature set. Options include:

  • topic title or full-text search
  • regular expressions
  • search within web or site-wide
  • index-style A-Z alphabetical listing sorted topic title
  • many more

See also: TWikiVariables for including hard-coded searches in text.

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.: 

%SEARCH{".*" web="TWiki" regex="on" nosearch="on" order="modified" 
reverse="on" limit="50"}%

WebIndex

WebIndex lists all web topics in alphabetical order, with the first couple of lines of text. This is simply a preset SEARCH: 

%SEARCH{"\.*" scope="topic" regex="on" nosearch="on"}%

-- MikeMannix - 01 Dec 2001
-- PeterThoeny - 30 Jan 2003

Managing Topics

Browser-based rename, move, and delete for individual 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

  1. 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:
  2. Move/Delete: Select the target web if other than the current web - choose Trash to delete a topic.
  3. Rename: Enter the new topic name - default is current name
    ALERT! NOTE: You'll be warned if any of the topics to be affected are locked (being edited), or if there is a name conflict.
  4. 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).
  5. 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].
    • HELP 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.

  • ALERT! This can only be done from on the server, not through the browser.
    • TIP 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.

Redirecting from an Old Topic

You can use TWikiMetaData to place a command in the WebTopicViewTemplate and WebTopicNonWikiTemplate that will indicate that a topic has been moved by searching for the tag %META:TOPICMOVED{...}%. Customize something like this: 

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

How Rename/Move Works

  1. %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.
  2. The topic is moved (if locks allow).
  3. References are changed (locks and permissions permitting).
  4. 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.

The following shows some limitations of square bracket processing. 

[[Old Topic]]  => [[NewTopic][Old Topic]]
[[old topic]]  => [[NewTopic][old topic]]
[[old t opic]] => not changed
[[OldTopic]]   => [[NewTopic]]

-- MikeMannix - 27 Dec 2001

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 one or more upper case letters, followed by optional lower case letters or numbers; it cannot be a WikiWord
Based on web: Select a TemplateWeb
Web color: Enter a StandardColors code for the web
Description:
 
 
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.
 

Note: Attachments will NOT get copied over along with their topics. This will be a feature added for the TWiki:Codev/CairoRelease.

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

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 now used to dynamically generate the SiteMap.

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.

NOTE: If you plan to rename the BlinkenArea.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).

  1. 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.
  2. Edit the TWikiPreferences topic: Rename or delete the web from the WIKIWEBLIST variable.
  3. Login to the BlinkenArea server, via Telnet or FTP.
  4. Go to twiki/data and rename or remove the web directory.
  5. Go to twiki/templates and rename or remove the web directory if present.
  6. Go to twiki/pub and rename or remove the web directory if present.

-- MikeMannix - 14 Sep 2001
-- PeterThoeny - 07 Apr 2002
-- GrantBow? - 16 Jan 2003

Appendix A: TWiki Filesystem

Annotated directory and file listings, for the 01-Feb-2003 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:

Directory: Files: Used for:
twiki list Start-up info
twiki/bin list Perl scripts
twiki/lib list Configuration file, main library, Perl system modules, Plugins directory
twiki/pub list Public files (eg: images) and FileAttachments and their RCS histories
twiki/data list Individual topics (page content) and their RCS histories
twiki/templates list HTML templates, used by TWiki scripts

File Descriptions

A rundown of the individual files included in the current distribution, organized by TWiki root directories.

Files in twiki

Application info and the current reference documentation. Full file list:

File: Used for:
index.html Links to launch TWiki after install and for files in this directory
license.txt GNU General Public License and TWiki-specific info
readme.txt General TWiki start-up info with relevant URLs
TWikiDocumentation.html All documentation packaged as a single page
TWikiHistory.html TWiki development timeline: versions, features, developers

Files in twiki/bin

Perl CGI scripts. Full file list:

File: Used for:
.htaccess.txt Authentication. Rename to .htaccess and customize if used
attach Shows the attach file page (FileAttachment)
edit Edit a topic
geturl Fetch URL data
installpasswd Install new password by admin
mailnotify Script called by cron job to notify users of changes
manage Manage script to create new webs
oops Shows an OK or oops dialog
passwd Reset and change password
preview Preview topic after edit
rdiff See differences of topics
register Register new users
rename Rename/move topics and move attachments
save Saves a topic, called by preview
search Displays search results
setlib.cfg Location of the TWiki libraries. Customize if needed
statistics Create statistics topic
testenv Test CGI environment variables
upload Does file upload (FileAttachment)
view View a topic ( the script )
viewfile View a file attachment

Files under twiki/lib

The new lib/TWiki/Plugins directories contain configuration, library and function files, and TWikiPlugins. Full file list:

File: Used for:
TWiki.cfg Main configuration, used by TWiki.pm
TWiki.pm Main TWiki library
TWiki/Access.pm Access control
TWiki/Attach.pm Attachment handling
TWiki/Form.pm Form handling
TWiki/Func.pm Public functions that Plugins may use
TWiki/Meta.pm Meta data in topics
TWiki/Net.pm SMTP mail handling
TWiki/Plugins.pm Plugin handling
TWiki/Prefs.pm Preferences handling
TWiki/Search.pm Search engine, used by wiki.pm
TWiki/Store.pm Back-end storage, *.txt text file and *.txt,v RCS repository file handling
TWiki/Store/RcsFile.pm Generic file handling code, a class
TWiki/Store/RcsWrap.pm Wrappers around RCS executables, a class that inherits from RcsFile
TWiki/Store/RcsLite.pm A Perl RCS implemention, a class that inherits from RcsFile
TWiki/Plugins/DefaultPlugin.pm Handles some legacy rules
TWiki/Plugins/EmptyPlugin.pm Empty plugin, use to create your own
TWiki/Plugins/InterwikiPlugin.pm Use aliases as links for predefined URLs

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:

File: Used for:
favicon.ico ICO file
wikiHome.gif GIF file
icn/_filetypes.txt Lookup table to translate file extension to file type
icn/bat.gif GIF file for file type
icn/bmp.gif GIF file for file type
... ...
TWiki/FileAttachment/Sample.txt TEXT file: sample
TWiki/FileAttachment/Smile.gif GIF image: sample
TWiki/FileAttachment/Smile.gif,v RCS repository for GIF file
TWiki/PreviewBackground/blankltgraybg.gif GIF image
TWiki/PreviewBackground/blankwhitebg.gif GIF image
TWiki/PreviewBackground/previewbg.gif GIF image: Preview view background
TWiki/PreviewBackground/preview2bg.gif GIF image: Alternate preview view background
TWiki/TWikiLogos/twikiRobot121x54.gif GIF image: TWiki logo
... ...
TWiki/TWikiTemplates/testscreen.gif GIF image: Screen shot
TWiki/WabiSabi/wabisabi.gif GIF image: illustration
Know/IncorrectDllVersionW32PTH10DLL/W32PTH10.DLL DLL file: sample

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 four start-up webs - Main, TWiki, Know, 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:

File: Used for:
.htpasswd Basic Authentication (htaccess) users file with username and encrypted password pairs
debug.txt Program-generated messages useful for debugging
mime.types Recognized file formats
warning.txt Diagnostic messages for identifying problems
_default/.changes Per web record of topic changes
_default/.mailnotify Per web timestamp of most recent email notification
_default/WebChanges.txt Display most recent topic changes in web
_default/WebChanges.txt,v Revisions history (RCS)
_default/WebHome.txt Default web home page
_default/WebHome.txt,v Revisions history (RCS)
_default/WebIndex.txt Lists all topics in a web
_default/WebIndex.txt,v Revisions history (RCS)
_default/WebNotify.txt Subscribe/unsubscribe to web changes email alert
_default/WebNotify.txt,v Revisions history (RCS)
_default/WebPreferences.txt Per web Preference Settings
_default/WebPreferences.txt,v Revisions history (RCS)
_default/WebSearch.txt Per web search options
_default/WebSearch.txt,v Revisions history (RCS)
_default/WebStatistics.txt Generates web usage statistics
_default/WebStatistics.txt,v Revisions history (RCS)
_default/WebTopicList.txt Lists all topics in a web in compact format
_default/WebTopicList.txt,v Revisions history (RCS)
... ...

Files in twiki/templates

Templates and skins used to control appearance of topics rendered as Web pages. Full file list:

File: Used for:
attach.tmpl Attach (FileAttachments) control screen
attachagain.tmpl Attachment control screen
attachnew.tmpl Attachment control screen
changeform.tmpl Control screen to change the form in edit mode
changes.tmpl Displays list of recently changed topics
edit.iejs.tmpl Edit window with IE-specific JavaScript
edit.tmpl Main edit window
mailnotify.tmpl Email notification
moveattachment.tmpl Move attachment control screen
oopsaccesschange.tmpl Error message
oopsaccesscreateweb.tmpl Error message
oopsaccessgroup.tmpl Error message
oopsaccessrename.tmpl Error message
oopsaccessview.tmpl Error message
oopsauth.tmpl Error message
oopsbadpwformat.tmpl Error message
oopschangepasswd.tmpl Error message
oopsempty.tmpl Error message
oopslocked.tmpl Error message
oopslockedrename.tmpl Error message
oopsmanage.tmpl Error message
oopsmissing.tmpl Error message
oopsmore.tmpl More topic actions message
oopsmoveerr.tmpl Error message
oopsnoformdef.tmpl Error message
oopsnotwikiuser.tmpl Error message
oopsnoweb.tmpl Error message
oopspreview.tmpl Error message
oopsregemail.tmpl Error message
oopsregexist.tmpl Error message
oopsregpasswd.tmpl Error message
oopsregrequ.tmpl Error message
oopsregthanks.tmpl Error message
oopsregwiki.tmpl Error message
oopsrenameerr.tmpl Error message
oopsrenamenotwikiword.tmpl Error message
oopsresetpasswd.tmpl Error message
oopsrev.tmpl Error message
oopssave.tmpl Error message
oopssaveerr.tmpl Error message
oopssendmailerr.tmpl Error message
oopstopicexists.tmpl Error message
oopsupload.tmpl Error message
oopswrongpassword.tmpl Error message
preview.tmpl Preview Changes screen
rdiff.tmpl Displays text changes before & after Diffs
registernotify.tmpl Registration notification
rename.tmpl Rename/move control screen (choose web & new topic tile
renamebase.tmpl Used by other rename templates
renameconfirm.tmpl Confirms a pre-specified rename, ex: undoing a rename
renamerefs.tmpl 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
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.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.

  • TIP 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._

Directory twiki/bin: 

drwxrwxr-x    2 twiki  twiki        4096 Jan  7 23:56 .
drwxrwxr-x    5 twiki  twiki        4096 Nov 18 12:21 ..
-rw-rw-r--    1 twiki  twiki         979 Aug  3 19:36 .htaccess
-rw-rw-r--    1 twiki  twiki        1598 Jun  1  2002 .htaccess.txt
-rwxrwxr-x    1 twiki  twiki        4986 Jan  4 17:27 attach
-rwxrwxr-x    1 twiki  twiki        3734 Jan  4 17:27 changes
-rwxrwxr-x    1 twiki  twiki        9362 Jan  4 18:04 edit
-rwxrwxr-x    1 twiki  twiki        1878 Jan  4 17:28 geturl
-rwxrwxr-x    1 twiki  twiki        4587 Jan  4 17:28 installpasswd
-rwxrwxr-x    1 twiki  twiki        7231 Jan  6 09:04 mailnotify
-rwxrwxr-x    1 twiki  twiki        6000 Dec 11 01:26 makedistrib
-rwxrwxr-x    1 twiki  twiki        8228 Jan  4 18:25 manage
-rwxrwxr-x    1 twiki  twiki        2445 Jan  4 18:08 oops
-rwxrwxr-x    1 twiki  twiki        6936 Jan  4 18:08 passwd
-rwxrwxr-x    1 twiki  twiki        5820 Jan  4 17:30 preview
-rwxrwxr-x    1 twiki  twiki        9235 Jan  4 17:31 rdiff
-rwxrwxr-x    1 twiki  twiki       10584 Jan  4 18:09 register
-rwxrwxr-x    1 twiki  twiki       14746 Jan  5 00:14 rename
-rwxrwxr-x    1 twiki  twiki        4800 Jan  4 18:09 save
-rwxrwxr-x    1 twiki  twiki        4729 Jan  4 17:32 search
-rw-rw-r--    1 twiki  twiki        1446 Jan  8 01:03 setlib.cfg
-rwxrwxr-x    1 twiki  twiki       19261 Jan  4 17:33 statistics
-rwxrwxr-x    1 twiki  twiki       30626 Jan  4 17:33 testenv
-rwxrwxr-x    1 twiki  twiki       14306 Jan  4 18:11 upload
-rwxrwxr-x    1 twiki  twiki       11414 Jan  5 01:12 view
-rwxrwxr-x    1 twiki  twiki        2944 Jan  5 00:36 viewfile

Directory twiki/templates/: 

drwxrwxr-x    2 twiki  twiki        4096 Dec 11 00:38 .
drwxrwxr-x    4 twiki  twiki        4096 Jan  8 01:03 ..
-rw-rw-r--    1 twiki  twiki        2590 Jan  7 22:53 attach.tmpl
-rw-rw-r--    1 twiki  twiki        1604 Aug  3  2001 attachagain.tmpl
-rw-rw-r--    1 twiki  twiki         449 Aug  3  2001 attachnew.tmpl
-rw-rw-r--    1 twiki  twiki        1276 Dec  9 21:48 changeform.tmpl
-rw-rw-r--    1 twiki  twiki        1620 Dec  9 21:48 changes.tmpl
-rw-rw-r--    1 twiki  twiki       12777 Jan  7 22:54 edit.iejs.tmpl
-rw-rw-r--    1 twiki  twiki        2801 Jan  7 22:54 edit.tmpl
-rw-rw-r--    1 twiki  twiki         975 Dec  9 21:48 mailnotify.tmpl
-rw-rw-r--    1 twiki  twiki        1606 Jan  7 22:54 moveattachment.tmpl
-rw-rw-r--    1 twiki  twiki         570 Aug  1  2001 oopsaccesschange.tmpl
-rw-rw-r--    1 twiki  twiki         596 Apr 13  2002 oopsaccesscreateweb.tmpl
-rw-rw-r--    1 twiki  twiki         586 Aug  1  2001 oopsaccessgroup.tmpl
-rw-rw-r--    1 twiki  twiki         573 Aug  1  2001 oopsaccessrename.tmpl
-rw-rw-r--    1 twiki  twiki         573 Aug  1  2001 oopsaccessview.tmpl
-rw-rw-r--    1 twiki  twiki         997 Nov 11 22:21 oopsauth.tmpl
-rw-rw-r--    1 twiki  twiki         405 Aug  1  2001 oopsbadpwformat.tmpl
-rw-rw-r--    1 twiki  twiki         344 Jul 31  2001 oopschangepasswd.tmpl
-rw-rw-r--    1 twiki  twiki         624 Jul 31  2001 oopsempty.tmpl
-rw-rw-r--    1 twiki  twiki         891 Dec 30 15:51 oopslocked.tmpl
-rw-rw-r--    1 twiki  twiki         589 Dec 30 15:55 oopslockedrename.tmpl
-rw-rw-r--    1 twiki  twiki         678 Apr 12  2002 oopsmanage.tmpl
-rw-rw-r--    1 twiki  twiki         328 Jul 31  2001 oopsmissing.tmpl
-rw-rw-r--    1 twiki  twiki        2352 Apr 13  2002 oopsmngcreateweb.tmpl
-rw-rw-r--    1 twiki  twiki        2322 Jan  7 22:55 oopsmore.tmpl
-rw-rw-r--    1 twiki  twiki         407 Aug  1  2001 oopsmoveerr.tmpl
-rw-rw-r--    1 twiki  twiki        1132 Nov 30  2001 oopsnoformdef.tmpl
-rw-rw-r--    1 twiki  twiki         520 Jan  4 18:21 oopsnotwikiuser.tmpl
-rw-rw-r--    1 twiki  twiki        1495 Apr  7  2002 oopsnoweb.tmpl
-rw-rw-r--    1 twiki  twiki         393 Aug  1  2001 oopspreview.tmpl
-rw-rw-r--    1 twiki  twiki         340 Dec 10 14:14 oopsregemail.tmpl
-rw-rw-r--    1 twiki  twiki         475 Jun 10  2002 oopsregexist.tmpl
-rw-rw-r--    1 twiki  twiki         345 Aug  1  2001 oopsregpasswd.tmpl
-rw-rw-r--    1 twiki  twiki         356 Aug  1  2001 oopsregrequ.tmpl
-rw-rw-r--    1 twiki  twiki         540 Aug  1  2001 oopsregthanks.tmpl
-rw-rw-r--    1 twiki  twiki         679 Aug  1  2001 oopsregwiki.tmpl
-rw-rw-r--    1 twiki  twiki         502 Mar 24  2002 oopsrenameerr.tmpl
-rw-rw-r--    1 twiki  twiki         433 May 19  2002 oopsrenamenotwikiword.tmpl
-rw-rw-r--    1 twiki  twiki         506 Jun 10  2002 oopsresetpasswd.tmpl
-rw-rw-r--    1 twiki  twiki         957 Jan  7 22:55 oopsrev.tmpl
-rw-rw-r--    1 twiki  twiki         774 Aug  1  2001 oopssave.tmpl
-rw-rw-r--    1 twiki  twiki         477 Aug  1  2001 oopssaveerr.tmpl
-rw-rw-r--    1 twiki  twiki         465 Jun 10  2002 oopssendmailerr.tmpl
-rw-rw-r--    1 twiki  twiki         379 Aug  1  2001 oopstopicexists.tmpl
-rw-rw-r--    1 twiki  twiki         342 Jul 31  2001 oopsupload.tmpl
-rw-rw-r--    1 twiki  twiki         364 Aug  1  2001 oopswrongpassword.tmpl
-rw-rw-r--    1 twiki  twiki        2603 Jan  7 22:55 preview.tmpl
-rw-rw-r--    1 twiki  twiki        1719 Jan  7 22:56 rdiff.tmpl
-rw-rw-r--    1 twiki  twiki        1160 Dec  9 21:48 registernotify.tmpl
-rw-rw-r--    1 twiki  twiki         993 Jun 23  2002 rename.tmpl
-rw-rw-r--    1 twiki  twiki        2369 Jan  7 22:56 renamebase.tmpl
-rw-rw-r--    1 twiki  twiki         471 May 31  2002 renameconfirm.tmpl
-rw-rw-r--    1 twiki  twiki         595 May 31  2002 renamerefs.tmpl
-rw-rw-r--    1 twiki  twiki        1818 Jan  7 22:56 search.tmpl
-rw-rw-r--    1 twiki  twiki        1676 Jan  7 22:57 searchbookview.tmpl
-rw-rw-r--    1 twiki  twiki         980 Jan  7 22:57 searchformat.tmpl
-rw-rw-r--    1 twiki  twiki         149 Sep 13  2001 searchmeta.tmpl
-rw-rw-r--    1 twiki  twiki        2071 Jan  7 22:57 searchrenameview.tmpl
-rw-rw-r--    1 twiki  twiki        2284 Dec  9 21:48 twiki.tmpl
-rw-rw-r--    1 twiki  twiki         419 Dec  9 21:48 view.plain.tmpl
-rw-rw-r--    1 twiki  twiki         827 Dec  9 21:48 view.print.tmpl
-rw-rw-r--    1 twiki  twiki         300 Dec 14 17:16 view.rss.tmpl
-rw-rw-r--    1 twiki  twiki        1629 Jan  7 22:58 view.tmpl

Directory twiki/data/: 

drwxrwxr-x    8 nobody nobody       4096 Jan  3 23:50 .
drwxrwxr-x    4 twiki  twiki        4096 Jan  8 01:03 ..
-rw-rw-rw-    1 twiki  twiki         210 Jan 11 15:58 .htpasswd
drwxrwxr-x    2 nobody nobody       4096 Dec 11 02:15 Know
drwxrwxr-x    2 nobody nobody       4096 Jan 11 17:45 Main
drwxrwxr-x    2 nobody nobody       4096 Dec 11 02:15 Sandbox
drwxrwxr-x    2 nobody nobody       8192 Jan 11 22:45 TWiki
drwxrwxr-x    2 nobody nobody       4096 Dec 11 02:15 Trash
drwxrwxr-x    2 nobody nobody       4096 Dec 11 01:01 _default
-rw-rw-rw-    1 twiki twiki            0 Aug  2 14:16 debug.txt
-rw-rw-r--    1 nobody nobody      36630 Jan 11 22:26 log200301.txt
-rw-rw-r--    1 twiki twiki         3419 Aug 13  2001 mime.types
-rw-rw-rw-    1 twiki twiki         1320 Dec 11 00:18 warning.txt

Partial file list for twiki/data/Main:

  • TIP Included files come with their RCS versions histories .txt,v. 

drwxrwxr-x    2 nobody nobody       4096 Jan 11 17:45 .
drwxrwxr-x    8 nobody nobody       4096 Jan  3 23:50 ..
-rw-rw-rw-    1 twiki  twiki        3662 Jan 11 16:29 .changes
-rw-rw-rw-    1 twiki  twiki           9 Oct 25  2001 .mailnotify
-rw-r--r--    1 nobody nobody        280 Dec 15  2000 TokyoOffice.txt
-rw-r--r--    1 nobody nobody        774 Dec 15  2000 TokyoOffice.txt,v
-rw-r--r--    1 nobody nobody        124 Aug 16  2001 WebChanges.txt
-r--r--r--    1 nobody nobody        526 Aug 16  2001 WebChanges.txt,v
-rw-r--r--    1 nobody nobody       1721 Jun 28  2002 WebHome.txt
-r--r--r--    1 nobody nobody      11314 Jun 28  2002 WebHome.txt,v
-rw-r--r--    1 nobody nobody        176 Nov 24  2001 WebIndex.txt
-r--r--r--    1 nobody nobody        483 Nov 24  2001 WebIndex.txt,v
-rw-r--r--    1 nobody nobody        729 Mar 24  2001 WebNotify.txt
-r--r--r--    1 nobody nobody       2981 Mar 24  2001 WebNotify.txt,v
-rw-r--r--    1 nobody nobody       3670 Apr 12  2002 WebPreferences.txt
-r--r--r--    1 nobody nobody       8203 Apr 12  2002 WebPreferences.txt,v
-rw-r--r--    1 nobody nobody        158 Aug  7  2001 WebSearch.txt
-r--r--r--    1 nobody nobody      18332 Aug  7  2001 WebSearch.txt,v
-rw-r--r--    1 nobody nobody        850 Dec 11 00:58 WebStatistics.txt
-r--r--r--    1 nobody nobody       1690 Dec 11 00:58 WebStatistics.txt,v
-rw-r--r--    1 nobody nobody        182 Nov 24  2001 WebTopicList.txt
-r--r--r--    1 nobody nobody        371 Nov 24  2001 WebTopicList.txt,v

Directory twiki/pub/: 

drwxrwxr-x    8 nobody nobody       4096 Nov 18 12:31 .
drwxrwxr-x    3 twiki  twiki        4096 Nov 18 12:31 ..
drwxrwxr-x    3 nobody nobody       4096 Nov 18 12:31 Know
drwxrwxr-x    2 nobody nobody       4096 Apr  7  2002 Main
drwxrwxr-x    2 nobody nobody       4096 Apr 20  2002 Sandbox
drwxrwxr-x    8 nobody nobody       4096 Nov 18 12:31 TWiki
drwxrwxr-x    2 nobody nobody       4096 Dec  3  2001 Trash
-rw-rw-r--    1 twiki  twiki        1078 Jan 14  2000 favicon.ico
drwxrwxr-x    2 twiki  twiki        4096 Nov 18 12:31 icn
-rw-rw-r--    1 twiki  twiki        2877 Jun  7  1999 wikiHome.gif

Partial file list for twiki/pub/icn/: 

drwxrwxr-x    2 twiki  twiki        4096 Nov 18 12:31 .
drwxrwxr-x    8 nobody nobody       4096 Nov 18 12:31 ..
-rw-rw-r--    1 twiki  twiki         801 Mar 26  1999 _filetypes.txt
-rw-rw-r--    1 twiki  twiki         143 Mar  9  1999 bat.gif
-rw-rw-r--    1 twiki  twiki         926 Mar  9  1999 bmp.gif
-rw-rw-r--    1 twiki  twiki         141 Mar 25  1999 c.gif
-rw-rw-r--    1 twiki  twiki         144 Mar  9  1999 dll.gif
-rw-rw-r--    1 twiki  twiki         152 Mar  9  1999 doc.gif

Directory twiki/pub/TWiki: 

drwxrwx--x    8 nobody nobody       4096 Nov 18 12:31 .
drwxrwxr-x    8 nobody nobody       4096 Nov 18 12:31 ..
drwxrwxr-x    2 nobody nobody       4096 Nov 18 12:31 FileAttachment
drwxrwxr-x    2 nobody nobody       4096 Nov 18 12:31 PreviewBackground
drwxrwxr-x    2 nobody nobody       4096 Nov 18 12:31 TWikiDocGraphics
drwxrwxr-x    2 nobody nobody       4096 Nov 18 12:31 TWikiLogos
drwxrwxr-x    2 nobody nobody       4096 Nov 18 12:31 TWikiTemplates
drwxrwxr-x    2 nobody nobody       4096 Nov 18 12:31 WabiSabi

Directory twiki/pub/TWiki/FileAttachment: 

drwxrwxr-x    2 nobody nobody       4096 Nov 18 12:31 .
drwxrwx--x    8 nobody nobody       4096 Nov 18 12:31 ..
-rw-rw-r--    1 nobody nobody         30 Jul 22  1999 Sample.txt
-rw-rw-r--    1 nobody nobody         94 Jun  7  1999 Smile.gif
-r--r--r--    1 nobody nobody         81 Aug 15 10:14 Smile.gif,v

-- PeterThoeny - 11 Jan 2003
-- MikeMannix - 16 May 2002

Appendix B: TWiki Development Timeline

01-Feb-2003 Release (Beijing)

  • 18 Jan 2003 - PeterThoeny
  • 31 Dec 2002 - PeterThoeny
    • Enhanced Plugin API to manipulate topic data with new functions in TWikiFuncModule: readTopicText, saveTopicText, setTopicEditLock, checkTopicEditLock
  • 31 Dec 2002 - PeterThoeny
  • 29 Dec 2002 - AndreaSterbini?, PeterThoeny, RichardDonkin?, SvenDowideit
    • New Plugin hooks registrationHandler, beforeEditHandler, afterEditHandler, beforeSaveHandler, writeHeaderHandler, redirectCgiQueryHandler, getSessionValueHandler, setSessionValueHandler
  • 30 Nov 2002 - RichardDonkin?
    • Internationalization ('I18N') support 8-bit character sets in WikiWords, such as ISO-8859-15, KOI8-R
  • 25 Nov 2002 - PeterThoeny
    • Include previous topic revision with %INCLUDE{ "OtherTopic" rev="1.2" }%
  • 15 Nov 2002 - PeterThoeny
    • The Go box understands also URLs, useful for special TWikiSkins handling
  • 08 Nov 2002 - ColasNahaboo, RichardDonkin?
    • In WebNotify, if only the WikiName is specified, the e-mail is taken from the user's home page; if the WikiName is a group name, a notification is sent to all members of the group
  • 30 Oct 2002 - PeterThoeny
    • New %NOP{}% variable in TWikiTemplates topic gets removed at topic creation time; useful to write protect template topics
  • 28 Sep 2002 - PeterThoeny
    • The %URLPARAM{}% variable in TWikiTemplates topic gets expanded at topic creation time; useful for dynamic content creation
  • 28 Sep 2002 - PeterThoeny
    • New $logDir introduced in TWiki.cfg to set the log directory
  • 13 Sep 2002 - PeterThoeny
    • Renamed the Test web to Sandbox
  • 03 Aug 2002 - RichardDonkin?
    • New setlib.cfg file in the bin directory to set the TWiki library path
  • 02 Aug 2002 - PeterThoeny, RyanFreebern
    • Support for outbound HTTP proxy when including URLs based on new %PROXYHOST and %PROXYPORT% settings in the TWikiPreferences
  • 12 Jul 2002 - PeterThoeny
    • The page logo is configurable with new %WIKILOGOIMG%, %TWIKILOGOURL% and %WIKILOGOALT% variables in TWikiPreferences; replacing $wikiHomeUrl in TWiki.cfg
  • 12 Jun 2002 - PeterThoeny
    • New %WIKITOOLNAME% variable in TWikiPreferences; replacing $wikiToolName in TWiki.cfg
  • 31 May 2002 - PeterThoeny
    • New %EDITBOXSTYLE% preferences variable which sets the edit box width automatically to the window width
  • 17 May 2002 - PeterThoeny
    • New %URLENCODE{}% variable to encodes a string for using in a URL parameter, e.g. %URLENCODE{"spaced name"}% returns spaced%20name
  • 17 May 2002 - PeterThoeny
  • 05 May 2002 - PeterThoeny
    • New user home pages are now based on the NewUserTemplate, replacing the /twiki/templates/register.tmpl template file
  • 26 Apr 2002 - PeterThoeny
    • New markup to exclude heading from a %TOC% table of content, e.g. ---+!! This heading is not shown in a TOC
  • 13 Apr 2002 - PeterThoeny
  • 01 Apr 2002 - JohnTalintyre?
    • New data storage framework that lets you use external RCS commands for revision control, or a new native Perl implementation that does not depend on the external RCS commands
  • 28 Mar 2002 - PeterThoeny
    • Fixed IE5/IE6-specific problem whereby going back from preview sometimes removes all edit changes
  • 23 Mar 2002 - JohnTalintyre?
    • New AND search; with regular expression enabled, use the semicolon ";" as the AND operator in %SEARCH{}% variable, FormattedSearch and WebSearch
  • 21 Mar 2002 - ColasNahaboo, RichardDonkin?
    • Fixed cache issue where the edit page showed outdated content
  • 06 Mar 2002 - RichardDonkin?
    • Improved statistics script which uses less memory to process large log files
  • 09 Jan 2002 - JohnTalintyre?
    • Variables inside <verbatim> tags are no longer expanded

01-Dec-2001 Release (Athens)

01-Sep-2001 Release

  • 30 Aug 2001 - JohnTalintyre?
    • Easier install for Windows, including auto detection in TWiki.cfg
  • 30 Aug 2001 - JohnTalintyre?
  • 21 Aug 2001 - PeterThoeny
    • Convert to XHTML 1.0 function: first step to XHTML-ifying TWiki
  • 26 Jun 2001 - JohnTalintyre?
  • 07 Jun 2001 - PeterThoeny
    • New topic templates as topics instead of templates. Customize by editing the topic. Retired notedited.tmpl, notext.tmpl and notwiki.tmpl templates. More in TWikiTemplates.
  • 07 Jun 2001 - PeterThoeny
    • New %TOPICLIST{"format"}% and %WEBLIST{"format"}% variables to get a formatted topic index and web index, respectively. More in TWikiVariables.
  • 01 Jun 2001 - PeterThoeny
    • New %URLPARAM{"name"}% variable to query URL parameters. More in TWikiVariables.
  • 01 Jun 2001 - AndreaSterbini?
  • 01 Jun 2001 - KlausWriessnegger, AndreaSterbini?
  • 01 May 2001 - AndreaSterbini?
  • 01 May 2001 - JohnTalintyre?
  • 01 May 2001 - JohnTalintyre?
  • 01 May 2001 - JohnTalintyre?
  • 27 Mar 2001 - PeterThoeny
    • The table syntax has been enhanced to (i) render | *bold* | cells as table headers, (ii) render space padded cells |   center aligned   | and |   right aligned |, (iii) span multiple columns using | empty cells |||. More in TextFormattingRules.
  • 25 Mar 2001 - PeterThoeny
  • 28 Feb 2001 - AndreaSterbini?, PeterThoeny
    • New Wiki rule for headings, i.e. ---++ My Title; and new %TOC% variable to build a table of content from headings in a topic. More in TWikiVariables.
  • 28 Feb 2001 - PeterThoeny
    • New Wiki rule to specify arbitrary text for external links (i.e. [[http://TWki.org][TWiki]]) and internal links (i.e [[WikiSyntax][syntax]]). More in TWikiVariables.
  • 28 Feb 2001 - PeterThoeny
    • New Wiki rule for named anchors, e.g. links within a topic. Define a named anchor with #MyAnchor at the beginning of a line, and link to it with [[#MyAnchor]]. More in TWikiVariables.
  • 25 Feb 2001 - NicholasLee?, PeterThoeny
    • Use Net::SMTP module instead of sendmail if installed.
  • 01 Feb 2001 - PeterThoeny
    • Added <verbatim> ... </verbatim> tags to show source code "as is". Unlike the <pre> ... </pre> tags, it also shows <, >, & characters "as is".
  • 01 Feb 2001 - PeterThoeny
  • 21 Jan 2001 - PeterThoeny
    • Added a "Minor change, don't notify" checkbox in preview. More in DontNotify.
  • 21 Jan 2001 - PeterThoeny
    • Added Bold Fixed formatting using double-equal signs, e.g. write ==Bold Fixed== to get Bold Fixed.
  • 20 Jan 2001 - PeterThoeny
    • 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!
  • 18 Jan 2001 - PeterThoeny
    • WebChanges, WebSearch and e-mail notification indicate also the revision number of a topic (i.e. 18 Jan 2001 16:43 r1.5), or NEW for a new topic (i.e. i.e. 18 Jan 2001 16:43 NEW).
  • 16 Jan 2001 - PeterThoeny
    • New variable %STARTINCLUDE% and %STOPINCLUDE% variables to control what gets included of a topic. More in TWikiVariables.
  • 16 Jan 2001 - PeterThoeny
    • TWiki skins Define a different page layout with a customized header and footer layout, i.e. a print skin for a printable view of a topic. More in TWikiSkins and TWiki:Codev/TWikiSkins.
  • 07 Jan 2001 - StanleyKnutson
    • Better error handling when saving a topic.
  • 05 Jan 2001 - PeterThoeny
  • 05 Dec 2000 - PeterThoeny
  • 03 Dec 2000 - PeterThoeny
    • New noheader="on" switch in %SEARCH{...}% to suppress table header. More in TWikiVariables.

01-Dec-2000 Release

  • 03 Nov 2000 - PeterThoeny
    • Flag $doHidePasswdInRegistration in wikicfg.pm to hide plain text password in registration email.
  • 01 Nov 2000 - PeterThoeny
    • New variable %VAR{"NAME" web="Web"}% to get web specific preferences. More in TWikiVariables.
  • 01 Nov 2000 - PeterThoeny
    • Added a "Cancel" link in edit that releases the edit lock.
  • 23 Oct 2000 - PeterThoeny
  • 05 Oct 2000 - PeterThoeny
    • Remember user by IP address so that view "knows" the user once authenticated in edit. More in TWikiUserAuthentication.
  • 26 Sep 2000 - AlWilliams, PeterThoeny
  • 26 Sep 2000 - HaroldGottschalk, AndreaSterbini?, PeterThoeny
  • 20 Sep 2000 - ManpreetSingh
    • New -q switch in mailnotify to suppress all normal output.
  • 19 Sep 2000 - PeterThoeny
  • 18 Sep 2000 - ManpreetSingh, PeterThoeny
  • 19 Aug 2000 - PeterThoeny
    • Ref-By link searches all webs (not just the current web.)
  • 16 Aug 2000 - PeterThoeny
    • 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.
  • 29 Jul 2000 - PeterThoeny
    • New variables %GMTIME{"..."}% and %SERVERTIME{"..."}% . More in TWikiVariables.
  • 23 Jul 2000 - PeterThoeny
    • Changed include syntax from %INCLUDE{"Web/TopicName.txt"}% to %INCLUDE{"Web.TopicName"}% . Legacy syntax still supported.
  • 23 Jul 2000 - PeterThoeny
    • BookView search allows you show a set of topics for easy printing.
  • 22 Jul 2000 - PeterThoeny
    • More forgiving syntax for *bold*, italic, __bold italic__ and fixed , where it is not necessary anymore to have a trailing space before .,;:?! characters.
  • 22 Jul 2000 - PeterThoeny
    • Split the TWiki.Main web into TWiki.Main (users, company data) and TWiki.TWiki (TWiki related documentation, registration)
  • 07 Jul 2000 - PeterThoeny
    • Added an "Release edit lock" checkbox in preview to let other people edit the topic immediately without the one hour lock.
  • 07 Jul 2000 - PeterThoeny
    • Fixed problem of losing carriage returns when editing topics with KDE KFM browser or W3M browser.
  • 21 Jun 2000 - PeterThoeny
    • Fixed problem that a page redirect on some server environments is not working (host name is needed in URL).
  • 21 Jun 2000 - CrisBailiff, PeterThoeny
    • Fixed security issue to prevent a server side %INCLUDE% of arbitrary files.
  • 29 May 2000 - PeterThoeny
    • New %GMTIME% variable that shows the current GM time.
  • 28 May 2000 - PeterThoeny
    • Lock warning shows remaining lock time in minutes.
  • 15 May 2000 - PeterFokkinga
  • 02 May 2000 - KevinKinnell, PeterThoeny
    • Advanced search features like search multiple webs; sort by topic name / modified time / author; limit the number of results returned. More in TWikiVariables.

01-May-2000 Release

  • 21 Apr 2000 - PeterThoeny
    • New TWikiVariables %HTTP_HOST% , %REMOTE_ADDR% , %REMOTE_PORT% and %REMOTE_USER% .
  • 21 Apr 2000 - JohnAltstadt, PeterThoeny
    • TWikiRegistration is done separately for Intranet use (depends on remote_user) or Internet use (depends on .htpasswd file).
  • 20 Mar 2000 - PeterThoeny
    • 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.
  • 11 Mar 2000 - PeterThoeny
    • Better security with taint checking ( Perl -T option )
  • 25 Feb 2000 - PeterThoeny
    • New preference variables %EDITBOXWIDTH% and %EDITBOXHEIGHT% to specify the edit box size.
  • 25 Feb 2000 - PeterThoeny
    • 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.
  • 11 Feb 2000 - PeterThoeny
    • 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".
  • 11 Feb 2000 - PeterThoeny
    • 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.
  • 07 Feb 2000 - PeterThoeny
    • Changed the syntax for server side include variable from %INCLUDE:"filename.ext"% to %INCLUDE{"filename.ext"}% . (Previous syntax still supported. Change was done because of inline search syntax)
  • 07 Feb 2000 - PeterThoeny
    • 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.
  • 04 Feb 2000 - PeterThoeny
    • 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.)
  • 29 Jan 2000 - PeterThoeny
    • Fixed bug where TWiki would not initialize correctly under certain circumstances, i.e. when running it under mod_perl. Sub initialize in wiki.pm did not handle $thePathInfo correctly.
  • 24 Jan 2000 - PeterThoeny
  • 10 Jan 2000 - PeterThoeny
    • No more escaping for '%' percent characters. (Number of consecutive '%' entered and displayed is identical.)
  • 03 Oct 1999 - PeterThoeny
    • Limit the number of revisions shown at the bottom of the topic. Example
      Topic TWikiHistory . { ..... Diffs r1.10 > r1.9 > r1.8 > r1.7 >... }
      Additional revisions can be selected by pressing the >... link.

01-Sep-1999 Release

  • 31 Aug 1999 - PeterThoeny
    • Fixed Y2K bug. (Date in year 2000 had wrong format.)
  • 08 Aug 1999 - PeterThoeny
    • New text formatting rule for creating tables. Text gets rendered as a table if enclosed in " " vertical bars. Example line as it is written and how it shows up
  • 03 Aug 1999 - PeterThoeny
    • Online registration of new user using web form in TWikiRegistration. Authentication of users.
  • 22 Jul 1999 - PeterThoeny
    • Flags $doLogTopic* in wikicfg.pm to selectively log topic view, edit, save, rdiff, attach, search and changes to monthly log file.
  • 21 Jul 1999 - PeterThoeny
    • Flag $doRemovePortNumber in wikicfg.pm to optionally remove the port number from the TWiki URL. Example www.some.domain:1234/twiki gets www.some.domain/twiki .
  • 15 Jul 1999 - PeterThoeny
    • 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.
  • 07 Jul 1999 - ChristopheVermeulen
    • Link a plural topic to a singular topic in case the plural topic does not exist. Example TestVersion / TestVersions , TestPolicy / TestPolicies , TestAddress / TestAddresses , TestBox / TestBoxes .

01-Jul-1999 Release

  • 23 Jun 1999 - PeterThoeny
    • New TextFormattingRules to write bold italic text by enclosing words with double underline characters.
  • 23 Jun 1999 - PeterThoeny
    • 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.
  • 21 May 1999 - DavidWarman
    • Externalize copyright text at the bottom of every page into a web-specific webcopyright.inc file. This is to easily customize the copyright text.
  • 20 May 1999 - PeterThoeny
    • Added meta tag so that robots index only /view/ of topics, not /edit/, /attach/ e.t.c. Tag <META NAME="ROBOTS" CONTENT="NOINDEX">
  • 20 May 1999 - PeterThoeny
    • New variables %WIKIHOMEURL% (link when pressing the icon on the upper left corner) and %WIKITOOLNAME% (the name of the wiki tool BlinkenArea ).
  • 15 Apr 1999 - PeterThoeny
    • Topic locking Warn user if a topic has been edited by an other person within one hour. This is to prevent contention, e.g. simultaneous topic updates.
  • 26 Mar 1999 - PeterThoeny
    • File attachments Upload and download any file as a topic attachment by using the browser. FileAttachment has more.
  • 26 Mar 1999 - PeterThoeny
    • New variables %PUBURL% (Public directory URL) and %ATTACHURL% (URL of topic file attachment).
  • 09 Feb 1999 - PeterThoeny
    • New text formatting rule for creating fixed font text . Words get showns in fixed font by enclosing them in "=" equal signs. Example Writing =fixed font= will show up as fixed font .
  • 09 Feb 1999 - PeterThoeny
    • No new topic revision is created if the same person saves a topic again within one hour.
  • 03 Feb 1999 - PeterThoeny
    • 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
  • 04 Jan 1999 - PeterThoeny
    • Fixed bug when viewing differences between topic revisions that include HTML table tags like <table>, <tr>, <td>.

1998 Releases

  • 08 Dec 1998 - PeterThoeny
    • Signature is shown below the text area when editing a topic. Use this to easily copy & paste your signature into the text.
  • 07 Dec 1998 - PeterThoeny
    • 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.
  • 18 Nov 1998 - PeterThoeny
    • Internal log of topic save actions to the file data/logYYYYMM.txt, where YYYYMM the year and month in numeric format is. Intended for auditing only, not accessible from the web.
  • 10 Nov 1998 - PeterThoeny
    • The email notification and the Changes topic have now a topic date that is linked. Clicking on the link will show the difference between the two most recent topic revisions.
  • 10 Nov 1998 - PeterThoeny
    • View differences between topic revisions. Each topic has a list of revisions (e.g. r1.3) and differences thereof (e.g. >) at the bottom
      Topic TWikiHistory . { Edit Ref-By r1.3 > r1.2 > r1.1 }
      Revision r1.3 1998/11/10 01:34 by PeterThoeny
  • 26 Oct 1998 - PeterThoeny
    • Added preview of topic changes before saving the topic. This was necessary to prevent unneeded revisions.
  • 26 Oct 1998 - PeterThoeny
    • 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 PeterThoeny
  • 14 Oct 1998 - PeterThoeny
    • Refered-By Find out which topics have a link to the current topic. Each topic has a Ref-By link for that. Note Only references from the current web are shown, not references from other webs.
  • 13 Oct 1998 - PeterThoeny
  • 24 Sep 1998 - PeterThoeny
    • Corrected templates for automatic email notification so that MS Outlook can display attachment as an HTML file.
  • 13 Aug 1998 - PeterThoeny
    • WikiNotation allows also numbers after the AaA sequence, e.g. AaA1 is a valid WikiTopic name, but not Aa1.
  • 07 Aug 1998 - PeterThoeny
    • Automatic email notification when something has changed in a TWiki web. Each web has a topic WebNotify where one can subscribe and unsubscribe.
  • 06 Aug 1998 - PeterThoeny
    • Added server side include of files. Syntax is %INCLUDE:"filename.ext"%
  • 05 Aug 1998 - PeterThoeny
    • Signature and date is inserted automatically when creating a new topic.
  • 04 Aug 1998 - PeterThoeny
    • Separate templates for text of non existing topic and default text of new topic. (template file templates/Web/notedited.tmpl)
  • 04 Aug 1998 - PeterThoeny
    • Warn user if new topic name is not a valid Wiki name. (template file templates/Web/notwiki.tmpl)
  • 31 Jul 1998 - PeterThoeny
    • Support for quoted text with a '>' at the beginning of the line.
  • 28 Jul 1998 - PeterThoeny
    • Added TWiki variables, enclosed in % signs %TOPIC% (Topic name), %WEB% (web name), %SCRIPTURL% (script URL), %DATE% (current date), %WIKIWEBMASTER% (Wiki webmaster address), %WIKIVERSION% (Wiki version), %USERNAME% (user name), %WIKIUSERNAME% (Wiki user name).
  • 28 Jul 1998 - PeterThoeny
    • Topic WebChanges shows Wiki username instead of Intranet username, e.g. PeterThoeny instead of thoeny in case the Wiki username exists. Implementation Automatic lookup of Wiki username in topic TWikiUsers.
  • 28 Jul 1998 - PeterThoeny
    • Topic index. (Technically speaking a simple '.*' search on topic names.)
  • 28 Jul 1998 - PeterThoeny
    • Topic WebSearch allows full text search and and topic search with/without regular expressions.
  • 27 Jul 1998 - PeterThoeny
    • Added automatic links to topics in other TWiki webs by specifying <web name>.<topic name>, e.g. Know.WebSeach .
  • 23 Jul 1998 - PeterThoeny
    • Installed initial version, based on the JOS Wiki. See WikiWikiClones for details.

Dev Flow

The typical TWiki development flow...

EOF

Topic TWikiDocumentation . { Edit | Attach | Ref-By | Printable | Diffs | r1.43 | > | r1.42 | > | r1.41 | More }
Revision r1.46 - 15 Aug 2004 - 08:15 - PeterThoeny