TWikiDocumentation

Webs: Faemalia -:- Greatprawn -:- Playground -:- Technical -:- Tweak
Tweak Web Sections: Register -:- Changes -:- Index -:- Search -:- Go

TWiki Reference Manual (01-Dec-2001)

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 system requirements for TWiki 01-Sep-2001

Overview

Maintaining minimum client and server requirements is necessary to keep TWiki deployment as broad as possible.

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
Non standard Perl modules Net::SMTP (or sendmail) Net::SMTP, MIME::Base64, Digest::SHA1
RCS 5.7 or higher
Other external programs ls, fgrep, egrep
Web server Apache; others (with support for CGI, authentication, extended path) *

Current documentation covers Linux only. A TWikiOnWindows installation guide is next.

Client Requirements

The TWiki standard installation has extremely low browser requirements:

You can easily add capabilities, through customizing the templates, for one, while tailoring the browser requirements to your situation.

Known Issues

-- MikeMannix? - 15 Sep 2001

TWiki Installation Guide

Installation instructions for the TWiki 01-Sep-2001 production release

Overview

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 OS and server that meet the system requirements. Documentation for other platforms is currently limited. For Windows, check TWiki:Codev/TWikiOnWindows. Search the TWiki:Codev web for other intallation notes.

Standard Installation

Request and download the TWiki 01-Sep-2001 distribution in Unix ZIP format from http://TWiki.org/download.html. (To install TWiki on SourceForge, for use on a software development project, read TWiki:Codev/SourceForgeHowTo.)

Step 1: Create & Configure the Directories

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

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
    AllowOverride all
    Allow from all
 </Directory>
 <Directory "/home/httpd/twiki/pub">
    Options FollowSymLinks +Includes
    AllowOverride None
    Allow from all
 </Directory>

Step 1 for Non-Root Accounts

To install TWiki on a system where you don't have server administrator privileges, for example, on a hosted Web account:

TWiki dir: What it is: Where to copy: Example:
twiki/bin CGI bin cgi-enabled dir /home/smith/public_html/cgi-bin
twiki/lib library files same level as twiki/bin /home/smith/public_html/lib
twiki/pub public files htdoc enabled dir /home/smith/public_html/pub
twiki/data topic data outside of htdoc tree (for security) /home/smith/twiki/data
twiki/templates web templates outside of htdoc tree (for security) /home/smith/twiki/templates

Step 2: Set File Permissions

Step 3: Set the Main Configuration File

Step 4: Finish Up from Your Browser

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

Adding a New Web

To create a new web:

  1. Create a new web data directory under twiki/data and check the file permission of the directory.
    • Use a name starting with characters A..Z, followed by a..z and/or 0..9 characters, but not a WikiWord.
  2. Copy all files from the twiki/data/_default directory to the new data directory, preserving the original files' owner, group and permissions (on Unix, use cp -p). The data files must be writable by the owner the CGI scripts are running on (usually, nobody).
    • HINT: You can set permissions of .txt and .txt,v files to -rw-rw-rw- (666) and then edit the topic using your browser; RCS will restore the file permissions correctly when saving the topic.
  3. Add the new web to the web list (visible in the upper right corner of each topic) by editing the site-level preferences, TWikiPreferences:
    • Add the new web to the %WIKIWEBLIST% variable.
  4. Update the web settings by editing the WebPreferences topic of the new web:
    • Customize the %WEBTOPICLIST% variable to contain the web-specific links you prefer.
    • Set the WEBBGCOLOR variable to a color. The number represents the unique color for the web.
    • Set Plugins, access privileges, custom variables, other web-level options (ex: %WEBCOPYRIGHT% can be set for an individual web).
  5. Add the new web to the color-coded web directory table by editing the TWikiWebsTable topic.
  6. Test the new web: view pages, create a new page.

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

Optionally, you can also:

NOTE: User home topics are located in the TWiki.Faemalia web - don't try to move them or create them in other webs. From any other web, user signatures have to point to TWiki.Faemalia web, using a Faemalia.UserName or %MAINWEB%.UserName format. (The %MAINWEB% variable is an advantage if you ever change the Faemalia web name, but the standard Faemalia.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? - 13 Sep 2001
-- MikeMannix? - 03 Dec 2001

