Skip to topic | Skip to bottom
Home
TWiki

Create personal sidebar
TWiki.TWikiDocumentationr1.1 - 15 Aug 2004 - 08:15 - TWikiGuesttopic end
Start of topic | Skip to actions

TWiki Reference Manual (01-Sep-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

Note: Included topic TWikiImplementationNotes? does not exist yet

TWiki Installation Guide

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

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

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

Standard Installation

Download the TWiki 01-Sep-2004 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 httpd.conf (typcially located in /etc/httpd/) with only ExecCGI option.
  • The twiki/pub directory of TWiki must be set so that it is visible as a URL. Add /home/httpd/twiki to file httpd.conf with normal access options (copy from /home/httpd/html ).
  • Now add ScriptAlias for /twiki/bin and Alias for /twiki to file httpd.conf .
    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 service httpd restart (or as appropriate to your flavor of UNIX or Linux).
  • 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.

Aletrnative Step 1: Create & Configure the Directories 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

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

Step 2: Set File Permissions

  • Make sure Perl 5 and the Perl CGI library are installed on your system. The default location of Perl is /usr/bin/perl. If it's elsewhere, change the path to Perl in the first line of each script in the twiki/bin directory, or create a symbolic link from /usr/bin/perl.
    • IMPORTANT:
      • On ISP-hosted accounts (and some intranet servers), Perl CGI scripts may require a .cgi extension to run. Some systems need .pl, the regular Perl extension. Rename all twiki/bin scripts if necessary.
      • Alternatively, you might try creating a file twiki/bin/.htaccess that contains the single line SetHandler cgi-script, which tells Apache to treat all files in this directory as CGI scripts.
  • Set the file permission of all Perl scripts in the twiki/bin directory as executable to -rwxr-xr-x (755).
  • To be able to edit the Perl scripts and .tmpl files it is necessary to chown and chgrp -R twiki so all the files have the owner you want.
  • 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 permissions manually.
    • Set the permission of all files below twiki/data so that they are writable by user nobody. A simple way is to chmod them to -rw-rw-r-- (664) and to chown them to nobody.
    • Set the permission of the twiki/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, such as www-data, or delete them all - new files will be automatically created the first time each topic is edited. You have two options to change ownership of the RCS lock user:
      • Run the testenv script from your browser; in the Fix line you can relock all the rcs files (recommended)
      • Alternatively, run this in your shell:
        cd twiki/data
        find . -name *,v -exec perl -pi~ -e '$. <= 10 && s/nobody:/www-data:/ ' {} \;
        This will create *,v~ backup files which you should remove after verification:
        find . -name *,v~ -exec rm -f {} \;

Step 3: Edit the Configuration Files

  • Edit the file /twiki/bin/setlib.cfg
    • Set $twikiLibPath to the absolute file path of your /twiki/lib as seen by the web server.
    • ALERT! Attention: Do not leave it as a relative "../lib" path or Plugins might fail to initialize properly
    • You can also edit $localPerlLibPath if you are not root and need to install additional CPAN modules, but can't update the main Perl installation files on the server. Just set this variable to the full pathname to your local lib directory, typically under your home directory.
    • ALERT! Attention: If you are running TWiki on Apache 2.0 on Unix you might experience cgi scripts to hang forever. This is a known Apache 2.0 bug. See details and woraround in the setlib.cfg file.
  • Edit the file twiki/lib/TWiki.cfg, setting the variables to your needs.
    • Set the file extension in the $scriptSuffix variable to cgi or pl if required.
    • RCS - revision control system to store revision of topics and attachments. You can use RCS executables or a version of RCS written in Perl, note that as the time of writing (Apr 2002) the Perl version has not been widely tested, so if you want to put up a live site the RCS executables are recommended.
      • Set $storeTopicImpl = "RcsWrap"; for the RCS executables and make sure RCS is installed. Set $rcsDir in twiki/lib/TWiki.cfg to match the location of your RCS binaries. You can check this by issuing the command rcs at the prompt, it should result in something like "rcs: no input file".
        • Check that you have GNU diff, by typing diff -v - an error indicates you have a non-GNU diff, so install the GNU diffutils package and make sure that diff is on the PATH used by TWiki (see $safeEnvPath in the TWiki.cfg file).
      • Set $storeTopicImpl = "RcsLite"; for the Perl based RCS
  • Security issue: Directories twiki/data , twiki/templates and all their subdirectories should be set so that they are not visible through URLs. (Alternatively, move the directories to a place where they are not visible, and change the variables in twiki/lib/TWiki.cfg accordingly)
  • 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: Internationalisation Setup (Optional)

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

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

To configure internationalisation suppport:

  1. Edit the TWiki.cfg file's Internationalisation section to set the $useLocale parameter to 1. TWiki will now use the I18N parameters set in the rest of this section.
  2. Type the Unix/Linux command locale -a to find a suitable 'locale' for your use of TWiki. A locale that includes a dot followed by a character set is recommended, e.g. pl_PL.ISO-8859-2 for Poland. Consult your system administrator if you are not sure which locale to use.
  3. In TWiki.cfg, set the $siteLocale parameter to your chosen locale, e.g. pl_PL.ISO-8859-2 for Poland.
  4. Check your setup using testenv (download the latest testenv from TWiki:Support/SupportGuidelines if possible) - this provides some diagnostics for I18N setup, and in particular checks that your locale can be used successfully.
  5. (For upgrade of TWiki I18N sites only:) If you were using TWiki:Codev.TWikiRelease01Feb2003 support for I18N, and are using Internet Explorer or Opera, you should re-configure your browser so that it sends URLs encoded with UTF-8 (supported since TWiki:Codev.TWikiRelease01Sep2004). If you are doing a new installation of TWiki, you can ignore this step - no browser reconfiguration is needed for TWiki Release 01-Sep-2004).
    • Internet Explorer 5.0 or higher: in Tools | Options | Advanced, check 'always send URLs as UTF-8', then close all IE windows and restart IE.
    • Opera 6.x or higher: in Preferences | Network | International Web Addresses, check 'encode all addresses with UTF-8'.
    • NOTE: This does not mean that TWiki supports UTF-8 as a site character set.
  6. Try out your TWiki by creating pages in the Sandbox web that use international characters in WikiWords and checking that searching, WebIndex, Ref-By and other features are working OK.

Trouble with I18N?

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

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

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