TWiki Upgrade Guide

Upgrade from TWiki 01-Dec-2000 or TWiki 01-Sep-2001 to TWiki 01-Dec-2001 (previous to new full release)

Overview

This guide describes how to upgrade either from TWiki 01-Dec-2000 or TWiki 01-Sep-2001 to TWiki 01-Dec-2001.

Upgrade Requirements

Major Changes from TWiki 01-Sep-2001

The latest 01-Dec-2001 release includes the following new features and enhancements compared to the 01-Sep-2001 release:

Major Changes from TWiki 01-Dec-2000

The 01-Sep-2001 release includes the following new features and enhancements compared to the 01-Dec-2000 release:

TWiki Directory Structure and File Names

The TWiki directory structure remains the same, with one exception, the TWiki configuration file and Perl modules have been moved from the twiki/bin directory into it's own twiki/lib directory tree. The following files have been renamed and moved:

From TWiki 01-Dec-2000: To TWiki 01-Dec-2001:
twiki/bin/wikicfg.pm twiki/lib/TWiki.cfg
twiki/bin/wiki.pm twiki/lib/TWiki.pm
twiki/bin/wikiaccess.pm twiki/lib/TWiki/Access.pm
twiki/bin/wikiprefs.pm twiki/lib/TWiki/Prefs.pm
twiki/bin/wikisearch.pm twiki/lib/TWiki/Search.pm
twiki/bin/wikistore.pm twiki/lib/TWiki/Store.pm

A new twiki/lib/TWiki/Plugins directory contains the new Plugin modules.

Standard Upgrade Procedure from 01-Sep-2001 to 01-Dec-2001 Release

This incremental update can be performed easily.

The following steps describe the upgrade assuming that $TWIKIROOT is the root of your current 01-Sep-2001 release.

  1. Back up and prepare:
    • Back up all existing TWiki directories $TWIKIROOT/bin, $TWIKIROOT/pub, $TWIKIROOT/data, $TWIKIROOT/templates.
    • 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.
  4. Update script files:
    • Overwrite all script files in $TWIKIROOT/bin with the new ones.
  5. Update library files:
    • Overwrite the TWiki.pm library in $TWIKIROOT/lib with the new one.
    • Overwrite all *.pm library files in $TWIKIROOT/lib/TWiki and $TWIKIROOT/lib/TWiki/Plugins with the new ones.
  6. Update data/TWiki files: (in case you want the updated docs)
    • Using your browser, merge the new TWiki.TWikiRegistration topic (or TWiki.TWikiRegistrationPub in case you used that one) into your existing TWiki.TWikiRegistration topic.
    • In the temporary twiki/data/TWiki directory where you unzipped the installation package:
      • Remove the files you do not want to upgrade: TWikiPreferences.*, TWikiWebsTable.*, WebNotify.*, WebPreferences.*, WebStatistics.* and all WebTopic* files.
      • In case the cgi-scripts are not running as user nobody: The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed the user of your cgi-scripts, i.e. www-data. A simple way to switch the locker of the RCS files is to use sed:
        for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done
    • Move all remaining *.txt and *.txt,v files from the temporary data/TWiki directory to your $TWIKIROOT/data/TWiki directory.
  7. Update pub/TWiki files:
    • Move the new pub/TWiki/TWikiDocGraphics directory into your $TWIKIROOT/pub/TWiki directory.

Standard Upgrade Procedure from 01-Dec-2000 to 01-Dec-2001 Release

The idea is to have the new and old installation work in parallel so that you can test the new installation before switching over. That way you can make the switch on your live TWiki installation within one minute without affecting the users.

Before Switch: After Switch:
Current 01-Dec-2000: New 01-Dec-2001: Obsolete 01-Dec-2000: New 01-Dec-2001:
twiki/templates/ twiki/templates2/ twiki/templates1/ twiki/templates/
twiki/bin/ twiki/bin/2/ (overwritten) twiki/bin/
(N/A) twiki/bin/lib/ (N/A) twiki/lib/
twiki/data/TWiki twiki/data/TWiki2 twiki/data/TWiki1 twiki/data/TWiki
(other directories do not change)

Alternatively you could move the existing installation away, install the 01-Dec-2001 release into it's place and move your webs and pub files back.