Step 5: Configure Site-Wide Email Preferences

  • Edit the TWikiPreferences topic in the TWiki web (by pointing your browser to http://yourdomain.com/twiki/bin/view/TWiki/TWikiPreferences) to set the WIKIWEBMASTER email address, and other email settings required for registration and WebChangesAlert to work:
    • WIKIWEBMASTER should be set to the email address of the TWiki administrator
    • SMTPMAILHOST is typically set on Windows or other non-Unix/Linux systems, where sendmail or similar is not available. When this is set and the Perl module Net::SMTP is installed, TWiki will connect to this SMTP server (e.g. mail.yourdomain.com) to send email for user registration and WebChangesAlerts. If you do have a sendmail-type program, leave SMTPMAILHOST unset so that the external sendmail program is used instead (defined by $mailProgram in TWiki.cfg).
    • SMTPSENDERHOST is optional, and set to the domain name sending the email (e.g. twiki.yourdomain.com). For use where the SMTP server requires that you identify the TWiki server sending mail. If not set, Net::SMTP will guess it for you.
  • You may want to set up other TWikiPreferences later on.
  • To enable the WebChangesAlerts (email notifications) you need to read about cron in the topic TWikiSiteTools.

Step 6: 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.WebHome topic.
  • You can add new %VARIABLES%. Define site-level variables in the TWikiPreferences topic. See also: TWikiVariables.

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

Additional Server-Level Options

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

Enabling Authentication of Users

  • If TWiki is installed on a non-authenticated server - not using SSL - and you'd like to authenticate users:
    1. Rename file .htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. The comment at the top of the file explains what need to be done, basically replace !FILE_path_to_TWiki! and !URL_path_to_TWiki! with paths specific to your installation. For the details of how this file works, consult the HTTP server documentation (for Apache server: [1], [2]).
      • 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. TWiki now supports several Password file format/encoding methods for Apache. Once you know what method is used by your Appache server, you can configure TWiki to create compatible .htpasswd entries by editing the $htpasswdFormatFamily, $htpasswdEncoding and $htpasswdFilename in the TWiki.cfg file. The supported options are htpasswd:plain, htpasswd:crypt, htpasswd:sha1, htdigest:md5
    3. 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. The same variables get expanded as in the template topics
  • 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.

WYSIWYG Editor

At this time, TWiki does not ship with an "what you see is what you get" editor. TWiki:Codev/IntegrateHtmlAreaEditor describes how to integrate an HTML editor.

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

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-2004 distribution.

-- TWiki:Main/PeterThoeny - 29 Aug 2004
-- TWiki:Main/MikeMannix - 16 May 2002

TWiki Upgrade Guide

Upgrade from the previous TWiki 01-Feb-2003 production release to TWiki 01-Sep-2004

Overview

This guide describes how to upgrade from TWiki 01-Feb-2003 to TWiki 01-Sep-2004. This is a major new release. You can chose between an automated upgrade using a script or a manual update.

Upgrade Requirements

  • Please review the AdminSkillsAssumptions before you upgrade TWiki
  • To upgrade from a 01-Feb-2003 standard installation to the latest 01-Sep-2004 TWiki Production Release, follow the instructions below
  • NOTE: To upgrade from a pre-01-Feb-2003 TWiki, start with TWikiUpgradeTo01Feb2003
  • 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 Compared to TWiki 01-Feb-2003

  • Automatic upgrade script, and easier first-time installation
  • Attractive new skins, using a standard set of CSS classes, and a TWikiSkinBrowser to help you choose
  • New easier-to-use save options
  • Many improvements to SEARCH
  • Improved support for internationalisation
  • Better topic management screens
  • More pre-installed Plugins: CommentPlugin, EditTablePlugin, RenderListPlugin, SlideShowPlugin, SmiliesPlugin, SpreadSheetPlugin, TablePlugin
  • Improved Plugins API and more Plugin callbacks
  • Better support for different authentication methods
  • Many user interface and usability improvements
  • And many more enhancements, see the complete change log at TWikiHistory

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

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

If you would prefer to do things manually than trust a beta script, skip to the manual upgrade procedure below.

The upgrade script is called "UpgradeTwiki", and is found in the root of the distribution.

It will:

  • Create a new TWiki installation, placing the files from the distribution there as appropriate
  • Where possible, merge the changes you've made in your existing topics into the new twiki
  • Where not possible, it will tell you, and you can inspect those differences manually
  • Create new configuration files for the new TWiki based on your existing configuation information
  • Set the permissions in the new TWiki so that it should work straight away
  • Attempt to setup authentication for your new TWiki, if you are using .htaccess in the old one
  • Tell you what else you need to do

To perform the upgrade, you need to:

  • Check first if there is a newer UpgradeTwiki script available, see TWiki:Codev.UpgradeTwiki
  • Create a new directory for your new installation: Let's call this distro/
  • Put the distribution zip file in distro/
  • Unzip it
  • Choose a directory for the new installation. I will call this new_twiki. This directory must not already exist.
  • Change directory to distro/ and run:
    ./UpgradeTwiki <full path to new_twiki>

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

There are a few points worth noting:

  • UpgradeTwiki may not be able to merge all the changes you made in your existing TWiki into the new installation, but it will tell you which ones it couldn't deal with
  • UpgradeTwiki creates the new installation in a new directory tree. It makes a complete copy of all your existing data, so:
    • Clearly you need to point it to a location where there is enough space
    • If you have symlinks under your data/ directory in your existing installation, these are reproduced as actual directories in the new structure. It is up to you to pull these sub-directories out again and re-symlink as needed
  • UpgradeTwiki doesn't deal with custom templates or Plugins, you will have to reinstall these in the new installation
  • If you have done tricky stuff with $OS in your existing TWiki.cfg file, then you will need to manually examine the new TWiki.cfg file and possibly put your tricky changes in there manually

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

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

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

  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 back 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
    • Change to view templates and skins:
      • Add %BROADCASTMESSAGE% somewhere on the top of the rendered HTML page (see the new view.tmpl for reference)
    • Changes to edit templates and skins:
      • Change the form action from preview to save:
        <form name="main" action="%SCRIPTURLPATH%/save%SCRIPTSUFFIX%/%WEB%/%TOPIC%" method="post">
      • Change the topic action to the following:
        %TMPL:DEF{"topicaction"}%
        <input type="submit" class="twikiSubmit" name="action" value="Cancel" id="cancel" />
        <input type="submit" class="twikiSubmit" name="action" value="Preview" id="preview" />
        <input type="submit" class="twikiSubmit" name="action" value="Checkpoint" id="checkpoint" />
        <input type="submit" class="twikiSubmit" name="action" value="QuietSave" id="quietsave" />
        <input type="submit" class="twikiSubmit" name="action" value="Save" id="save" />%TMPL:END%
  4. Update script files:
    • Overwrite all script files in $TWIKIROOT/bin with the new ones.
      • If necessary, rename the scrips 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 your existing $TWIKIROOT/bin/.htaccess file to include a directive for the new rdiffauth script:
      <Files "rdiffauth">
          require valid-user
      </Files>
    • Pay attention to the file and directory permissions, the scripts need to be executable, e.g. chmod 775 $TWIKIROOT/bin/*
      • Certain hosted environments require a 755 (do so if you get a "Premature end of script headers" messages in the Apache error log)
    • For Windows hosts, 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 but the directory files should be, e.g. chmod 664 `find -type f $TWIKIROOT/lib` (for files) and chmod 775 `find -type d $TWIKIROOT/lib` (for directories)
  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, for example www-data
      • Run the testenv script from your browser; in the Fix line you can relock all the rcs files (recommended)
      • Alternatively, execute the shell script commands described in TWikiInstallationGuide#StepTwo
    • 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.*, 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. Notable changes are:
      • New WIKIWEBMASTERNAME setting to avoid notifications being trapped by spam filters
      • New ATTACHFILESIZELIMIT setting for maximum size of FileAttachments in KB, 0 for no limit
      • New READTOPICPREFS and TOPICOVERRIDESUSER settings to allow override Preference settings in topics
      • Changed FINALPREFERENCES:
        • Set FINALPREFERENCES = PREVIEWBGIMAGE, WIKITOOLNAME, WIKIWEBMASTER, SMTPMAILHOST, SMTPSENDERHOST, ALLOWWEBMANAGE, READTOPICPREFS, TOPICOVERRIDESUSER
    • Move the data/_default directory from the temporary location to your $TWIKIROOT/data directory
    • 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):
    • Add WebLeftBar topic. See WebLeftBarExample for a clean example, and WebLeftBarCookbook for more information. (WebLeftBar is used by the PatternSkin skin)
    • Add WebSearchAdvanced topic, which has this one line:
      %INCLUDE{"%TWIKIWEB%.WebSearchAdvanced"}%
    • Consider changing WebPreferences settings:
      • New NOAUTOLINK setting to prevent automatic linking of WikiWords and acronyms
      • Changed FINALPREFERENCES:
        • Set FINALPREFERENCES = NOSEARCHALL, ATTACHFILESIZELIMIT, WIKIWEBMASTER, WEBCOPYRIGHT, WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, DENYWEBRENAME, ALLOWWEBRENAME
  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. Verify installation:
    • Execute the $TWIKIROOT/bin/testenv script from your browser (e.g. http://localhost/bin/testenv) to see if it reports any issues; address any potential problems
    • Test your updated TWiki installation to see if you can view, create, edit and rename topics; upload and move attachments; register users
    • Test if the installed Plugins work as expected. You should see the list of installed Plugins in TWiki.WebHome

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

Known Issues

-- TWiki:Main.PeterThoeny - 29 Aug 2004

TWiki User Authentication

TWiki site access control and user activity tracking options

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

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

Authentication Options

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

  1. No login at all: Forget about authentication to make your site completely public - anyone can browse and edit freely, in classic Wiki mode. All visitors are assigned the TWikiGuest default identity, so you can't track individual user activity.
    • How: Default, no web server configuration necessary
  2. No login to view; require login to edit: Keeping track of who changed what and when, while keeping view access unrestricted is desirable in most TWiki deployments. This option is not suitable if you need TWikiAccessControl for view restricted content since TWiki does not know who a user is when looking at content.
    • How: Use Basic Authentication to control access by protecting key scripts: attach, edit, installpasswd, manage, preview, rename, save, upload. The TWikiInstallationGuide has step-by-step instructions.
  3. No login to view unless necessary; require login to edit: You prefer not to bother the user with login for unrestricted content, but you need TWikiAccessControl for view restricted content. There are two ways to accomplish this:
    • How 1: Use Basic Authentication with Partial Authentication (described below)
    • How 2: Use one of the Session TWiki:Plugins where you give the user the option to login and logout.
  4. Require login to view and edit: Most restrictive, but TWiki knows who the user is at all times. There are two ways to accomplish this:
    • How 1: Use Basic Authentication to authenticate the whole twiki/bin directory. Consult your web server documentation.
    • How 1: Use SSL (Secure Sockets Layer; HTTPS) to authenticate and secure the whole server. Consult your web server documentation.

Partial Authentication

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

  • Normally, the REMOTE_USER environment variable is set for the scripts that are under authentication. If, for example, the edit, save and preview scripts are authenticated, but not view, you would get your WikiName in preview for the %WIKIUSERNAME% variable, but view will show TWikiGuest instead of your WikiName.
  • TWiki can be configured to remember the IP address/username pair whenever an authentication happens (edit topic, attach file). Once remembered, the non-authenticated scripts, like view, will show the correct username instead of TWikiGuest.
  • Enable this feature by setting the $doRememberRemoteUser flag in TWiki.cfg. TWiki then persistently stores the IP address/username pairs in the file, $remoteUserFilename, which is "$dataDir/remoteusers.txt" by default.
  • Copy the view script to viewauth (or better, create a symbolic link)
  • Add viewauth to the list of authenticated scripts in the twiki/bin/.htaccess file. The view script should not be listed in the .htaccess file.
  • 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.

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

NOTE: To correctly enter a WikiName - your own or someone else's - be sure to include the Main web name in front of the Wiki username, followed by a period, and no spaces. Ex:
Main.WikiUsername or %MAINWEB%.WikiUsername
This points WikiUser to the TWiki.Main web, where user registration pages are stored, no matter which web it's entered in. Without the web prefix, the name appears as a NewTopic? everywhere but in the Main web.

Changing Passwords

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

Forgot your old password? Then use ResetPassword instead. Please only use ResetPassword 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.

If you have questions please contact the TWiki webmaster dkessler@operamail.com.

Please only use this ResetPassword form in case you really forgot your password. Otherwise just change it using ChangePassword. Thank you.

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

After submitting this form you will see a page with your new password appearing encrypted.

You will have to e-mail this information to the Wiki webmaster, dkessler@operamail.com, who will set your account to use the new password.

-- TWiki:Main.MikeMannix - 19 May 2002
-- TWiki:Main.PeterThoeny - 25 Apr 2004

TWiki Access Control

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

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

An Important Control Consideration

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

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

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

  • In TWiki, content is transparently preserved under revision control:
    • Edits can be undone by the TWikiAdminGroup (the default administrators group; see #ManagingGroups).
    • Users are encouraged to edit and refactor (condense a long topic), since there's a safety net.

As a collaboration guideline:

  • Create broad-based Groups (for more and varied input), and...
  • Avoid creating view-only Users (if you can read it, you should be able to contribute to it).

Authentication vs. Access Control

Authentication: Identifies who a user is based on a login procedure. See TWikiUserAuthentication.

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

Users and Groups

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

Managing Users

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

  • WikiName and encrypted password are recorded in .htpasswd if authentication is enabled.
  • A confirmation e-mail is sent to the user.
  • A user home page with the WikiName of the user is created in the Main web.
  • The user is added to the TWikiUsers topic.

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

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

Managing Groups

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

  1. Edit TWikiGroups by entering a new topic with a name that ends in Group. Example:
    • SomeGroup
  2. Set Preferences for two Variables in the new group topic:
    • Set GROUP = < list of Users and/or Groups >
    • Set ALLOWTOPICCHANGE = < list of Users and/or Groups >
    • The GROUP variable is a comma-separated list of Users and/or other Groups. Example:
      • Set GROUP = Main.SomeUser, Main.OtherUser, Main.SomeGroup
    • ALLOWTOPICCHANGE defines who is allowed to change the group topic; it is a comma delimited list of Users and Groups. You typically want to restrict that to the members of the group itself, so it should contain the name of the topic. (This prevents Users not in the Group from editing the topic to give themselves or others access. For example, for the TWikiAdminGroup topic write:
    • Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup

Restricting Write Access

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

Deny Editing by Topic

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

  • Define one or both of these variables in a topic, preferably at the end of the page:
    • Set DENYTOPICCHANGE = < list of Users and Groups >
    • Set ALLOWTOPICCHANGE = < list of Users and Groups >

  • DENYTOPICCHANGE defines Users or Groups that are not allowed to make changes to the topic, with a comma-delimited list. Example:
    • Set DENYTOPICCHANGE = Main.SomeBadBoy, Main.SomeBadGirl, Main.SomeHackerGroup

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

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

Deny Editing by Web

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

  • Define one or both of these variable in the WebPreferences topic:
    • Set DENYWEBCHANGE = < list of Users and Groups >
    • Set ALLOWWEBCHANGE = < list of Users and Groups >

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

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

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.

  • Define one or both of these variables in a topic, preferably at the end of the topic:
    • Set DENYTOPICRENAME = < list of Users and Groups >
    • Set ALLOWTOPICRENAME = < list of Users and Groups >

  • DENYTOPICCRENAME defines Users or Groups that are not allowed to rename the topic. It is a comma delimited list of Users and Groups. Example:
    • Set DENYTOPICRENAME = Main.SomeBadBoy, Main.SomeBadGirl, Main.SomeHackerGroup

  • ALLOWTOPICRENAME defines Users or Groups that are allowed to rename the topic. It is a comma delimited list of Users and Groups. Example:
    • Set ALLOWTOPICRENAME = Main.SomeGoodGuy, Main.SomeGoodGirl, Main.TWikiAdminGroup

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

Deny Renaming by Web

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

  • Define one or both of these variable in the WebPreferences topic:
    • Set DENYWEBRENAME = < list of Users and Groups >
    • Set ALLOWWEBRENAME = < list of Users and Groups >

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

  • DENYTOPICRENAME (in topic) overrides DENYWEBRENAME (in WebPreferences)
  • ALLOWTOPICRENAME (in topic) overrides ALLOWWEBRENAME (in WebPreferences)

Restricting Read Access

You can define who is allowed to see a web.

Deny Viewing by Topic

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

Deny Viewing by Web

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

  • obfuscating webs: Insecure but handy method to hide new webs until content is ready for deployment.
  • authenticating all webs and restricting selected webs: Topic access in all webs is authenticated, and selected webs have restricted access.
  • authenticating and restricting selected webs only: Provide unrestricted viewing access to open webs, with authentication and restriction only on selected webs.

Obfuscate Webs

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

  • Set NOSEARCHALL = on

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

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

Authenticate all Webs and Restrict Selected Webs

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

  1. Restrict view access to selected Users and Groups. Set one or both of these variables in its WebPreferences topic:
    • Set DENYWEBVIEW = < list of Users and Groups >
    • Set ALLOWWEBVIEW = < list of Users and Groups >
    • Note: DENYWEBVIEW is evaluated before ALLOWWEBVIEW. Access is denied if the authenticated person is in the DENYWEBVIEW list, or not in the ALLOWWEBVIEW list. Access is granted in case DENYWEBVIEW and ALLOWWEBVIEW is not defined.
  2. Hide the web from an "all webs" search. Enable this restriction with the NOSEARCHALL variable in its WebPreferences topic:
    • Set NOSEARCHALL = on
  3. Add view to the list of authenticated scripts in the .htaccess file.

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

Authenticate and Restricting Selected Webs Only

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

  1. Restrict view access to selected Users and Groups. Set one or both of these variables in its WebPreferences topic:
    • Set DENYWEBVIEW = < list of Users and Groups >
    • Set ALLOWWEBVIEW = < list of Users and Groups >
    • Note: DENYWEBVIEW is evaluated before ALLOWWEBVIEW. Access is denied if the authenticated person is in the DENYWEBVIEW list, or not in the ALLOWWEBVIEW list. Access is granted in case DENYWEBVIEW and ALLOWWEBVIEW is not defined.
  2. Hide the web from an "all webs" search. Enable this restriction with the NOSEARCHALL variable in its WebPreferences topic:
    • Set NOSEARCHALL = on
  3. Enable the $doRememberRemoteUser flag in lib/TWiki.cfg as described in TWikiUserAuthentication. TWiki will now remember the IP address of an authenticated user.
  4. Copy the view script to viewauth (or better, create a symbolic link)
  5. Add viewauth to the list of authenticated scripts in the .htaccess file. The view script should not be listed in the .htaccess file.

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

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

Hiding Control Settings

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

<!--
   * 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 no-one can edit it from a browser. To avoid this, you can create Web-based superusers:

  • Set the $superAdminGroup variable in lib/TWiki.cfg to the name of a group of Users who are always allowed to edit/view topics. 
$superAdminGroup = "TWikiAdminGroup";
  • The default setting is not to have superusers.

-- TWiki:Main.PeterThoeny - 04 May 2002
-- TWiki:Main.MikeMannix - 12 May 2002

Note: Included topic TWikiTemplatingSystem? does not exist yet

TWiki Skins

Skins overlay regular templates with alternate header/footer layouts; topic text is not affected

Overview

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

Defining Skins

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

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

Variables in Skins

You can use template variables, TWikiVariables, and other predefined variables to compose your skins. Some commonly used variables in skins:

Variable: Expanded to:
%WIKILOGOURL% Link of page logo
%WIKILOGOIMG% Image URL of page logo
%WIKILOGOALT% Alt text of page logo
%WEBBGCOLOR% Web specific background color, defined in the WebPreferences
%WIKITOOLNAME% The name of your TWiki site
%SCRIPTURL% The script URL of TWiki
%SCRIPTSUFFIX% The script suffix, ex: .pl, .cgi
%WEB% The name of the current web. Note: It is recommended to URL-encode the variable in form actions with %INTURLENCODE{"%WEB%"}% for proper handling in an internationalized environment
%TOPIC% The name of the current topic. Note: It is recommended to URL-encode the variable in form actions with %INTURLENCODE{"%TOPIC%"}% for proper handling in an internationalized environment
%WEBTOPICLIST% Common links of current web, defined in the WebPreferences. It includes a #GoBox
%TEXT% The topic text, e.g. the content that can be edited
%META{"form"}% TWikiForm, if any
%META{"attachments"}% FileAttachment table
%META{"parent"}% The topic parent
%EDITTOPIC% Edit link
%REVTITLE% The revision title, if any, ex: (r1.6)
%REVINFO% Revision info, ex: r1.6 - 24 Dec 2002 - 08:12 GMT - TWikiGuest
%WEBCOPYRIGHT% Copyright notice, defined in the WebPreferences
%BROADCASTMESSAGE% Broadcast message at the beginning of your view template, can be used to alert users of scheduled downtimes; is set in TWikiPreferences

The "Go" Box and Navigation Box

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

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

Bare bones header for demo only
Welcome | Register | Changes | Topics | Index | Search | Go

Using Cascading Style Sheets

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

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

<style type="text/css">
.broadcastmessage {
    background: yellow; display:block;
    border-style:solid;border-width: 2px;border-color:red;
}
.broadcastmessage strong {color: red}
</style>

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

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

Attachment Tables

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

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

Macro Description
ATTACH:files:header Standard title bar
ATTACH:files:row Standard row
ATTACH:files:footer Footer for all screens
ATTACH:files:header:A Title bar for upload screens, with attributes column
ATTACH:files:row:A Row for upload screen
ATTACH:files:footer:A Footer for all screens
The format of tables of file versions in the Upload screen are also formattable, using the macros:
Macro Description
ATTACH:versions:header Header for versions table on upload screen
ATTACH:versions:row Row format for versions table on upload screen
ATTACH:versions:footer Footer for versions table on upload screen

The ATTACH:row macros are expanded for each file in the attachment table, using the following special tags:

Tag Description
%A_URL% URL that will recover the file
%A_REV% Revision of this file e.g. "1.1"
%A_ICON% A file icon suitable for representing the attachment content
%A_FILE% The name of the file
%A_SIZE% The size of the file
%A_DATE% The date the file was uploaded
%A_USER% The user who uploaded it
%A_COMMENT% The comment they put in when uploading it
%A_ATTRS% The attributes of the file as seen on the upload screen e.g "h" for a hidden file

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

Packaging and Publishing Skins

See TWiki:Plugins/SkinPackagingHowTo and TWiki:Plugins/SkinDeveloperFAQ

Browsing Installed Skins

You can try all installed skins in TWikiSkinBrowser.

Activating Skins

A skin can be activated in two ways:

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

-- TWiki:Main.PeterThoeny - 25 Jul 2004
-- TWiki:Main.CrawfordCurrie - 30 Jun 2004

TWiki Variables

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

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

Notes:

  • To leave a variable unexpanded, precede it with an exclamation point, e.g. type !%TOPIC% to get %TOPIC%.
  • Variables are expanded relative to the topic they are used in, not the topic they are defined in.

Predefined Variables

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

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

This version of TWiki - 01 Sep 2004 $Rev: 1742 $ - expands the following variables (enclosed in % percent signs):

ATTACHURL -- full URL for attachments in the current topic

ATTACHURLPATH -- path of the attachment URL of the current topic

BASETOPIC -- base topic where an INCLUDE started

  • The name of the topic where a single or nested INCLUDE started - same as %TOPIC% if there is no INCLUDE
  • Syntax: %BASETOPIC%
  • Related: BASEWEB, INCLUDINGTOPIC, INCLUDE, TOPIC

BASEWEB -- base web where an INCLUDE started

  • 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.
  • Syntax: %BASEWEB%
  • Related: BASETOPIC, INCLUDINGWEB, INCLUDE, WEB

DISPLAYTIME -- display time

DISPLAYTIME{"format"} -- formatted display time

  • Formatted time - either GMT or Local server time, depending on setting in TWiki.cfg. Same format qualifiers as %GMTIME%
  • Syntax: %DISPLAYTIME{"format"}%
  • Example: %DISPLAYTIME{"$hou:$min"}% expands to 16:22
  • Related: DISPLAYTIME, GMTIME, SERVERTIME

ENCODE{"string"} -- encodes a string

  • Syntax: %ENCODE{"string"}%
  • Supported parameters:
    Parameter: Description: Default:
    "string" String to encode required (can be empty)
    type="entity" Encode special characters into HTML entities, like a double quote into &#034; URL encoding
    type="url" Encode special characters for URL parameter use, like a double quote into %22 (this is the default)
  • Example: %ENCODE{"spaced name"}% expands to spaced%20name
  • Related: URLPARAM

FORMFIELD{"format"} -- renders a field in the form attached to some topic

  • Syntax: %FORMFIELD{"fieldname"}%
  • Supported parameters:
    Parameter: Description: Default:
    "fieldname" The name of a TWiki form field required
    topic="..." Topic where form data is located. May be of the form Web.TopicName Current topic
    format="..." Format string. $value expands to the field value "$value"
    default="..." Text shown when no value is defined for the field ""
    alttext="..." Text shown when field is not found in the form ""
  • Example: %FORMFIELD{"ProjectName" topic="Projects.SushiProject" default="(not set)" alttext="ProjectName field found"}%
  • Related: SEARCH

GMTIME -- GM time

GMTIME{"format"} -- formatted GM time

  • Syntax: %GMTIME{"format"}%
  • Supported variables:
    Variable: Unit: Example
    $seconds seconds 59
    $minutes minutes 59
    $hours hours 23
    $day day of month 31
    $wday day of the Week (Sun, Mon, Tue, Wed, Thu, Fri, Sat) Thu
    $month month in ISO format Dec
    $mo 2 digit month 12
    $year 4 digit year 1999
    $ye 2 digit year 99
    $tz either "GMT" (if set to gmtime), or "Local" (if set to servertime) GMT
    $iso ISO format timestamp 2025-05-03T16:22Z
    $rcs RCS format timestamp 2025/05/03 16:22:30
    $http E-mail & http format timestamp Sat, 03 May 2025 16:22:30 GMT
  • Variables can be shortened to 3 characters
  • Example: %GMTIME{"$day $month, $year - $hour:$min:$sec"}% expands to 03 May, 2025 - 16:22:30
  • Related: DISPLAYTIME, GMTIME, SERVERTIME

HOMETOPIC -- home topic in each web

HTTP_HOST -- environment variable

ICON{"type"} -- small icon of common attachment types

  • Small 16x16 pixel icon of common attachment types. Specify file type only, file name, or full path name
  • Syntax: %ICON{"type"}%
  • Samples: bmp, doc, gif, hlp, html, mp3, pdf, ppt, txt, xls, xml, zip
  • Example: %ICON{"pdf"}% expands to
  • Related: TWikiPreferences, FileAttachments, TWikiDocGraphics

INCLUDE{"page"} -- include other topics or web pages

  • Syntax: %INCLUDE{"page" ...}%
  • Supported parameters:
    Parameter: Description: Default:
    "SomeTopic" The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}%  
    "Web.Topic" A topic in another web, i.e. %INCLUDE{"TWiki.SiteMap"}%  
    "http://..." A full qualified URL, i.e. %INCLUDE{"http://twiki.org/"}%
    Note if the URL resolves to an attachment file on the server this will automatically translate to a server-side include.     		 
    pattern="..." A RegularExpression pattern to include a subset of a topic or page none
    rev="1.2" Include a previous topic revision; N/A for URLs top revision
    warn="off" Warn if topic include fails: Fail silently (if off); output default warning (if set to on); else, output specific text (use $topic for topic name) %INCLUDE- WARNING% preferences setting
  • Related: BASETOPIC, BASEWEB, INCLUDINGTOPIC, INCLUDINGWEB, IncludeTopicsAndWebPages, STARTINCLUDE, STOPINCLUDE,

INCLUDINGTOPIC -- name of topic that includes current topic

  • The name of the topic that includes the current topic - same as %TOPIC% in case there is no include
  • Syntax: %INCLUDINGTOPIC%
  • Related: BASETOPIC, INCLUDINGWEB, INCLUDE, TOPIC

INCLUDINGWEB -- web that includes current topic

  • The web name of the topic that includes the current topic - same as %WEB% if there is no INCLUDE.
  • Syntax: %INCLUDINGWEB%
  • Related: BASEWEB, INCLUDINGTOPIC, INCLUDE, WEB

MAINWEB -- name of Main web

METASEARCH -- special search of meta data

  • Syntax: %METASEARCH{...}%
  • Supported parameters:
    Parameter: Description: Default:
    type="topicmoved" What sort of search is required?
    "topicmoved" if search for a topic that may have been moved
    "parent" if searching for topics that have a specific parent i.e. its children     		required
    web="%WEB%" Wiki web to search: A web, a list of webs separated by whitespace, or all webs. current web
    topic="%TOPIC%" The topic the search relates to current topic
    title="Title" Text that is prefixed to any search results empty
    default="none" Default text shown if no search hit empty
  • Example: %METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%
  • Example: You may want to use this in WebTopicViewTemplate and WebTopicNonWikiTemplate:
    %METASEARCH{type="parent" web="%WEB%" topic="%TOPIC%" title="Children: "}%
  • Related: SEARCH

NOTIFYTOPIC -- name of the notify topic

PLUGINVERSION -- the version of the TWiki Plugin API

PLUGINVERSION{"name"} -- the version of an installed Plugin

  • Syntax: %PLUGINVERSION{"name"}%
  • Example: %PLUGINVERSION{"DefaultPlugin"}% expands to 1.021
  • Related: PLUGINVERSION, WIKIVERSION

PUBURL -- the base URL of attachments

  • Syntax: %PUBURL%
  • Expands to: http://pyqplayer.sourceforge.net/pub
  • Example: You can refer to a file attached to another topic with %PUBURL%/%WEB%/OtherTopic/image.gif
  • Related: ATTACHURL, PUBURLPATH, SCRIPTURL, FileAttachments

PUBURLPATH -- the base URL path of attachments

REMOTE_ADDR -- environment variable

REMOTE_PORT -- environment variable

REMOTE_USER -- environment variable

REVINFO -- revision information of current topic

REVINFO{"format"} -- formatted revision information of topic

  • Syntax: %REVINFO{"format"}%
  • Supported parameters:
    Parameter: Description: Default:
    "format" Format of revision information, see supported variables below "r1.$rev - $date - $wikiusername"
    web="..." Name of web Current web
    topic="..." Topic name Current topic
    rev="1.5" Specific revison number Latest revision
  • Supported variables in format:
    Variable: Unit: Example
    $web Name of web Current web
    $topic Topic name Current topic
    $rev Revison number. Prefix r1. to get the usual r1.5 format 5
    $date Revision date 11 Jul 2004
    $username Login username of revision jsmith
    $wikiname WikiName of revision JohnSmith
    $wikiusername WikiName with Main web prefix Main.JohnSmith
  • Example: %REVINFO{"$date - $wikiusername" rev="1.1"}% returns revision info of first revision
  • Related: REVINFO

SCRIPTURL -- script URL of TWiki

  • Syntax: %SCRIPTURL%
  • Expands to: http://pyqplayer.sourceforge.net/cgi-bin/bin
  • Example: To get the authenticated version of current topic write %SCRIPTURL%/viewauth%SCRIPTSUFFIX%/%WEB%/%TOPIC% which expands to http://pyqplayer.sourceforge.net/cgi-bin/bin/viewauth/TWiki/TWikiVariablesNtoZ
  • Related: PUBURL, SCRIPTSUFFIX, SCRIPTURLPATH

SCRIPTURLPATH -- script URL path of TWiki

SCRIPTSUFFIX -- script suffix

  • Some TWiki installations require a file extension for CGI scripts like .pl or .cgi
  • Syntax: %SCRIPTSUFFIX%
  • Expands to:
  • Related: SCRIPTURL

SEARCH{"text"} -- search content

  • Inline search, shows a search result embedded in a topic
  • Syntax: %SEARCH{"text" ...}%
  • Supported parameters: [1]
    Parameter: Description: Default:
    "text" Search term. Is a keyword search, literal search or regular expression search, depending on the type parameter. SearchHelp has more required
    search="text" (Alternative to above) N/A
    web="Name"
    web="Main, Know"
    web="all"     		Wiki web to search: A web, a list of webs separated by comma, or all webs. [2] Current web
    topic="WebPreferences"
    topic="*Bug"     		Limit search to topics: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. All topics in a web
    excludetopic="Web*"
    excludetopic="WebHome, WebChanges"     		Exclude topics from search: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. None
    type="keyword"
    type="literal"
    type="regex"     		Do a keyword search like soap "web service" -shampoo; a literal search like web service; or RegularExpression search like soap;web service;!shampoo %SEARCHVAR- DEFAULTTYPE% preferences setting (literal)
    scope="topic"
    scope="text"
    scope="all"     		Search topic name (title); the text (body) of topic; or all (both) "text"
    order="topic"
    order="created"
    order="modified"
    order="editby"
    order=
     "formfield(name)"         		Sort the results of search by the topic names, topic creation time, last modified time, last editor, or named field of TWikiForms. The sorting is done web by web; in case you want to sort across webs, create a formatted table and sort it with TablePlugin's initsort Sort by topic name
    limit="all"
    limit="16"     		Limit the number of results returned. This is done after sorting if order is specified All results
    reverse="on" Reverse the direction of the search Ascending search
    casesensitive="on" Case sensitive search Ignore case
    nosummary="on" Show topic title only Show topic summary
    bookview="on" BookView search, e.g. show complete topic text Show topic summary
    nosearch="on" Suppress search string Show search string
    noheader="on" Suppress search header
    Topics: Changed: By:     		Show search header
    nototal="on" Do not show number of topics found Show number
    header="..."
    format="..."     		Custom format results: see FormattedSearch for usage, variables & examples Results in table
    expandvariables="on" Expand variables before applying a FormattedSearch on a search hit. Useful to show the expanded text, e.g. to show the result of a SpreadSheetPlugin %CALC{}% instead of the formula Raw text
    multiple="on" Multiple hits per topic. Each hit can be formatted. The last token is used in case of a regular expression ";" and search Only one hit per topic
    separator=", " Line separator between hits Newline "$n"
  • Example: %SEARCH{"wiki" web="Main" scope="topic"}%
  • Example with format: %SEARCH{"FAQ" scope="topic" nosearch="on" nototal="on" header="| *Topic: * | *Summary: * |" format="| $topic | $summary |"% (displays results in a table with header - details)
  • HELP If the TWiki:Plugins.TablePlugin is installed, you may set a %TABLE{}% variable just before the %SEARCH{}% to alter the output of a search. Example: %TABLE{ tablewidth="90%" }%
  • Related: METASEARCH, TOPICLIST, WEBLIST, FormattedSearch

  • [1] Note: The search form uses identical names for input fields.
  • [2] Note: A web can be excluded from a web="all" search if you define a NOSEARCHALL=on variable in its WebPreferences

SERVERTIME -- server time

SERVERTIME{"format"} -- formatted server time

  • Same format qualifiers as %GMTIME%
  • Syntax: %SERVERTIME{"format"}%
  • Example: %SERVERTIME{"$hou:$min"}% expands to 16:22
  • Related: DISPLAYTIME, GMTIME, SERVERTIME

SPACEDTOPIC -- topic name, spaced and encoded

  • The current topic name with added spaces, for regular expression search of Ref-By
  • Syntax: %SPACEDTOPIC%
  • Expands to: TWiki%20*Variables%20*Nto%20*Z
  • Related: TOPIC

STARTINCLUDE -- start position of topic text if included

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

STATISTICSTOPIC -- name of statistics topic

STOPINCLUDE -- end position of topic text if included

  • If present in included topic, stop to include text at this location and ignore the remaining text. A normal view of the topic shows everyting exept the %STOPINCLUDE% variable itself.
  • Syntax: %STOPINCLUDE%
  • Related: INCLUDE, STARTINCLUDE

TOC -- table of contents of current topic

TOC{"Topic"} -- table of contents

  • Syntax: %TOC{"SomeTopic" ...}%
  • Table of Contents. Shows a TOC that is generated automatically based on headings of a topic. Headings in WikiSyntax ("---++ text") and HTML ("<h2>text</h2>") are taken into account. Any heading text after "!!" is excluded from the TOC; for example, write "---+!! text" if you do not want to list a header in the TOC
  • Supported parameters:
    Parameter: Description: Default:
    "TopicName" topic name Current topic
    web="Name" Name of web Current web
    depth="2" Limit depth of headings shown in TOC 6
    title="Some text" Title to appear at top of TOC none
  • Example: %TOC{depth="2"}%
  • Example: %TOC{"TWikiDocumentation" web="TWiki" title="Contents:"}%
  • Example: see TWiki:Sandbox.TestTopicInclude
  • Related: TOC

TOPIC -- name of current topic

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.
  • Syntax: %TOPICLIST{"format" ...}%
  • Supported parameters:
    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
  • Example: %TOPICLIST{"   * $web.$name"}% creates a bullet list of all topics
  • Example: %TOPICLIST{separator=", "}% creates a comma separated list of all topics
  • Example: %TOPICLIST{" <option>$name</option>"}% creates an option list (for drop down menus)
  • Related: SEARCH, WEBLIST

TWIKIWEB -- name of TWiki documentation web

  • The web containing all documentation and site-wide preference settings for TWiki
  • Syntax: %TWIKIWEB%
  • Expands to: TWiki
  • Related: MAINWEB

URLPARAM{"name"} -- get value of a URL parameter

  • Returns the value of a URL parameter. Note that there is a risk that this variable could be misused for cross-scripting
  • Syntax: %URLPARAM{"name"}%
  • Supported parameters:
    Parameter: Description: Default:
    "name" The name of a URL parameter required
    default="..." Default value in case parameter is empty or missing empty string
    newline="<br />" Convert newlines in textarea to other delimiters no conversion
    encode="entity" Encode special characters into HTML entities, like a double quote into &#034;. This is needed if text is put into an HTML form field no encoding
    encode="url" Encode special characters for URL parameter use, like a double quote into %22 no encoding
    multiple="on"
    multiple="[[$item]]"     		If set, gets all selected elements of a <select multiple="multiple"> tag. A format can be specified, with $item indicating the element, e.g. multiple="Option: $item" first element
    separator=", " Separator between multiple selections. Only relevant if multiple is specified "\n" (new line)
  • Example: %URLPARAM{"skin"}% returns print for a .../view/TWiki/TWikiVariablesNtoZ?skin=print URL. Test this:
  • Related: SEARCH, FormattedSearch

USERNAME -- your login username

VAR{"NAME" web="Web"} -- get a preference value from another web

  • Syntax: %VAR{"NAME" web="Web"}%
  • Example: To get %WEBBGCOLOR% of the Main web write %VAR{"WEBBGCOLOR" web="Main"}%, which expands to #FFEFA6
  • Related: WEBPREFSTOPIC

WEB -- name of current web

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

  • List of all webs. Hidden webs are excluded, e.g. webs with a NOSEARCHALL=on preference variable. The "format" defines the format of one web item. The $name variable gets expanded to the name of the web, $qname gets expanded to double quoted name, $marker to marker where web matches selection.
  • Syntax: %WEBLIST{"format" ...}%
  • Supported parameters:
    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%"
  • Example: %WEBLIST{"   * [[$name.WebHome]]"}% creates a bullet list of all webs.
  • Example: %WEBLIST{"<option $marker value=$qname>$name</option>" webs="Trash,public" selection="TWiki" separator=" "}% Dropdown of all public Webs + Trash Web, current Web highlighted.
  • Related: TOPICLIST, SEARCH

WEBPREFSTOPIC -- name of web preferences topic

WIKIHOMEURL -- site home URL

  • The base URL of TWiki, is the link of the Home icon in the upper left corner, defined in TWiki.cfg
  • Syntax: %WIKIHOMEURL%
  • Expands to: http://your.domain.com/twiki
  • Related: WIKITOOLNAME

WIKINAME -- your Wiki username

WIKIPREFSTOPIC -- name of site-wide preferences topic

WIKITOOLNAME -- name of your TWiki site

WIKIUSERNAME -- your Wiki username with web prefix

  • Your %WIKINAME% with Main web prefix, useful to point to your TWiki home page
  • Syntax: %WIKIUSERNAME%
  • Expands to: Main.TWikiGuest, renders as TWikiGuest
  • Related: REMOTE_USER, USERNAME, WIKINAME

WIKIUSERSTOPIC -- name of topic listing all registers users

  • Syntax: %WIKIUSERSTOPIC%
  • Expands to: TWikiUsers, with Main prefix renders as TWikiUsers
  • Related: WIKIUSERNAME

WIKIVERSION -- the version of the installed TWiki engine

Note: Above text is included from TWikiVariablesAtoM and TWikiVariablesNtoZ

Preferences Variables

Additional variables are defined in the preferences topics:

Variable: Level: What: Expands to:
%ALLOWTOPICCHANGE% (any topic) List of users and groups who are allowed to change the current topic. (More in TWikiAccessControl)  
%ALLOWTOPICRENAME% (any topic) List of users and groups who are allowed to rename the current topic. (More in TWikiAccessControl) TWikiAdminGroup  
%ALLOWWEBCHANGE% WL List of users and groups who are allowed to change topics in the TWiki web. (More in TWikiAccessControl)  
%ALLOWWEBRENAME% WL List of users and groups who are allowed to rename topics in the TWiki web. (More in TWikiAccessControl)  
%ATTACHLINKBOX% SL , UL Default state of the link check box in the attach file page. Check box is initially checked if value is set to CHECKED , unchecked if empty. If checked, a link is created to the attached file at the end of the topic. Value is:  
%DENYTOPICCHANGE% (any topic) List of users and groups who are not allowed to change the current topic. (More in TWikiAccessControl) %DENYTOPICCHANGE%  
%DENYTOPICRENAME% (any topic) List of users and groups who are not allowed to rename the current topic. (More in TWikiAccessControl) %DENYTOPICRENAME%  
%DENYWEBCHANGE% WL List of users and groups who are not allowed to change topics in the TWiki web. (More in TWikiAccessControl)  
%DENYWEBRENAME% WL List of users and groups who are not allowed to rename topics in the TWiki web. (More in TWikiAccessControl)  
%DONTNOTIFYCHECKBOX% SL , UL Default state of the "Minor Changes, Don't Notify" (DontNotify) check box in preview. Check box is initially checked if Set DONTNOTIFYCHECKBOX = checked="checked", or unchecked if empty. Value is:  
%EDITBOXHEIGHT% SL , UL Vertical size of edit box, is 17 17  
%EDITBOXWIDTH% SL , UL Horizontal size of edit box, is 70 70  
%EDITBOXSTYLE% SL , UL Style of text edit box. Set to width: 99% for full window width (default; overwrites the EDITBOXWIDTH setting), or width: auto to disable. Value is: width: 99% width: 99%  
%FINALPREFERENCES% SL , WL List of preferences that are not allowed to be overridden by next level preferences ATTACHFILESIZELIMIT, PREVIEWBGIMAGE, WIKITOOLNAME, WIKIWEBMASTER, SMTPMAILHOST, SMTPSENDERHOST, ALLOWWEBMANAGE, READTOPICPREFS, TOPICOVERRIDESUSER, NOSEARCHALL, ATTACHFILESIZELIMIT, WIKIWEBMASTER, WEBCOPYRIGHT, WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, DENYWEBRENAME, ALLOWWEBRENAME  
%HTTP_EQUIV_ON_EDIT% SL , UL http-equiv meta tags for edit script.  
%HTTP_EQUIV_ON_PREVIEW% SL , UL http-equiv meta tags for preview script.  
%HTTP_EQUIV_ON_VIEW% SL http-equiv meta tags for view, rdiff, attach, search* scripts.  
%NEWTOPICBGCOLOR% SL , UL Background color of non existing topic. ( UL needs authentication for topic views ) #FFFFCE  
%NEWTOPICFONTCOLOR% SL , UL Font color of non existing topic. ( UL needs authentication for topic views ) #0000FF  
%NOSEARCHALL% WL Exclude web from a web="all" search (set variable to on for hidden webs)  
%RELEASEEDITLOCKCHECKBOX% SL , UL Default state of the "Release edit lock" (UnlockTopic) check box in preview. Checkbox is initially checked if Set RELEASEEDITLOCKCHECKBOX = checked="checked", or unchecked if empty. If checked, make sure to click on Edit to do more changes; do not go back in your browser to the edit page, or you risk that someone else will edit the topic at the same time! Value is:  
%WEBBGCOLOR% WL Background color of web #FFD8AA  
%WEBCOPYRIGHT% SL , WL Copyright notice (bottom right corner of topics) Copyright © 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Project hosting provided by:
SourceForge.net Logo		Donations welcome:
Support This Project
 
%WEBTOPICLIST% WL Common links of web (second line of topics) Welcome | Register | Changes | Topics | Index | Search | Go  
%WIKIWEBLIST% SL List of TWiki webs (in upper right corner of topics) Main | TWiki | Sandbox  
%WIKIWEBMASTER% SL Webmaster email address (sender of email notifications) , is dkessler@operamail.com dkessler@operamail.com  

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

Setting Preferences

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

Creating Custom Variables

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

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

-- TWiki:Main.PeterThoeny - 14 Aug 2004
-- TWiki:Main.MikeMannix - 12 May 2002

Merged into TWikiMetaData - this topic to be rolled back.

Note: Included topic TWikiFormTemplate? does not exist yet

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 a set of Plugins as part of the standard installation.

  • DefaultPlugin: Optionally handles some legacy variables from older versions of TWiki. You can control this option from TWikiPreferences. (Perl programmers can also add rules for simple custom processing.)
  • EmptyPlugin: Is a fully functional module, minus active code; it does nothing and serves as a template for new Plugin development
  • CommentPlugin: Allows users to quickly post comments to a page without an edit/preview/save cycle.
  • InterwikiPlugin: Use it for shorthand linking to remote sites, ex: TWiki:Plugins expands to TWiki:Plugins on TWiki.org. You can edit the predefined set of of Wiki-related sites, and add your own
  • EditTablePlugin: Edit TWiki tables using edit fields, date pickers and drop down boxes
  • 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 TWiki topics.
  • TablePlugin: Control attributes of tables and sorting of table columns

Installing Plugins

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

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

  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, and adjust the paths in the new lib/TWiki.cfg. The following directories are shared: twiki/data, twiki/templates and twiki/pub.
    • 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.

Checking that Plugins are Working on a Live Server

InstalledPlugins shows which Plugins are: 1) installed, 2) loading properly and 3) what TWiki:Codev.PluginHandlers they invoke. Any failures are shown in the Errors section.

A Note on Plugin Performance

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

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

Managing Plugins

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

Setting Preferences

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

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

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

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

  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, SpreadSheetPlugin, CommentPlugin, EditTablePlugin, InterwikiPlugin, RenderListPlugin, SlideShowPlugin, SmiliesPlugin, 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 depreciated *_text_* as bold italic text.
  • SpreadSheetPlugin: Add spreadsheet calculation like "$SUM( $ABOVE() )" to tables located in TWiki topics.
  • 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!
  • TablePlugin: Control attributes of tables and sorting of table columns

The TWiki Plugin API

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

Available Core Functions

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

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.

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

  • commonTagsHandler: Use it to expand %XYZPLUGIN% and %XYZPLUGIN{...}% variables
  • startRenderingHandler: Use it for your own rendering rules or to overload TWiki's internal rendering like [[links]]

TWiki:Codev/StepByStepRenderingOrder helps you decide which rendering handler to use.

Hints on Writing Fast Plugins

  • Delay the Plugin initialization to the actual function which is handling the tag. This way all the expensive initialization is done only when needed.
  • For example, use an eval block like:
    eval { require IPC::Run }
    return "<font color=\"red\">SamplePlugin: Can't load required modules ($@)</font>" if $@;
  • You could return errors as strings to show what happened
  • You can use a flag to avoid running the initialization twice

Plugin Version Detection

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

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

  • The initPlugin handler should check all dependencies and return TRUE if the initialization is OK or FALSE if something went wrong.
    • The Plugin initialization code does not register a Plugin that returns FALSE (or that has no initPlugin handler).

  • $TWiki::Plugins::VERSION in the TWiki::Plugins module contains the TWiki Plugin API version, currently 1.025.
    • You can also use the %PLUGINVERSION{}% variable to query the Plugin API version or the version of installed Plugins.

Creating Plugins

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

The DefaultPlugin Alternative

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

Anatomy of a Plugin

A basic TWiki Plugin consists of two elements:

  • a Perl module, ex: MyFirstPlugin.pm
  • a documentation topic, ex: MyFirstPlugin.txt

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

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

Creating the Perl Module

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

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

  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 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/PluginPackage. Publish your Plugin in these steps:

  1. Post the Plugin documentation topic in the TWiki:Plugins/PluginPackage:
    • enter the Plugin name in the "How to Create a Plugin" section, for example MyFirstPlugin
    • paste in the topic text from Creating Plugin Documentation and save
  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.)
  4. Put the Plugin into the CVS repository, see TWiki:Plugins/ReadmeFirst (optional)

Thank you very much for sharing your Plugin with the TWiki community smile

Recommended Storage of Plugin Data

Plugins sometimes need to store data. This can be Plugin internal data like cache data, or generated data for the browser like images. The following is a recommendation where to store the data.

Where to store Plugin Internal Data

In case the Plugin generates data just for internal use, or data which is not specific to a topic, store it in the Plugin's attachment directory.

  • The Plugin's attachment directory is pubdir/Installweb/FooBarPlugin
    • Installweb refers to the name of the web where the Plugin is installed
  • The Plugin's attachment URL is %PUBURL%/Installweb/FooBarPlugin
  • The filename should start with an underscore, followed by an identifier, e.g. _any_name.ext
    • The leading underscore avoids a nameclash with files attached to the Plugin topic
    • Use only alphanumeric characters, underscores and periods to avoid platform dependency issues and URL issues
    • Do not use subdirectories (rename and delete would fail)
  • Use Plugin API functions documented in TWikiFuncModule to ensure portability:
    • Use getPubDir() to get the attachment root directory
    • Use getUrlHost() and getPubUrlPath() to build the URL in case you create content for the browser
    • Use $installWeb to get the name of the web where the Plugin is installed
    • Create the web directory and topic attachment directory if needed
  • Hint: Package the Plugin at least with one file attachment. This ensures that the attachment directory already exists

Where to Store Data for Topics using the Plugin

In case the Plugin generates data which is specific to a topic, store it in the topic's attachment directory.

  • The topic's attachment directory is pubdir/Webname/TopicName
  • The topic's attachment URL is %PUBURL%/Webname/TopicName
  • The filename should start with an underscore, followed by the Plugin name, an underscore and an identifier, e.g. _FooBarPlugin_any_name.ext
    • The leading underscore avoids a nameclash with files attached to the same topic
    • Use only alphanumeric characters, underscores and periods to avoid platform dependency issues and URL issues
    • Do not use subdirectories (rename and delete would fail)
  • Use Plugin API functions documented in TWikiFuncModule to ensure portability:
    • Use getPubDir() to get the attachment root directory
    • Use getUrlHost() and getPubUrlPath() to build the URL in case you create content for the browser

Example code to build the file name: 

sub _make_filename
{
    my ( $web, $topic, $name ) = @_;

    # Create web directory "pub/$web" if needed
    my $dir = TWiki::Func::getPubDir() . "/$web";
    unless( -e "$dir" ) {
        umask( 002 );
        mkdir( $dir, 0775 );
    }
    # Create topic directory "pub/$web/$topic" if needed
    $dir .= "/$topic";
    unless( -e "$dir" ) {
        umask( 002 );
        mkdir( $dir, 0775 );
    }
    return "$dir/_FooBarPlugin_$name";
}

-- TWiki:Main/PeterThoeny - 14 Aug 2004
-- TWiki:Main/AndreaSterbini - 29 May 2001
-- TWiki:Main/MikeMannix - 03 Dec 2001

Note: Included topic WebNotification? does not exist yet

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

-- TWiki:Main.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 an upper case letters, followed by optional upper or lower case letters or numbers
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.
 

Notes:

  • Attachments will NOT get copied over along with their topics
  • The manage script while creating the new web will update the following variables in the WebPreferences: WEBBGCOLOR, SITEMAPLIST, SITEMAPWHAT, SITEMAPUSETO and NOSEARCHALL. These variables are used to dynamically generate the SiteMap
  • This script does not edit the TWiki.TWikiPreferences file to update the WIKIWEBLIST. This must be done by hand
  • As of TWiki Release 01 Sep 2004, a web name can be a WikiWord. Prior to that it could be only UPPER or UPPERlower. A side effect of this is that if you do use a wiki name, %WEB% must be written as <nop>%WEB% or else it will try to link to a non-existing topic of that name

Renaming or Deleting a Web

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

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

Renaming the MAINWEB

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

-- TWiki:Main.MikeMannix - 14 Sep 2001
-- TWiki:Main.PeterThoeny - 07 Apr 2002
-- TWiki:Main.GrantBow - 16 Jan 2003
to top

End of topic
Skip to action links | Back to top

Edit | Attach image or document | Printable version | Raw text | More topic actions
Revisions: | r1.46 | > | r1.45 | > | r1.44 | Total page history | Backlinks
You are here: TWiki > TWikiDocumentation

to top

Copyright © 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Project hosting provided by:
SourceForge.net Logo		Donations welcome:
Support This Project