Follow this step-by-step guide to upgrade from the 01-Dec-2000 TWiki to the 01-Dec-2001 release, importing your original page data and related files:

Pre-Upgrade Preparation

Two major areas of TWiki functionality - TWikiTemplates and TWikiForms (input forms associated with a topic)- are entirely different in the new TWiki. If you've customized your templates or use Category Tables, read those sections before starting your upgrade.

The following steps describe the upgrade on Unix. Windows setup is very similar. It's assumed that $TWIKIROOT is the root of your current 01-Dec-2000 release, ex: export TWIKIROOT=/some/dir/

Step 1: Backup & Unpack

  1. Back up all existing TWiki directories twiki/bin, twiki/pub, twiki/data, twiki/templates.
  2. Create a temporary directory and unpack the ZIP file there:
    mkdir -p ~/tmp/
    cp -p ~/downloads/TWiki20011201.zip ~/tmp/
    cd ~/tmp/
    unzip ~/tmp/TWiki20011201.zip

Step 2: Upgrade TWiki document files

  1. Move the document files to your TWiki root ( twiki ):
    mv ~/tmp/TWiki*.html $TWIKIROOT
    mv ~/tmp/index.html $TWIKIROOT
    mv ~/tmp/readme.txt $TWIKIROOT
    mv ~/tmp/license.txt $TWIKIROOT

Step 3: Install new template files

  1. Move & rename the template directory to a temporary twiki/templates2 directory, ex:
    mv ~/tmp/templates $TWIKIROOT/templates2
  2. Pay attention to the file and directory permissions (security issue). Set file permissions, ex:
    chmod 644 *.cgi

Step 4: Install new data and pub files

  1. Move the TWiki web to a temporary TWiki2 twiki/data/TWiki2 directory. Do the same to files attached to this web, ex:
    mv ~/tmp/data/TWiki $TWIKIROOT/data/TWiki2
    mv ~/tmp/pub/TWiki $TWIKIROOT/pub/TWiki2
  2. Move & rename the Know web to a temporary twiki/data/Know2 directory, ex:
    mv ~/tmp/data/Know $TWIKIROOT/data/Know2
    mv ~/tmp/pub/Know $TWIKIROOT/pub/Know2
  3. Move the _default and Trash web, ex:
    mv ~/tmp/data/_default $TWIKIROOT/data
    mv ~/tmp/data/Trash $TWIKIROOT/data
  4. Move the MIME types file, ex:
    mv ~/tmp/data/mime.types $TWIKIROOT/data
  5. Move the TWiki logo files, ex:
    mv ~/tmp/pub/*.gif $TWIKIROOT/pub
  6. Pay attention to the file permissions of the TWiki2 and Know2 directories and its files. The files must be writable by the cgi-scripts (usually user nobody).
  7. In case the cgi-scripts are not running as user nobody: The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed the user of your cgi-scripts, i.e. www-data. A simple way to switch the locker of the RCS files is to use sed:
    for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done

Step 5: Install new CGI scripts

  1. Move & rename the CGI script directory to a temporary twiki/bin/2 directory, ex:
    mv ~/tmp/bin $TWIKIROOT/bin/2
  2. If necessary, change the script names to include the required extension, ex: .cgi
  3. Copy any additional scripts you might have from the 01-Dec-2000 release, ex:
    cp -p $TWIKIROOT/bin/somescript $TWIKIROOT/bin/2
  4. In case you use basic authentication, rename .htaccess.txt to .htaccess and customize it, ex:
    cd $TWIKIROOT/bin/2
    mv .htaccess.txt .htaccess
    diff ../.htaccess .
    and merge the content
  5. Pay attention to the file and directory permissions (security issue). Set permissions, ex:
    chmod 755 *.cgi

Step 6: Install new Perl library files

  1. Move the lib directory to a temporary twiki/bin/lib directory, ex:
    mv ~/tmp/lib $TWIKIROOT/bin
  2. Pay attention to the file and directory permissions (security issue). Set permissions, ex:
    chmod 644 *.pm

Step 7: Set configurations and test installation

  1. Merge the content of the old twiki/bin/wikicfg.pm into the new twiki/lib/TWiki.cfg configuration file. Use the diff command to find out the differences, ex:
    cd $TWIKIROOT/bin/lib
    diff ../wikicfg.pm TWiki.cfg
  2. Make sure to set the correct temporary location of templates and scripts, ex:
    $scriptUrlPath    = "/twiki/bin/2";
    $templateDir      = "/home/httpd/twiki/templates2";
  3. Do not merge the functions extendHandleCommonTags, extendGetRenderedVersionOutsidePRE, extendGetRenderedVersionInsidePRE from the old twiki/bin/wikicfg.pm. This is now handled by the Default plugin twiki/lib/TWiki/Plugins/Default.pm
  4. Test your new TWiki installation to see if you can view topics. Point your browser to the old installation and fix the URL to see the new installation, ex:
    • Old URL: http://localhost/cgi-bin/view
    • New URL: http://localhost/cgi-bin/2/view

Step 8: Update topics

You can do the following changes using your old TWiki 01-Dec-2000 or new TWiki 01-Dec-2001 installation. Pointing your browser to the old installation for edit-copy-edit-paste operations is recommended, so that users don't get surprised by meta data content showing up in topics.

  1. Remember that you now have two TWiki webs:
    • The original TWiki web.
    • The new TWiki2 web, which gets renamed to TWiki when you switch over the installation.
  2. In case you customized TWiki.TWikiRegistration, merge your changes back into TWiki2.TWikiRegistration.
  3. Copy TWiki.TWikiWebsTable to TWiki2.TWikiWebsTable.
    • Do the same for any other topics you might have created in the TWiki web.
  4. In TWiki2.TWikiPreferences, merge the old TWiki.TWikiPreferences settings and customize it.
    • Add your webs to WIKIWEBLIST
    • Set the WIKIWEBMASTER
    • Set the SMTPMAILHOST
  5. In WebPreferences of all webs, add or change the following web preferences: (see TWiki.WebPreferences)
    • Add a NOSEARCHALL in case you want to exclude the web from a web="all" search:
      * Set NOSEARCHALL = on
    • In WEBTOPICLIST, remove the %WEB% . {} decoration from the list (it is now in the templates), ex:
      * Set WEBTOPICLIST = <a href="GroundZero">Home</a>
        | <a href="WebChanges">Changes</a>
        | <a href="WebIndex">Index</a>
        | <a href="WebSearch">Search</a>
        | Go <input type="text" name="topic" size="16" />
    • Add a these new preferences:
      * Set DENYWEBVIEW =
      * Set ALLOWWEBVIEW =
      * Set DENYWEBRENAME =
      * Set ALLOWWEBRENAME =
    • Set the FINALPREFERENCES:
      * Set FINALPREFERENCES = WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, DENYWEBRENAME, ALLOWWEBRENAME
  6. Optional: In WebSearch of all webs, replace content with this one line:
    %INCLUDE{"%TWIKIWEB%.WebSearch"}%
  7. Optional: In WebChanges of all webs, replace content with this one line:
    %INCLUDE{"%TWIKIWEB%.WebChanges"}%

Step 9: Customize template files

NOTE: Skip this step if you did not customize your template files.

  1. Remember that you have now two template directories:
    • The original twiki/templates.
    • The new twiki/templates2, which gets renamed to twiki/templates when you switch over the installation.
  2. Customized templates and skins need to be upgraded to the new TWikiTemplates. This isn't difficult, but you have be familiar with the new template set-up before starting the conversion. The safest way is to use the new templates as a base and to merge your changes back. Changes in new templates:
    • Templates are now rendered by TWiki. You can use all TextFormattingRules, but you have to escape unwanted ones. Also, remove empty lines unless you want a =<p /> tag added.
    • Added TWikiMetaData rendering.
  3. Form Templates replace the TWikiCategoryTables:
    • Create a replacement WebForm topic based on twikicatitems.tmpl in each web that uses a Category Table. See details in TWikiForms and compare with the settings in the Know2.WebPreferences topic.
      NOTE: Do not remove the twikicatitems.tmpl file, it is still used for topics that are of the old format.
    • Searches need to be adjusted to deal with format change. It is possible to define a regular expression search that can deal at the same time with topics in the old format and new format.
      • Example: List all topics in the Know web that have a TopicClassification? of PublicFAQ?:
        %SEARCH{ "[T]opicClassification.*?(td..td|value\=).*?[P]ublicFAQ" casesensitive="on" regex="on" nosearch="on" web="Know"}%
        (The [T] and [P] is done so that search does not find the topic where this search string is located in!)
      • Example: Create a link that lists all topics in the Know web with a TopicClassification? of PublicFAQ?:
        [[%SCRIPTURL%/search%SCRIPTSUFFIX%/Know/?scope=text
        &search=%5BT%5DopicClassification.*%3F%28td..td%7C
        value%5C%3D%29.*%3F%5BP%5DublicFAQ&regex=on][All Public FAQ]]
        All Public FAQ
  4. For each web that has a custom notedited.tmpl template, create an equivalent WebTopicEditTemplate to conform with the new TemplateTopics. The new format replaces the notedited.tmpl, notext.tmpl and notwiki.tmpl templates.

Step 10: Switch over to new installation

In this step, you move the working 01-Dec-2001 installation to the old 01-Dec-2000 installation, so that users don't have to change the URL.

  1. Test your new 01-Dec-2001 installation under twiki/bin/2/view to make sure everything works as expected.
    • NOTE: Don't worry about the Plugins, they'll work after the switch.
  2. Edit $TWIKIROOT/bin/2/TWiki.cfg and remove the /2 from $scriptUrlPath and $templateDir, ex:
    $scriptUrlPath    = "/twiki/bin";
    $templateDir      = "/home/httpd/twiki/templates";
  3. Rename the TWiki2 web to TWiki, including attachments, ex:
    cd $TWIKIROOT/data
    mv TWiki TWiki1
    mv TWiki2 TWiki
    cd $TWIKIROOT/pub
    mv TWiki TWiki1
    mv TWiki2 TWiki
  4. Rename the templates2 directory to templates, ex:
    cd $TWIKIROOT
    mv templates templates1
    mv templates2 templates
  5. Move the lib directory one level up from $TWIKIROOT/bin/lib to $TWIKIROOT/lib, ex:
    cd $TWIKIROOT
    mv bin/lib .
  6. Copy content of bin/2 to bin, ex:
    cd $TWIKIROOT/bin
    cp -p bin/2/* .
    cp -p bin/2/.htaccess .
  7. Point your browser to the original URL and make sure the relocated 01-Dec-2001 installation works as expected: check browsing, searching and user registration.
  8. Clean up and remove obsolete directories:
    • Remove directory $TWIKIROOT/bin/2
    • Remove directory $TWIKIROOT/templates1
    • Remove directory $TWIKIROOT/data/TWiki1
    • Remove directory $TWIKIROOT/pub/TWiki1
    • Remove temporary directory, ex: ~/tmp

Step 11: Test the TWiki Plugins

  1. Test the new TWikiPlugins by checking the Plugins settings in TWikiPreferences.
    • The EmptyPlugin, DefaultPlugin, and InterwikiPlugin should be preinstalled. To check the InterwikiPlugin, go to its page.
  2. If you have customized the functions extendHandleCommonTags, extendGetRenderedVersionOutsidePRE and extendGetRenderedVersionInsidePRE in twiki/bin/wikicfg.pm:
    • Merge those changes back into twiki/lib/TWiki/Plugins/Default.pm

General Format Changes

Known Issues

-- JohnTalintyre? - 18 Jul 2001
-- MikeMannix? - 12 Sep 2001
-- PeterThoeny? - 03 Dec 2001

TWiki User Authentication

TWiki site access control and user activity tracking

Overview

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:

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

TWiki Username vs. Login Username

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

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

TWiki can automatically map an intranet username to a TWiki username, provided that the username pair exists in the FaemaliaUsers topic. This is also handled automatically when you register.

NOTE: To correctly enter a WikiName - your own or someone else's - be sure to include the Faemalia web name in front of the Wiki username, followed by a period, and no spaces. Ex:
Faemalia.WikiUsername or %MAINWEB%.WikiUsername
This points WikiUser to the TWiki.Faemalia 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 Faemalia web.

Changing Passwords

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

Change password

Forgot your old password? Then reset your password instead. Please only use Reset Password in case you really forgot your password. Thank you.

Your WikiName: **
Old password **
New password **
Retype new password **
     (Fields marked ** are required)

After submitting this form your password will be changed.

Request for reset of password

Please only use this Reset Password form in case you really forgot your password. Otherwise just change it using Change Password.

Your WikiName: **
New password **
Retype new password **
     (Fields marked ** are required)

After submitting this form you will receive a page with yor new password appearing encrypted.

-- MikeMannix? - 29 Aug 2001

TWiki Access Control

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

Overview

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

An Important Control Consideration

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

As a collaboration guideline:

Users and Groups

Access control is based on users and groups. Users are defined by their WikiNames, an then organized into unlimited combinations under different user groups.

Managing Users

A user is created by with the TWikiRegistration form. The process generates a topic in the Faemalia web in the new user's WikiName. The default visitor name is TWikiGuest.

Managing Groups

Groups are defined by group topics in the Faemalia web, like the TWikiAdminGroup?. To start a new group:

  1. Create a new topic with A name that ends in Group, SomeGroup
  2. Define two variables:
    • Set GROUP = < list of users and groups >
    • Set ALLOWTOPICCHANGE = < list of users and groups >

Restricting Write Access

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

Deny Editing by Topic

Denying editing of a topic also restricts attaching files to it; both privileges are assigned together.

Deny Editing by Web

Restricting web-level editing blocks creating new topics, changing topics or attaching files.

The same rules apply as for restricting topics, with these additions:

Restricting Rename Access

You can define who is allowed to rename, move or delete a topic, or rename a web.

Deny Renaming by Topic

To allow a user to rename, move or delete a topic, they also need write (editing) permission. They also need write access to change references in referring topics.

Deny Renaming by Web

You can define restrictions of who is allowed to rename a TWiki web.

The same rules apply as for topics, with these additions:

Restricting Read Access

You can define restrictions of who is allowed to view a TWiki web.

Known Issues

Selective Unrestricted Web Access

Hiding Control Settings

<!--
Set DENYTOPICCHANGE = Main.SomeGroup
-->

The SuperAdminGroup

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

$superAdminGroup = "TWikiAdminGroup";

-- MikeMannix? - 02 Dec 2001

TWiki Text Formatting

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

TWiki Editing Shorthand

Formatting Command: Example: You write: You get:
Paragraphs:
Blank lines will create new paragraphs. 
1st paragraph

2nd paragraph
1st paragraph

2nd paragraph

Headings:
At least three dashes at the beginning of a line, followed by plus signs and the heading text. One plus creates a level 1 heading (most important), two pluses a level 2 heading; the maximum is level 6. Note: A Table of Content can be created automatically with the %TOC% variable, see TWikiVariables. 
---++ Sushi

---+++ Maguro

Sushi

Maguro
Bold Text:
Words get bold by enclosing them in * asterisks. 
*Bold*
Bold
Italic Text:
Words get italic by enclosing them in _ underscores. 
_Italic_
Italic
Bold Italic:
Words get _bold italic by enclosing them in _ double-underscores. 
__Bold italic__
Bold italic
Fixed Font:
Words get shown in fixed font by enclosing them in = equal signs. 
=Fixed font=
Fixed font
Bold Fixed Font:
Words get shown in bold fixed font by enclosing them in double equal signs. 
==Bold fixed==
Bold fixed
Note: Make sure to "stick" the * _ = == signs to the words, e.g. take away spaces. 
_This works_,
_this not _
This works, _this not _
Verbatim Mode:
Surround code excerpts and other formatted text with <verbatim> and </verbatim> tags.
Note: Use <pre> and </pre> tags instead if you want that HTML code is interpreted.
Note: Each tag must be on a line by itself. 
<verbatim>
class CatAnimal {
  void purr() {
    <code here>
  }
}
</verbatim>

class CatAnimal {
  void purr() {
    <code here>
  }
}
Separator:
At least three dashes at the beginning of a line. 
-------
List Item:
Three spaces and an asterisk. 
   * bullet item
  • bullet item
Nested List Item:
Six, nine, ... spaces and an asterisk. 
      * nested stuff
    • nested stuff
Ordered List:
Three spaces and a number. 
   1 Sushi
   1 Dim Sum
  1. Sushi
  2. Dim Sum
Definition List:
Three spaces, the term, a colon, a space, followed by the definition.
Note: Terms with spaces are not supported. In case you do have a term with more then one word, separate the words with dashes or with the &nbsp; non-breaking-space entity. 
   Sushi: Japan
   Dim&nbsp;Sum: S.F.
Sushi
Japan
Dim Sum
S.F.
Table:
Optional spaces followed by the cells enclosed in vertical bars.
Note: | *bold* | cells are rendered as table headers.
Note: |   spaced   | cells are rendered center aligned.
Note: |     spaced | cells are rendered right aligned.
Note: | 2 colspan || cells are rendered as multi-span columns.
Note: In case you have a long row and you want it to be more readable when you edit the table you can split the row into lines that end with a '\' backslash character. 
| *L* | *C* | *R* |
| A2 |  2  |  2 |
| A3 |  3  |  3 |
| multi span |||
| A4 \  | next \  | next |
L C R
A2 2 2
A3 3 3
multi span
A4 next next
WikiWord Links:
CapitalizedWordsStuckTogether (or WikiWords) will produce a link automatically.
Note: In case you want to link to a topic in a different TWiki web write Webname.TopicName. 
WebNotify

Know.ReadmeFirst
WebNotify

ReadmeFirst?

#SquareBrackets Forced Links:
You can create a forced internal link by enclosing words in double square brackets.
Note: Text within the brackets may contain optional spaces; the topic name is formed by capitalizing the initial letter and by removing the spaces; i.e. [[text formatting FAQ]] links to topic TextFormattingFAQ. You can also refer to a different web and use anchors. 
[[wiki syntax]]

[[Faemalia.TWiki users]]
wiki syntax

Faemalia.TWiki users?

Specific Links:
Create a link where you can specify the link text and the link reference separately, using nested square brackets like [[reference][text]]. Internal link references (i.e. WikiSyntax) and external link references (i.e. http://TWiki.org/) are supported. The same Forced Links rules apply for internal link references. Anchor names can be added as well, like [[WebHome#MyAnchor][go home]] and [[http://www.yahoo.com/#somewhere][Yahoo!]]. 
[[WikiSyntax][syntax]]

[[http://gnu.org][GNU]]
syntax

GNU

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

[[#MyAnchor][Jump]]

#MyAnchor To here
WebHome#NotThere?

Jump

To here

Prevent a Link:
Prevent a WikiWord from being linked by prepending it with the <nop> tag. 
<nop>SunOS
SunOS

Using HTML

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

HTML and TWiki Usability

TWiki HTML Rendering

Hyperlinks

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

Internal Links

External Links

TWikiPlugin Formatting Extensions

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

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

Check on current Plugin status and settings for this site in TWikiPreferences.

-- MikeMannix? - 02 Dec 2001

TWiki Variables

Text strings expanded on the fly to display data or system info

Overview

TWikiVariables are text strings - %VARIABLE% - that expand into content whenever a page is opened. Variables are replaced by their actual values: stored data, or system info (like the date, or the current user). There are predefined variables, and Preference variables that you set. You can also define custom variables, with new names and values.

Predefined Variables

Most predefined variables return values that were either defined when TWiki was installed, or taken from server info (like current username, or date and time). Many of the variables let you control how the formatted results appear.

TWiki expands the following variables (enclosed in % percent signs):

Variable: Expanded to:
%WIKIHOMEURL% The base script URL of TWiki, is the link of the Home icon in the upper left corner, is http://faemalia.org/wiki/view
%SCRIPTURL% The script URL of TWiki, is http://www.faemalia.org/wiki
%SCRIPTURLPATH% The path of the script URL of TWiki, is /wiki
%SCRIPTSUFFIX% The script suffix, ex: .pl, .cgi is
%PUBURL% The public URL of TWiki, is http://www.faemalia.org/wikipub
%PUBURLPATH% The path of the public URL of TWiki, is /wikipub
%ATTACHURL% The attachment URL of the current topic, is http://www.faemalia.org/wikipub/Tweak/TWikiVariables
Example: If you attach a file you can refer to it as %ATTACHURL%/image.gif
%ATTACHURLPATH% The path of the attachment URL of the current topic, is /wikipub/Tweak/TWikiVariables
%URLPARAM{"name"}% Returns the value of a URL parameter. Ex: %URLPARAM{"skin"}% returns print for a .../view/Tweak/TWikiVariables?skin=print URL. Is
%WIKITOOLNAME% Name of wiki tool, is TWiki
%WIKIVERSION% Wiki tool version is 02 Sep 2004 $Rev: 1742 $
%USERNAME% Your login username is guest
%WIKINAME% Your Wiki username. Same as %USERNAME% if not defined in the FaemaliaUsers topic. Is guest
%WIKIUSERNAME% Your %WIKINAME% including the Faemalia web name. Usefull for signatures. Is Faemalia.guest
%MAINWEB% The Main web containing FaemaliaUsers, OfficeLocations? and TWikiGroups. Is Faemalia
%TWIKIWEB% The web containing all documentation and configuration of TWiki is Tweak
%WEB% The current web is Tweak
%BASEWEB% The web name where the includes started, e.g. the web of the first topic of nested includes. Same as %WEB% in case there is no include.
%INCLUDINGWEB% The web name of the topic that includes the current topic. Same as %WEB% in case there is no include.
%HOMETOPIC% The home topic in each web. Is GroundZero
%NOTIFYTOPIC% The notify topic in each web. Is WebNotify
%WIKIUSERSTOPIC% The index topic of all registered users. Is FaemaliaUsers
%WIKIPREFSTOPIC% The web preferences topic. Is TWikiPreferences
%WEBPREFSTOPIC% The web preferences topic. Is WebPreferences
%STATISTICSTOPIC% The web statistics topic. Is WebStatistics
%TOPIC% The current topic name, is TWikiVariables
%BASETOPIC% The name of the topic where the includes started, e.g. the first topic of nested includes. Same as %TOPIC% in case there is no include.
%INCLUDINGTOPIC% The name of the topic that includes the current topic. Same as %TOPIC% in case there is no include.
%SPACEDTOPIC% The current topic name with added spaces, for regular expression search of Ref-By, is TWiki%20*Variables
%TOPICLIST{"format"}% Topic index of a web. The "format" defines the format of one topic item. It may include variables: The $name variable gets expanded to the topic name; the $web variable gets expanded to the name of the web. Parameters are format, separator and web:
Parameter: Description: Default:
"format" Format of one line, may include $name and $web variables "$name"
format="format" (Alternative to above) "$name"
separator=", " line separator "\n" (new line)
web="Name" Name of web Current web
Examples:
%TOPICLIST{"   * $web.$name"}% creates a bullet list of all topics.
%TOPICLIST{separator=", "}% creates a comma separated list of all topics.
%TOPICLIST{" <option>$name</option>"}% creates an option list (for drop down menus).
%WEBLIST{"format"}% Web index, e.g. list of all webs. Hidden webs are excluded, e.g. webs with a NOSEARCHALL=on preference variable. The "format" defines the format of one web item. The $name variable gets expanded to the name of the web, $qname gets expanded to double quoted name, $marker to marker where web matches selection. Parameters are format, separator and web:
Parameter: Description: Default:
"format" Format of one line, may include $name variable "$name"
format="format" (Alternative to above) "$name"
separator=", " line separator "\n" (new line)
webs="public" comma sep list of Web, public expands to all non-hidden "public"
marker="selected" Text for $marker where item matches selection, otherwise equals "" "selected"
selection="%WEB%" Current value to be selected in list section="%WEB%"
Examples:
%WEBLIST{"   * [[$name.GroundZero]]"}% creates a bullet list of all webs.
%WEBLIST{"" webs="Trash,public" selection="Tweak" separator=" "}% Dropdown of all public Webs + Trash Web, current Web highlighted.
%GMTIME% GM time, is 07 Jan 2009 - 19:15
%GMTIME{"format"}% Formatted GM time based on time variables.
Variable: Unit: Example
$seconds seconds 59
$minutes minutes 59
$hours hours 23
$day day of month 31
$month month in ISO format Dec
$mo 2 digit month 12
$year 4 digit year 1999
$ye 2 digit year 99
Variables can be shortened to 3 characters. Example:
%GMTIME{"$day $month, $year - $hour:$min:$sec"}% is
07 Jan,