TWiki Reference Manual (Wed, 08 Feb 2006 build 8740)

TWiki Reference Manual (Wed, 08 Feb 2006 build 8740)

TWiki Installation Guide

Installation instructions for the TWiki 4.0 production release.

TWiki should be fine with any web server and OS that meet the system requirements. The following installation instructions are written for experienced system administrators; please review the AdminSkillsAssumptions before you install TWiki. If you need help, ask a question in the TWiki:Support web or on TWiki:Codev.TWikiIRC (irc.freenode.net, channel #twiki)

Hint: TWiki:TWiki.InstallingTWiki on TWiki.org has supplemental documentation that help you install TWiki on different platforms, environments and web hosting sites.

Basic Installation

1. Download the TWiki distribution from http://TWiki.org/download.html.
2. Make a directory for the installation and unpack the distribution in it.
3. Make sure the user that runs CGI scripts on your system can read and write all files in the distribution.
   Detailed instructions on file permissions are beyond the scope of this guide, but in general:
   • During installation and configuration, the CGI user needs to be able to read and write everything in the distribution,
   • Once installation and configuration is complete, the CGI user needs write access to everything under the data and pub directories and to lib/LocalSite.cfg. Everything else should be read-only.
   • Everybody else should be denied access to everything, always.
4. 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 somewhere else, change the path to Perl in the first line of each script in the twiki/bin directory.
   Some systems require a special extension on perl scripts (e.g. .cgi or .pl). If necessary, rename all files in twiki/bin (i.e. rename view to view.pl etc). If you do this, make sure you set the ScriptSuffix option in configure (Step 6).
5. Create the file /twiki/bin/LocalLib.cfg.
   There is a template for this file in /twiki/bin/LocalLib.cfg.txt.
   The file must contain a setting for $twikiLibPath, which must point to the absolute file path of your twiki/lib e.g. /home/httpd/twiki/lib.
   If you need to install additional CPAN modules, but can't update the main Perl installation files on the server, you can set $CPANBASE to point to your personal CPAN install. Don't forget that the webserver user has to be able to read those files as well.
6. Configure the webserver so you can execute the bin/configure script from your browser.
   • Explicit instructions for doing this are beyond the scope of this document, though there is a lot of advice on TWiki.org covering different configurations of webserver. To help you out, there's an example Apache httpd.conf file in twiki_httpd_conf.txt at the root of the package. This file also contains advice on securing your installation. There's also a script called tools/rewriteshebang.pl to help you in fixing up the shebang lines in your CGI scripts.
7. Run the configure script from your browser, and resolve any errors or warnings it tells you about.

Next Steps

• Review TWikiPreferences settings - read through it and set any additional settings you think you might need (you can click the 'Edit' button near the top to edit the settings in place)
  • It is recommended to copy any settings or variables that you want to customize from TWiki.TWikiPreferences and paste them into Main.TWikiPreferences. This will protect your local customizations from being overwritten in later upgrades. See notes at top of TWiki.TWikiPreferences for more information.
• Customize user home pages - read and change NewUserTemplate.
• Enable authentication - read TWikiUserAuthentication.
• Clear admin notes - some pages are meant to be customized after choice of authentication - check and update these topics (remove notice):
  • ChangePassword
  • ResetPassword
  • ChangeEmailAddress
  • TWikiRegistration fields can be customzied to the needs of your organization
  • TWikiAdminGroup
• Enable e-mail notification - read TWikiSiteTools#WebNotify to get WebChangesAlerts.
• Automate update of site statistics - read TWikiSiteTools#WebStatistics
• Automate removal of expired sessions and lease files - read TWikiScripts#tick_twiki_pl.
• Install Plugins if needed - TWiki:Plugins is an extensive library of Plugins for TWiki, that enhance functionality in a huge number of ways. A few Plugins are pre-installed in the TWiki distribution. Installation instructions are included in Plugins you download from TWiki:Plugins.PluginPackage on TWiki.org.
• Review known issues - visit TWiki:Codev.KnownIssuesOfTWiki04x00x00 and fix issues that apply to you.

Troubleshooting

• The first step is to re-run the configure script and make sure you have resolved all errors, and are happy that you understand any warnings.
• TWiki:TWiki.InstallingTWiki on TWiki.org has supplemental documentation that help you install TWiki on different platforms, environments and web hosting sites.
• If you need help, ask a question in the TWiki:Support web or on TWiki:Codev.TWikiIRC (irc.freenode.net, channel #twiki)

TWiki Upgrade Guide

Upgrade from the previous TWiki 01-Sep-2004 Prodcution Release to TWiki-4.0.0

Overview

TWiki-4.0.0 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
• Review TWiki:TWiki.TWikiUpgradeTo04x00x00 for latest information and experience notes.
• To upgrade from a release prior to TWiki Release 01-Sep-2004, start with TWiki:TWiki.UpgradingTWiki on TWiki.org
• To upgrade from a standard TWiki Release 01-Sep-2004 to the latest TWiki-4.0.0 Production Release, follow the instructions below
• Once the upgrade has been applied, an existing earlier installation will still be able to read all the topics, but should not be used to write. Make sure you take a backup!
• Not all Plugins written for TWiki Release 01-Sep-2004 are fully supported with Dakar. Make sure the Plugins you use can be upgraded as well!

Major Changes Compared to TWiki Release 01-Sep-2004

See TWikiReleaseNotes04x00x00.

Automated Upgrade Procedure

If you would prefer to do things manually, or if you made custom modifications to distributed files (except topics), then skip to the manual upgrade procedure below.

The upgrade script is called "UpgradeTwiki", and is found in the root of the distribution. It can be run by any user, though you will need to make sure you correct the permissions so that the webserver user can write all files in the new installation when you have finished. The upgrade script does not write to your existing installation.

The upgrade script will upgrade the TWiki core only. Plugins will need to be upgraded separately.

Note: To upgrade from a Beta, do not use UpgradeTWiki. Instead follow the steps outlined in Upgrading a Beta, below.

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 and attachments 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 existing_twiki's setlib.cfg> <full path to new_twiki>
• confirm your system settings by pointing your browser to cgi-bin/configure

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

Visit TWiki:Codev.KnownIssuesOfTWiki04x00x00 and fix known issues that apply to you.

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

The following steps are a rough guide to upgrading only. It is impossible to give detailed instructions, as what you have to do may depend on whether you can configure the webserver or not, and how much you have changed distributed files in your current TWiki release.

1. Follow the installation instructions, and install the new release in a new directory.
2. Copy your local webs over to the data and pub directories of the new install
   • You could also use softlinks to link the web directories in data and pub to the old installation area
3. Unlock the rcs files in data and pub directories from the old installation using the following shell commands:
   • find data -name '*,v' -exec rcs -r -u -M '{}' \;
   • find pub -name '*,v' -exec rcs -r -u -M '{}' \;
4. Examine your old TWiki.cfg, and for each local setting, set the corresponding value in the configure interface for the new install.
   • If you can't use configure, then copy the new TWiki.cfg to LocalSite.cfg, and edit LocalSite.cfg. Remove all the settings that you didn't change in your previous install, and change the remaining settings to the values from your old TWiki.cfg.
5. Transfer any customized and local settings from TWiki.TWikiPreferences to the topic pointed at by {LocalSitePreferences} (Main.TWikiPreferences). This avoids having to write over files in the distribution.
6. If you changed any of the topics in the original TWiki distribution, you will have to transfer your changes to the new install manually. There is no simple way to do this, though the following procedure may help:
   1. Install a copy of the original TWiki release you were using in a temporary directory
   2. Use 'diff' to find changed files, and transfer the changes into the new Dakar install.
   3. Install updated plugins into your new area.
7. Point your webserver at the new install.
8. Visit TWiki:Codev.KnownIssuesOfTWiki04x00x00 and fix known issues that apply to you.

You are highly recommended not to change any distributed files if you can avoid it, to simplify future upgrades!

Upgrading a Beta

1. Follow the installation instructions, and install the new release in a new directory.
2. Copy your local webs over to the data and pub directories of the new install
3. Copy over your bin/setlib.cfg and lib/LocalLib.cfg files
4. Point your webserver at the new install.

Warning: Can't find topic TWikiImplementationNotes

TWiki Installation Guide

Installation instructions for the TWiki 4.0 production release.

TWiki should be fine with any web server and OS that meet the system requirements. The following installation instructions are written for experienced system administrators; please review the AdminSkillsAssumptions before you install TWiki. If you need help, ask a question in the TWiki:Support web or on TWiki:Codev.TWikiIRC (irc.freenode.net, channel #twiki)

Hint: TWiki:TWiki.InstallingTWiki on TWiki.org has supplemental documentation that help you install TWiki on different platforms, environments and web hosting sites.

Basic Installation

1. Download the TWiki distribution from http://TWiki.org/download.html.
2. Make a directory for the installation and unpack the distribution in it.
3. Make sure the user that runs CGI scripts on your system can read and write all files in the distribution.
   Detailed instructions on file permissions are beyond the scope of this guide, but in general:
   • During installation and configuration, the CGI user needs to be able to read and write everything in the distribution,
   • Once installation and configuration is complete, the CGI user needs write access to everything under the data and pub directories and to lib/LocalSite.cfg. Everything else should be read-only.
   • Everybody else should be denied access to everything, always.
4. 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 somewhere else, change the path to Perl in the first line of each script in the twiki/bin directory.
   Some systems require a special extension on perl scripts (e.g. .cgi or .pl). If necessary, rename all files in twiki/bin (i.e. rename view to view.pl etc). If you do this, make sure you set the ScriptSuffix option in configure (Step 6).
5. Create the file /twiki/bin/LocalLib.cfg.
   There is a template for this file in /twiki/bin/LocalLib.cfg.txt.
   The file must contain a setting for $twikiLibPath, which must point to the absolute file path of your twiki/lib e.g. /home/httpd/twiki/lib.
   If you need to install additional CPAN modules, but can't update the main Perl installation files on the server, you can set $CPANBASE to point to your personal CPAN install. Don't forget that the webserver user has to be able to read those files as well.
6. Configure the webserver so you can execute the bin/configure script from your browser.
   • Explicit instructions for doing this are beyond the scope of this document, though there is a lot of advice on TWiki.org covering different configurations of webserver. To help you out, there's an example Apache httpd.conf file in twiki_httpd_conf.txt at the root of the package. This file also contains advice on securing your installation. There's also a script called tools/rewriteshebang.pl to help you in fixing up the shebang lines in your CGI scripts.
7. Run the configure script from your browser, and resolve any errors or warnings it tells you about.

Next Steps

• Review TWikiPreferences settings - read through it and set any additional settings you think you might need (you can click the 'Edit' button near the top to edit the settings in place)
  • It is recommended to copy any settings or variables that you want to customize from TWiki.TWikiPreferences and paste them into Main.TWikiPreferences. This will protect your local customizations from being overwritten in later upgrades. See notes at top of TWiki.TWikiPreferences for more information.
• Customize user home pages - read and change NewUserTemplate.
• Enable authentication - read TWikiUserAuthentication.
• Clear admin notes - some pages are meant to be customized after choice of authentication - check and update these topics (remove notice):
  • ChangePassword
  • ResetPassword
  • ChangeEmailAddress
  • TWikiRegistration fields can be customzied to the needs of your organization
  • TWikiAdminGroup
• Enable e-mail notification - read TWikiSiteTools#WebNotify to get WebChangesAlerts.
• Automate update of site statistics - read TWikiSiteTools#WebStatistics
• Automate removal of expired sessions and lease files - read TWikiScripts#tick_twiki_pl.
• Install Plugins if needed - TWiki:Plugins is an extensive library of Plugins for TWiki, that enhance functionality in a huge number of ways. A few Plugins are pre-installed in the TWiki distribution. Installation instructions are included in Plugins you download from TWiki:Plugins.PluginPackage on TWiki.org.
• Review known issues - visit TWiki:Codev.KnownIssuesOfTWiki04x00x00 and fix issues that apply to you.

Troubleshooting

• The first step is to re-run the configure script and make sure you have resolved all errors, and are happy that you understand any warnings.
• TWiki:TWiki.InstallingTWiki on TWiki.org has supplemental documentation that help you install TWiki on different platforms, environments and web hosting sites.
• If you need help, ask a question in the TWiki:Support web or on TWiki:Codev.TWikiIRC (irc.freenode.net, channel #twiki)

TWiki Upgrade Guide

Upgrade from the previous TWiki 01-Sep-2004 Prodcution Release to TWiki-4.0.0

Overview

TWiki-4.0.0 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
• Review TWiki:TWiki.TWikiUpgradeTo04x00x00 for latest information and experience notes.
• To upgrade from a release prior to TWiki Release 01-Sep-2004, start with TWiki:TWiki.UpgradingTWiki on TWiki.org
• To upgrade from a standard TWiki Release 01-Sep-2004 to the latest TWiki-4.0.0 Production Release, follow the instructions below
• Once the upgrade has been applied, an existing earlier installation will still be able to read all the topics, but should not be used to write. Make sure you take a backup!
• Not all Plugins written for TWiki Release 01-Sep-2004 are fully supported with Dakar. Make sure the Plugins you use can be upgraded as well!

Major Changes Compared to TWiki Release 01-Sep-2004

See TWikiReleaseNotes04x00x00.

Automated Upgrade Procedure

If you would prefer to do things manually, or if you made custom modifications to distributed files (except topics), then skip to the manual upgrade procedure below.

The upgrade script is called "UpgradeTwiki", and is found in the root of the distribution. It can be run by any user, though you will need to make sure you correct the permissions so that the webserver user can write all files in the new installation when you have finished. The upgrade script does not write to your existing installation.

The upgrade script will upgrade the TWiki core only. Plugins will need to be upgraded separately.

Note: To upgrade from a Beta, do not use UpgradeTWiki. Instead follow the steps outlined in Upgrading a Beta, below.

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 and attachments 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 existing_twiki's setlib.cfg> <full path to new_twiki>
• confirm your system settings by pointing your browser to cgi-bin/configure

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

Visit TWiki:Codev.KnownIssuesOfTWiki04x00x00 and fix known issues that apply to you.

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

The following steps are a rough guide to upgrading only. It is impossible to give detailed instructions, as what you have to do may depend on whether you can configure the webserver or not, and how much you have changed distributed files in your current TWiki release.

1. Follow the installation instructions, and install the new release in a new directory.
2. Copy your local webs over to the data and pub directories of the new install
   • You could also use softlinks to link the web directories in data and pub to the old installation area
3. Unlock the rcs files in data and pub directories from the old installation using the following shell commands:
   • find data -name '*,v' -exec rcs -r -u -M '{}' \;
   • find pub -name '*,v' -exec rcs -r -u -M '{}' \;
4. Examine your old TWiki.cfg, and for each local setting, set the corresponding value in the configure interface for the new install.
   • If you can't use configure, then copy the new TWiki.cfg to LocalSite.cfg, and edit LocalSite.cfg. Remove all the settings that you didn't change in your previous install, and change the remaining settings to the values from your old TWiki.cfg.
5. Transfer any customized and local settings from TWiki.TWikiPreferences to the topic pointed at by {LocalSitePreferences} (Main.TWikiPreferences). This avoids having to write over files in the distribution.
6. If you changed any of the topics in the original TWiki distribution, you will have to transfer your changes to the new install manually. There is no simple way to do this, though the following procedure may help:
   1. Install a copy of the original TWiki release you were using in a temporary directory
   2. Use 'diff' to find changed files, and transfer the changes into the new Dakar install.
   3. Install updated plugins into your new area.
7. Point your webserver at the new install.
8. Visit TWiki:Codev.KnownIssuesOfTWiki04x00x00 and fix known issues that apply to you.

You are highly recommended not to change any distributed files if you can avoid it, to simplify future upgrades!

Upgrading a Beta

1. Follow the installation instructions, and install the new release in a new directory.
2. Copy your local webs over to the data and pub directories of the new install
3. Copy over your bin/setlib.cfg and lib/LocalLib.cfg files
4. Point your webserver at the new install.

TWiki User Authentication

TWiki site access control and user activity tracking options

Overview

Authentication, or "login", is the process by which a user lets TWiki know who they are.

Authentication isn't just to do with access control. TWiki uses authentication to identify users, so it can keep track of who made changes, and manage a wide range of personal settings. With authentication enabled, users can personalise TWiki and contribute as recognised individuals, instead of shadows.

TWiki authentication is very flexible, and can either stand alone or integrate with existing authentication schemes. You can set up TWiki to require authentication for every access, or only for changes. Authentication is also essential for access control.

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

• You are TWikiGuest

TWiki user authentication is split into three sections; password management, user registration, and login management. Password management deals with how users are recognised (authenticated). Registration deals with how new users are added to the wiki. Login management deals with how users log in.

Once a user is logged on, they are remembered using a "session id" stored in a cookie in the browser (or by other less elegant means if the user has disabled cookies). This avoids them having to log on again and again.

Please note FileAttachments are not protected by TWiki User Authentication.

Tip: TWiki:TWiki.TWikiUserAuthenticationSupplement on TWiki.org has supplemental documentation on user authentication.

Password Management

As shipped, TWiki supports the Apache 'htpasswd' password manager. This manager supports the use of .htpasswd files on the server. These files can be unique to TWiki, or can be shared with other applications (such as an Apache webserver). A variety of password encodings are supported for flexibility when re-using existing files. See the descriptive comments in the Security Settings section of the configure interface for more details.

New User Registration

New user registration uses the password manager to set and change passwords. It is also responsible for the new user verification process. the registration process supports single user registration via the TWikiRegistration page, and bulk user registration via the BulkRegistration page (for admins only).

The registration process is responsible for creating user topics.

Login Management

Login management controls the way users have to log in. There are three basic options; no login, login via a TWiki login page, and login using the webserver authentication support.

You can select your chosen login through the Security Settings pane in the configure interface.

No Login

Does exactly what it says on the tin. Forget about authentication to make your site completely public - anyone can browse and edit freely, in classic Wiki style. All visitors are given the TWikiGuest default identity, so you can't track individual user activity.

Note: This setup is not recommended on public websites for security reasons; anyone would be able to change system settings and perform tasks usually restricted to the TWikiAdminGroup.

Template Login

Template Login asks for a username and password in a web page, and processes them using whatever Password Manager you choose. Users can log in and log out.

Enabling Template Login

1. Use the configure interface to
   1. enable the TemplateLogin login manager (on the Security Settings pane).
   2. select the appropriate password manager for your system, or provide your own.
2. Register yourself in the TWikiRegistration topic.
   Check that the password manager recongises the new user. If you are using .htpasswd files, check that a new line with the username and encrypted password is added to the .htpasswd file. If not, you probably got a path wrong, or the permissions may not allow the webserver user to write to that file.
3. Create a new topic to check if authentication works.
4. Edit the TWikiAdminGroup topic in the Users web to include users with system administrator status.
   This is a very important step, as users in this group can access all topics, independent of TWiki access controls.

TWikiAccessControl has more information on setting up access controls.

At this time TWikiAccessControls cannot control access to files in the pub area, unless they are only accessed through the viewfile script. If your pub directory is set up in the webserver to allow open access you may want to add .htaccess files in there to restrict access.

You can create a custom version of the TWikiRegistration 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

Apache Login

Using this method TWiki does not authenticate users internally. Instead it depends on the REMOTE_USER environment variable, which is set when you enable authentication in the webserver.

The advantage of this scheme is that if you have an existing website authentication scheme using Apache modules such as mod_auth_ldap or mod_auth_mysql you can just plug in directly to them.

The disadvantage is that because the user identity is cached in the browser, you can log in, but you can't log out again unless you restart the browser.

TWiki maps the REMOTE_USER that was used to log in to the webserver to a WikiName using the table in TWikiUsers. This table is updated whenever a user registers, so users can choose not to register (in which case their webserver login name is used for their signature) or register (in which case that login name is mapped to their WikiName).

The same private .htpasswd file used in TWiki Template Login can be used to authenticate Apache users, using the Apache Basic Authentication support. This allows the TWiki registration support to maintain usernames and passwords.

Enabling Apache Login using mod_auth

1. Use configure to select the ApacheLogin login manager.
2. Use configure to set up TWiki to create the right kind of .htpasswd entries.
3. Create a .htaccess file in the twiki/bin directory.
   There is an template for this file in twiki/bin/.htaccess.txt that you can copy and change. The comments in the file explain what need to be done.
   If you got it right, the browser should now ask for login name and password when you click on the Edit. If .htaccess does not have the desired effect, you may need to "AllowOverride All" for the directory in httpd.conf (if you have root access; otherwise, e-mail web server support)
   At this time TWikiAccessControls do not control access to files in the pub area, unless they are only accessed through the viewfile script. If your pub directory is set up to allow open access you may want to add .htaccess files in there as well to restrict access
4. You can create a custom version of TWikiRegistration 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
5. Register yourself in the TWikiRegistration topic.
   Check that a new line with the username and encrypted password is added to the .htpasswd file. If not, you may have got a path wrong, or the permissions may not allow the webserver user to write to that file.
6. Create a new topic to check if authentication works.
7. Edit the TWikiAdminGroup topic in the Users web to include users with system administrator status.
   This is a very important step, as users in this group can access all topics, independent of TWiki access controls.

Logons via bin/logon

Any time a user enters a page that needs authentication, they will be forced to log on. It may be convenient to have a "logon" as well, to give the system a chance to identify the user and retrieve their personal settings. It may be convenient to force them to log on.

The bin/logon script accomplishes this. The bin/logon script must be setup in the bin/.htaccess file to be a script which requires a valid user. However, once authenticated, it will simply redirect the user to the view URL for the page from which the logon script was linked.

Sessions

TWiki uses the CPAN:CGI::Session and CPAN:CGI::Cookie modules to track sessions using cookies. These modules are de facto standards for session management among Perl programmers. If you can't use Cookies for any reason, CPAN:CGI::Session also supports session tracking using the client IP address. See How to choose an authentication method for a discussion of the pros and cons of the various authentication methods.

There are a number of TWikiVariables available that you can use to interrogate your current session. You can even add your own session variables to the TWiki cookie. Session variables are referred to as "sticky" variables.

Getting, Setting, and Clearing Session Variables

You can get, set, and clear session variables from within TWiki web pages or by using script parameters. This allows you to use the session as a personal "persistent memory space" that is not lost until the web browser is closed. Also note that if a session variable has the same name as a TWiki preference, the session variables value takes precedence over the TWiki preference. This allows for per-session preferences.

To make use of these features, use the tags:

%SESSION_VARIABLE{ "varName" }%
%SESSION_VARIABLE{ "varName" set="varValue" }%
%SESSION_VARIABLE{ "varName" clear="" }%

Cookies and Transparent Session IDs

TWiki normally uses cookies to store session information on a client computer. Cookies are a common way to pass session information from client to server. TWiki cookies simply hold a unique session identifier that is used to look up a database of session information on the TWiki server.

For a number of reasons, it may not be possible to use cookies. In this case, TWiki has a fallback mechanism; it will automatically rewrite every internal URL it sees on pages being generated to one that also passes session information.

TWiki Username vs. Login Username

This section applies only if you are using authentication with existing login names (i.e. mapping from login names to WikiNames).

QBFreak.net 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 Users web.

TWiki can automatically map an Intranet (Login) Username to a TWiki Username if the {AllowLoginName} is enabled in configure. The default is to use your WikiName as a login name.

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

Changing Passwords

If your {PasswordManager} supports password changing, you can change and reset passwords using forms on regular pages.

• The ChangePassword form ( TWiki/ChangePassword )
• The ResetPassword form ( TWiki/ResetPassword )

Changing E-mail Addresses

If the active {PasswordManager} supports storage and retrieval of user e-mail addresses, you can change your e-mail using a regular page. As shipped, this is true only for the Apache 'htpasswd' password manager.

• The ChangeEmailAddress form ( TWiki/ChangeEmailAddress )

Controlling access to individual scripts

• For Template Login, update the {AuthScripts} list using configure
• For Apache Login, add/remove the script from .htaccess

How to choose an authentication method

One of the key features of TWiki is that it is possible to add HTML to topics. No authentication method is 100% secure on a website where end users can add HTML, as there is always a risk that a malicious user can add code to a topic that gathers user information, such as session IDs. The TWiki developers have been forced to make certain tradeoffs, in the pursuit of efficiency, that may be exploited by a hacker.

This section discusses some of the known risks. You can be sure that any potential hackers have read this section as well!

Firstly, the most secure method is without doubt to use the webserver authentication support, with Sessions turned off.

The second most secure method is to use TWiki's internal authentication with Sessions turned off. This method is less secure than using the webserver because passwords are sent in plain text and can therefore be intercepted in transit.

As soon as you allow the server to maintain information about a logged-in user, you open a door to potential attacks. There are a variety of ways a malicious user can pervert TWiki to obtain another users session ID, the most common of which is known as a cross-site scripting attack. Once a hacker has an SID they can pretend to be that user.

To help prevent these sorts of attacks, TWiki supports IP matching, which ensures that the IP address of the user requesting a specific session is the same as the IP address of the user who created the session. This works well as long as IP addresses are unique to each client, and as long as the IP address of the client can't be faked.

The third most secure method is to use sessions with IP matching ({UseIPMatching} switched on). Shorter session expiry times are more secure ({Sessions}{ExpireAfter}). The default session lifetime is 6 hours, which is quite a long lifetime for a session.

Session IDs are usually stored by TWiki in cookies, which are stored in the client browser. Cookies work well, but not all environments or users permit cookies to be stored in browsers. So TWiki also supports two other methods of determining the session ID. The first method uses the client IP address to determine the session ID. The second uses a rewriting method that rewrites local URLs in TWiki pages to include the session ID in the URL.

The first method works well as long as IP addresses are unique to each individual client, and client IP addresses can't be faked by a hacker. If IP addresses are unique and can't be faked, it is almost as secure as cookies + IP matching, so it ranks as the fourth most secure method.

If you have to turn IP matching off, and cookies can't be relied on, then you may have to rely on the second method, URL rewriting. This method exposes the session IDs very publicly, so should be regarded as the least secure method.

See TWiki:TWiki.SecuringTWikiSite for more information.

TWiki Access Control

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

TWiki Access Control allows you restrict access to single topics and entire webs, by individual user and by user Groups. Access control, combined with TWikiUserAuthentication, lets you easily create and manage an extremely flexible, fine-grained privilege system.

Tip: TWiki:TWiki.TWikiAccessControlSupplement on TWiki.org has additional documentation on access control.

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

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

Permissions settings of the webs on this TWiki site

See TWikiAccessControl for details

Please Note:

• A blank in the the above table may mean either the corresponding control is absent or commented out or that it has been set to a null value. The two conditions have dramatically different and possibly opposed semantics.
• TWikiGuest is the guest account - used by unauthenticated users.
• The TWiki web must not deny view to TWikiGuest; otherwise, people will not be able to register.

Note: Above table comes from SitePermissions

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 using the password manager 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 Users web.
• The user is added to the TWikiUsers topic.

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

Managing Groups

Groups are defined by group topics located in the Users web, such as the TWikiAdminGroup. To create a new group, visit TWikiGroups and enter the name of the new group ending in Group into the "new group" form field. This will create a new group topic with two important settings:

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

The GROUP setting is a comma-separated list of users and/or other groups. Example:

• Set GROUP = Users.SomeUser, Users.OtherUser, Users.SomeGroup

The ALLOWTOPICCHANGE setting 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 = Users.TWikiAdminGroup

Note: TWiki has strict formatting rules. Make sure you have three spaces, an asterisk, and an extra space in front of any access control rule.

The Super Admin Group

By mistyping a user or group name in the settings, it's possible to lock a topic so that no-one can edit it from a browser. To avoid this, add the WikiNames of registered administrators to the super admin group topic called TWikiAdminGroup. The name of this topic is defined by the {SuperAdminGroup} configure setting. Example group setting:

• Set GROUP= Users.ElizabethWindsor, Users.TonyBlair

Restricting Access

You can define who is allowed to read or write to a web or a topic. Note that some plugins may not respect access permissions.

• Restricting VIEW blocks viewing and searching of content.
• Restricting CHANGE blocks creating new topics, changing topics or attaching files.
• Restricting RENAME controls who is allowed to rename, move or delete a topic.
  • To rename, move or delete a topic, the user also also needs VIEW and CHANGE permission. They also need CHANGE access to change references in any referring topics (though the rename can proceed without this access), and CHANGE access to the target topic.
• Restricting MANAGE controls access to certain management functions, such as 'create web'. It must be set in the TWiki web.

Controlling access to a Web

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

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

• You can define these settings in the WebPreferences topic, preferable towards the end of the topic:
  • Set DENYWEBVIEW = < comma-delimited list of Users and Groups >
  • Set ALLOWWEBVIEW = < comma-delimited list of Users and Groups >
  • Set DENYWEBCHANGE = < comma-delimited list of Users and Groups >
  • Set ALLOWWEBCHANGE = < comma-delimited list of Users and Groups >
  • Set DENYWEBRENAME = < comma-delimited list of Users and Groups >
  • Set ALLOWWEBRENAME = < comma-delimited list of Users and Groups >

Be careful with empty values for any of these. In older versions of TWiki,

• Set ALLOWWEBVIEW =

• Set DENYWEBVIEW =

Controlling access to a Topic

• You can define these settings in the WebPreferences topic, preferable towards the end of the topic:
  • Set DENYTOPICVIEW = < comma-delimited list of Users and Groups >
  • Set ALLOWTOPICVIEW = < comma-delimited list of Users and Groups >
  • Set DENYTOPICCHANGE = < comma-delimited list of Users and Groups >
  • Set ALLOWTOPICCHANGE = < comma-delimited list of Users and Groups >
  • Set DENYTOPICRENAME = < comma-delimited list of Users and Groups >
  • Set ALLOWTOPICRENAME = < comma-delimited list of Users and Groups >

Remember when opening up access to specific topics within a restricted web that other topics in the web - for example, the WebLeftBar - may also be accessed when viewing the topics. The message you get when you are denied access should tell you what topic you were not permitted to access.

Be careful with empty values for any of these. In older versions of TWiki,

• Set ALLOWTOPICVIEW =

• Set DENYTOPICVIEW =

Controlling access to Attachments

Attachments are referred to directly, and are not normally indirected via TWiki scripts. This means that the above instructions for access control will not apply to attachments. It is possible that someone may inadvertently publicise a URL that they expected to be access-controlled.

The easiest way to apply the same access control rules for attachments as apply to topics is to use the Apache mod_rewrite module, and configure your webserver to redirect accesses to attachments to the TWiki viewfile script. For example,

  ScriptAlias /twiki/bin/ /filesystem/path/to/twiki/bin/
  Alias /twiki/pub/       /filesystem/path/to/twiki/pub/

  RewriteEngine on
  RewriteRule ^/twiki/pub/TWiki/(.*)$ /twiki/pub/TWiki/$1 [L,PT]
  RewriteRule ^/twiki/pub/([^\/]+)/([^\/]+)/([^\/]+)$ /twiki/bin/viewfile/$1/$2?filename=$3 [L,PT]

That way all the controls that apply to the topic also apply to attachments to the topic. Other types of webserver have similar support.

Note: Images embedded in topics will load much slower since each image will be delivered by the viewfile script.

How TWiki evaluates ALLOW/DENY settings

When deciding whether to grant access, TWiki evaluates the following rules in order (read from the top of the list; if the logic arrives at PERMITTED or DENIED that applies immediately and no more rules are applied). You need to read the rules bearing in mind that VIEW, CHANGE and RENAME access may be granted/denied separately.

1. If the user is a super-user
   • access is PERMITTED.
2. If DENYTOPIC is set to a list of wikinames
   • people in the list will be DENIED.
3. If DENYTOPIC is set to empty ( i.e. Set DENYTOPIC = )
   • access is PERMITTED i.e no-one is denied access to this topic
4. If ALLOWTOPIC is set
   1. people in the list are PERMITTED
   2. everyone else is DENIED
      • Note that this means that setting ALLOWTOPIC to empty denies access to everyone except admins (unless DENYTOPIC is also set to empty, as described above)
5. If DENYWEB is set to a list of wikiname
   • people in the list are DENIED access
6. If ALLOWWEB is set to a list of wikinames
   • people in the list will be PERMITTED
   • everyone else will be DENIED
     • Note that setting ALLOWWEB to empty denies access to everyone except admins
7. If you got this far, access is PERMITTED

Access Control quick recipes

Obfuscating Webs

Another way of hiding webs is to keep them hidden by not publishing the 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, or to hide view access restricted webs.

Note: Obfuscating a web without view access control is very 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. Requires TWikiUserAuthentication to be enabled.

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

Authenticate and Restrict Selected Webs Only

Use the following setup to provide unrestricted viewing access to open webs, with authentication only on selected webs. Requires TWikiUserAuthentication to be enabled.

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

Hide Control Settings

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

<!--
   * Set DENYTOPICCHANGE = Users.SomeGroup
-->

TWiki Variables

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

TWikiVariables are text strings - %VARIABLE% or %VARIABLE{ parameter="value" }% - that expand into content whenever a topic is rendered for viewing. There are two types of variables:

1. Preferences variables: Can be defined and changed by the user
2. Predefined variables: Defined by the TWiki system or by Plugins (for example, the SpreadSheetPlugin introduces a %CALC{}% variable)

Using Variables

To use a variable type its name. For example,

• type %T% to get (a preferences variable)
• type %TOPIC% to get TWikiVariables (a predefined variable)
• type %CALC{ "$UPPER(Text)" }% to get TEXT (a variable defined by Plugin)

Note:

• 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
• Type %ALLVARIABLES% to get a full listing of all variables defined for a particular topic

Preferences Variables

Unlike predefined variables, preferences variables can be defined by the user in various places.

Setting Preferences Variables

1. local site level in TWikiPreferences
2. user level in individual user topics in Users web
3. web level in WebPreferences of each web
4. topic level in topics in webs
5. plugin topics (see TWikiPlugins)
6. session variables (if sessions are enabled)

Settings at higher-numbered levels override settings of the same variable at lower numbered levels, unless the variable was included in the setting of FINALPREFERENCES at a lower-numbered level, in which case it is locked at the value it has at that level.

The syntax for setting 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] = [space] value

Examples:

• Set VARIABLENAME = value
  • Set VARIABLENAME = value

Example:

   * Set VARIABLENAME = value starts here
     and continues here

Whatever you include in your Variable will be expanded on display, exactly as if it had been entered directly.

Example: Create a custom logo variable

• To place a logo anywhere in a web by typing %MYLOGO%, define the Variable on the web's WebPreferences topic, 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, e.g. LogoTopic. Sample variable setting in WebPreferences:
  • Set MYLOGO = %PUBURL%/%WEB%/LogoTopic/mylogo.gif

You can also set preferences variables on a topic by clicking the link Edit topic preference settings under More topic actions. Preferences set in this manner are not visible in the topic text, but take effect nevertheless.

Access Control Variables

These are special types of preferences variables to control access to content. TWikiAccessControl explains these security settings in detail.

Local values for variables

   * Set EDITBOXHEIGHT = 10
   * Local EDITBOXHEIGHT = 20

Use this powerful feature with great care! %ALLVARIABLES% can be used to get a listing of the values of all variables in their evaluation order, so you can see variable scope if you get confused.

Frequently Used Preferences Variables

The following preferences variables are frequently used. They are defined in TWikiPreferences#Miscellaneous_Settings:

• %BR% - line break
• %BULLET% - bullet sign
• %BB% - line break and bullet combined
• %BB2% - indented line break and bullet
• %RED% text %ENDCOLOR% - colored text (also %YELLOW%, %ORANGE%, %PINK%, %PURPLE%, %TEAL%, %NAVY%, %BLUE%, %AQUA%, %LIME%, %GREEN%, %OLIVE%, %MAROON%, %BROWN%, %BLACK%, %GRAY%, %SILVER%, %WHITE%)
• %H% - Help icon
• %I% - Idea icon
• %M% - Moved to icon
• %N% - New icon
• %P% - Refactor icon
• %Q% - Question icon
• %S% - Pick icon
• %T% - Tip icon
• %U% - Updated icon
• %X% - Alert icon
• %Y% - Done icon

There are additional useful preferences variables defined in TWikiPreferences, in Main.TWikiPreferences, and in WebPreferences of every web.

Predefined Variables

Most predefined variables return values that were either set in the configuration when TWiki was installed, or taken from server info (such as current username, or date and time). Some, like %SEARCH%, are powerful and general tools.

• Predefined variables can be overridden by preferences variables
• Plugins may extend the set of predefined variables (see individual Plugins topics for details)
• 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 - Wed, 08 Feb 2006 build 8740 - predefines the following variables:

ACTIVATEDPLUGINS -- list of currently activated plugins

• Syntax: %ACTIVATEDPLUGINS%
• Expands to: SpreadSheetPlugin, AliasPlugin, BlogPlugin, CommentPlugin, DBCachePlugin, EditTablePlugin, ExtendedSelectPlugin, FilterPlugin, GluePlugin, HeadlinesPlugin, IfDefinedPlugin, InterwikiPlugin, NatSkinPlugin, PreferencesPlugin, RedDotPlugin, RedirectPlugin, SlideShowPlugin, SmiliesPlugin, TWikiBotPlugin, TablePlugin, TagCloudPlugin, TimeSincePlugin, TwistyPlugin, UserInfoPlugin
• Related: PLUGINDESCRIPTIONS, FAILEDPLUGINS, PLUGINVERSION

ALLVARIABLES -- list of currently defined TWikiVariables

• Syntax: %ALLVARIABLES%
• Expands to: a table showing all defined TWikiVariables in the current context

ATTACHURL -- full URL for attachments in the current topic

• Syntax: %ATTACHURL%
• Expands to: http://www.qbfreak.net/twiki/pub/TWiki/TWikiVariablesAtoM
• Example: If you attach a file you can refer to it as %ATTACHURL%/image.gif
• Related: ATTACHURLPATH, PUBURLPATH, SCRIPTURL, FileAttachments

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

• Syntax: %ATTACHURLPATH%
• Expands to: /twiki/pub/TWiki/TWikiVariablesAtoM
• Related: ATTACHURL, PUBURL, FileAttachments

AUTHREALM -- authentication realm

• String defined as {AuthRealm} in configure. This is used in certain password encodings, and in login templates as part of the login prompt.
• Syntax: %AUTHREALM%
• Expands to: Enter your LoginName. (Typically First name and last name, no space, no dots, capitalized, e.g. JohnSmith, unless you chose otherwise). Visit TWikiRegistration if you do not have one.
• Related: TWikiUserAuthentication, SESSIONID, SESSIONVAR, LOGIN, LOGOUT, SESSION_VARIABLE

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

DATE -- signature format date

• Syntax: %DATE%
• Expands to: 22 May 2012
• Note: When used in a template topic, this variable will be expanded when the template is used to create a new topic. See TWikiTemplates#TemplateTopicsVars for details.
• Related: DISPLAYTIME, GMTIME{"format"}, SERVERTIME

DISPLAYTIME -- display time

• Syntax: %DISPLAYTIME%
• Expands to: 22 May 2012 - 04:40
• Related: DISPLAYTIME{"format"}, GMTIME, SERVERTIME

DISPLAYTIME{"format"} -- formatted display time

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

ENCODE{"string"} -- encodes a string to HTML entities

• Encode "special" characters to HTML numeric entities. Encoded characters are:
  • all non-printable ASCII characters below space, except newline ("\n") and linefeed ("\r")
  • HTML special characters "<", ">", "&", single quote (') and double quote (")
  • TWiki special characters "%", "[", "]", "@", "_", "*", "=" and "|"
• 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 "	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
• Note: Values of HTML input fields must be entity encoded, for example:
  <input type="text" name="address" value="%ENCODE{ "any text" type="entity" }%" />
• Related: URLPARAM

ENDSECTION{"name"} -- marks the end of a named section within a topic

• Syntax: %ENDSECTION{"name"}%
• Syntax: %ENDSECTION{type="include"}%
• Supported parameter:

  Parameter:	Description:
  "name"	Name of the section.
  type="..."	Type of the section being terminated; supported types "section", "include", "templateonly".

• If the STARTSECTION is named, the corresponding ENDSECTION must also be named with the same name. If the STARTSECTION specifies a type, then the corresponding ENDSECTION must also specify the same type. If the section is unnamed, ENDSECTION will match with the nearest unnamed %STARTSECTION% of the same type above it.
• Related: STARTSECTION

FAILEDPLUGINS -- debugging for plugins that failed to load, and handler list

• Syntax: %FAILEDPLUGINS%
• Expands to: See TWikiPlugins#FAILEDPLUGINS
• Related: PLUGINDESCRIPTIONS, ACTIVATEDPLUGINS, PLUGINVERSION

FORMFIELD{"fieldname"} -- 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, and $title expands to the field title	"$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

• Syntax: %GMTIME%
• Expands to: 22 May 2012 - 11:40
• Note: When used in a template topic, this variable will be expanded when the template is used to create a new topic. See TWikiTemplates#TemplateTopicsVars for details.
• Related: DISPLAYTIME, GMTIME{"format"}, SERVERTIME

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
  $dow	day of the week (Sun = 0)	2
  $week	number of week in year (ISO 8601)	34
  $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	2012-05-22T11:40:37Z
  $rcs	RCS format timestamp	2012/05/22 11:40:37
  $http	E-mail & http format timestamp	Tue, 22 May 2012 11:40:37 GMT
  $epoch	Number of seconds since 00:00 on 1st January, 1970	1337686837

• Variables can be shortened to 3 characters
• Example: %GMTIME{"$day $month, $year - $hour:$min:$sec"}% expands to 22 May, 2012 - 11:40:37
• Note: When used in a template topic, this variable will be expanded when the template is used to create a new topic. See TWikiTemplates#TemplateTopicsVars for details.
• Related: DISPLAYTIME, GMTIME, SERVERTIME

HOMETOPIC -- home topic in each web

• Syntax: %HOMETOPIC%
• Expands to: WebHome, renders as WebHome
• Related: NOTIFYTOPIC, STATISTICSTOPIC, TOPIC

HTTP -- get HTTP headers

• Called with the name of an HTTP header field, returns its value. Capitalization and the use of hyphens versus underscores are not significant.
• Syntax: %HTTP%
• Syntax: %HTTP{"Header-name"}%
• Examples:

  %HTTP%
  %HTTP{"Accept-language"}%	en-us,en;q=0.5
  %HTTP{"User-Agent"}%	CCBot/1.0 (+http://www.commoncrawl.org/bot.html)

• Note: You can see the HTTP headers your browser sends to the server on a number of sites e.g. http://www.ericgiguere.com/tools/http-header-viewer.html
• Related: HTTPS, REMOTE_ADDR, REMOTE_PORT, REMOTE_USER

HTTPS -- get HTTPS headers

• The same as %HTTP% but operates on the HTTPS environment variables present when the SSL protocol is in effect. Can be used to determine whether SSL is turned on.
• Syntax: %HTTPS%
• Syntax: %HTTPS{"Header-name"}%
• Related: HTTP, REMOTE_ADDR, REMOTE_PORT, REMOTE_USER

HTTP_HOST -- environment variable

• Syntax: %HTTP_HOST%
• Expands to: www.qbfreak.net
• Related: REMOTE_ADDR, REMOTE_PORT, REMOTE_USER

ICON{"name"} -- small documentation graphic or icon of common attachment types

• Generates the HTML img tag of a small graphic image attached to TWikiDocGraphics. Images typically have a 16x16 pixel size. You can select a specific image by name, or you can give a full filename, in which case the type of the file will be used to select one of a collection of common file type icons.
• Syntax: %ICON{"name"}%
• Examples:
  • %ICON{"flag-gray"}% returns
  • %ICON{"pdf"}% returns
  • %ICON{"smile.pdf"}% returns
  • %ICON{"/dont/you/dare/smile.pdf"}% returns
  • %ICON{"http://twiki.org/doc/xhtml.xsl"}% returns
• Graphic samples: arrowbright, bubble, choice-yes, hand
• File type samples: bmp, doc, gif, hlp, html, mp3, pdf, ppt, txt, xls, xml, zip
• Related: ICONURL, ICONURLPATH, TWikiPreferences, FileAttachments, TWikiDocGraphics

ICONURL{"name"} -- URL of small documentation graphic or icon

• Generates the full URL of a TWikiDocGraphics image, which TWiki renders as an image. The related %ICON{"name"}% generates the full HTML img tag. Specify image name or full filename (see ICON for details on filenames.)
• Syntax: %ICONURL{"name"}%
• Examples:
  • %ICONURL{"arrowbright"}% returns http://www.qbfreak.net/twiki/pub/TWiki/TWikiDocGraphics/arrowbright.gif
  • %ICONURL{"novel.pdf"}% returns http://www.qbfreak.net/twiki/pub/TWiki/TWikiDocGraphics/pdf.gif
  • %ICONURL{"/queen/boheme.mp3"}% returns http://www.qbfreak.net/twiki/pub/TWiki/TWikiDocGraphics/mp3.gif
• Related: ICONURLPATH, ICON, TWikiPreferences, FileAttachments, TWikiDocGraphics

ICONURLPATH{"name"} -- URL path of small documentation graphic or icon

• Generates the URL path of a TWikiDocGraphics image, typically used in an HTML img tag. Specify image name or full filename (see ICON for details on filenames.)
• Syntax: %ICONURLPATH{"name"}%
• Examples:
  • %ICONURLPATH{"locktopic"}% returns /twiki/pub/TWiki/TWikiDocGraphics/locktopic.gif
  • %ICONURLPATH{"eggysmell.xml"}% returns /twiki/pub/TWiki/TWikiDocGraphics/xml.gif
  • %ICONURLPATH{"/doc/xhtml.xsl"}% returns /twiki/pub/TWiki/TWikiDocGraphics/xsl.gif
• Related: ICONURL, ICON, TWikiPreferences, FileAttachments, TWikiDocGraphics

IF{"condition" ...} -- simple conditionals

• Evaluate a condition and show one text or another based on the result. See details in IfStatements
• Syntax: %IF{"CONDITION" then="THEN" else="ELSE"}% shows "THEN" if "CONDITION" evaluates to TRUE, otherwise "ELSE" will be shown
• Example: %IF{"defined FUNFACTOR" then="FUNFACTOR is defined" else=" is not defined"}% renders as ==
• Related: $IF() of SpreadSheetPlugin

INCLUDE{"page"} -- include other topic or web page

• 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:80/index.html"}%. Supported content types are text/html and text/plain. 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="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)	%INCLUDEWARNING% preferences setting
  section="name"	Includes only the specified named section, as defined in the included topic by the STARTSECTION and ENDSECTION variables
  PARONE="val 1" PARTWO="val 2"	Any other parameter will be defined as a variable within the scope of the included topic. The example parameters on the left will result in %PARONE% and %PARTWO% being defined within the included topic.

• Examples: See IncludeTopicsAndWebPages
• Related: BASETOPIC, BASEWEB, INCLUDINGTOPIC, INCLUDINGWEB, STARTINCLUDE, STOPINCLUDE, STARTSECTION, ENDSECTION

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

LANGUAGE -- current user's language

• Returns the language code for the language used as the current user. This is the language actually used by TWiki Internationalization (e.g. in user interface).
• The language is detected from the user's browser, unless some site/web/user/session-defined setting overrides it:
  • If the LANGUAGE preference is set, it's used as user's language instead of any language detected from the browser.
  • Avoid defining LANGUAGE at a non per-user way, so each user can choose his/her preferred language.
• Related: LANGUAGES

LANGUAGES -- list available TWiki languages

• List the languages available (as PO files) to TWiki. Those are the languages in which TWiki's user interface is available.
• Syntax: %LANGUAGES{...}%
• Supported parameters:

  Parameter:	Description:	Default:
  format	format for each item. See below for variables available in the format string.	"   * $langname"
  separator	separator between items.	"\n" (newline)
  marker="selected"	Text for $marker if the item matches selection	"selected"
  selection="%LANGUAGE%"	Current language to be selected in list	(none)

• format variables:

  Variable	Meaning
  $langname	language's name, as informed by the translators
  $langtag	language's tag. Ex: en, pt-br, etc.

• Example: <select>%LANGUAGES{format="<option $marker value='$langtag'>$langname</option>" selection="%LANGUAGE%"}%</select> creates an option list of the available languages with the current language selected

LOCALSITEPREFS -- web.topicname of site preferences topic

• The full name of the local site preferences topic. This topic is read for preferences before TWiki.%TWIKIPREFSTOPIC% is read.
• Syntax: %LOCALSITEPREFS%
• Expands to: Main.TWikiPreferences, renders as TWikiPreferences

LOGIN -- present a full login link

• Syntax: %LOGIN%
• Expand to:
• Related: TWikiUserAuthentication, SESSIONID, SESSIONVAR, LOGOUT, SESSION_VARIABLE

LOGOUT -- present a full logout link

• Syntax: %LOGOUT%
• Expand to:
• Related: TWikiUserAuthentication, SESSIONID, SESSIONVAR, LOGIN, SESSION_VARIABLE

MAKETEXT -- creates text using TWiki's I18N infrastructure

• Syntax: %MAKETEXT{"string" args="..."}
• Supported parameters:

  Parameter	Description	Default
  "text" or string="text"	The text to be displayed.	none
  args="param1, param2"	a comma-separated list of arguments to be interpolated in the string, replacing the [_N] placeholders in it.	none

• Examples:
  • %MAKETEXT{string="Notes:"}%
    expands to
    Notes:
  • %MAKETEXT{"Contact [_1] if you have any questions." args="%WIKIWEBMASTER%"}%
    expands to
    Contact webmaster@qbfreak.net if you have any questions.
  • %MAKETEXT{"Did you want to [[[_1]][reset [_2]'s password]]?" args="%TWIKIWEB%.ResetPassword,%WIKIUSERNAME%"}%
    expands to
    Did you want to reset Users.TWikiGuest's password?
• Notes:
  • TWiki will translate the string to the current user's language only if it has such string in its translation table for that language.
  • Amperstands (&) followed by one letter (one of a...z, A...Z) (say, X) in the translatable string will be translated to <span class='twikiAccessKey'>X</span>. This is used to implement access keys. If you want to write an actual amperstand that stays just before a letter, write two consecutive amperstands (&&): they will be transformed in just one.
  • translatable string starting with underscores (_) are reserved. You cannot use translatable phrases starting with an underscore.
  • Make sure that the translatable string is constant. Specially, do not include %VARIABLES% inside the translatable strings (since they will get expanded before the %MAKETEXT{...}% itself is handled).

MAINWEB -- name of Main web

• The web containing TWikiUsers, individual user topics and TWikiGroups
• Syntax: %MAINWEB%
• Expands to: Users
• Related: TWIKIWEB

META -- displays meta-data

• Provided mainly for use in templates, this variable generates the parts of the topic view that relate to meta-data (attachments, forms etc.) The formfield item is the most likely to be useful to casual users.
• Syntax: %META{ "item" ...}%
• Parameters:

  Item	Options	Description
  "formfield"	name="..." - name of the field. The field value can be shortened as described in FormattedSearch for $formfield	Show a single form field
  "form"	none	Generates the table showing the form fields. See Form Templates
  "attachments"	all="on" to show hidden attachments	Generates the table showing the attachments
  "moved"	none	Details of any topic moves
  "parent"	dontrecurse="on": By default recurses up tree, this has some cost. nowebhome="on": Suppress WebHome. prefix="...": Prefix that goes before parents, but only if there are parents, default "". suffix="...": Suffix, only appears if there are parents, default "". separator="...": Separator between parents, default is " > ".	Generates the parent link

• Related: METASEARCH

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 "field" if searching for topics that have a particular form field value (use the name and value parameters to specify which field to search)	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, for topicmoved and parent searches	current topic
  name	form field to search, for field type searches. May be a regular expression (see SEARCH).
  value	form field value, for field type searches. May be a regular expression (see SEARCH).
  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: "}%
• Example: %METASEARCH{type="field" name="Country" value="China"}%
• Related: SEARCH, META

NOP -- template text not to be expanded in instantiated topics

• Syntax: %NOP%
  • In normal topic text, expands to <nop>, which prevents expansion of adjacent variables and wikiwords
  • When the topic containing this is used as a template for another topic, it is removed.
• Syntax: %NOP{...}% deprecated
  • In normal topic text, expands to whatever is in the curly braces (if anything).
  • Note: This is deprecated. Do not use it. Use %STARTSECTION{type="templateonly"}% .. %ENDSECTION{type="templateonly"}% instead (see TWikiTemplates for more details).
• Related: STARTSECTION, TWikiTemplates

NOTIFYTOPIC -- name of the notify topic

• Syntax: %NOTIFYTOPIC%
• Expands to: WebNotify, renders as WebNotify
• Related: HOMETOPIC, STATISTICSTOPIC, TOPIC

PLUGINDESCRIPTIONS -- list of plugin descriptions

• Syntax: %PLUGINDESCRIPTIONS%
• Expands to:
  • SpreadSheetPlugin (Dakar, 8154): Add spreadsheet calculation like "$SUM( $ABOVE() )" to tables located in QBFreak.net topics.
  • AliasPlugin (1.32, 9301): Define aliases which will be replaced with arbitrary strings automatically
  • BlogPlugin (0.80, $Rev: 9253$): Basic blogging features used to implement the BlogUp TWikiApplication
  • CommentPlugin (Dakar, 8164): Allows users to quickly post comments to a page without an edit/preview/save cycle.
  • DBCachePlugin (1.01, $Rev: 9393$): Lightweighted frontend to the DBCacheContrib
  • EditTablePlugin (Dakar, 8154): Edit TWiki tables using edit fields, date pickers and drop down boxes
  • ExtendedSelectPlugin (1.1): Adds options to the select type in forms
  • FilterPlugin (0.94, $Rev: 8790$): Substitute and extract information from content by using regular expressions
  • GluePlugin (1.5, $Rev: 8784$): Enable TWikiML to span multiple lines
  • HeadlinesPlugin (2.02, 8154): Build news portals that show headline news based on RSS news feeds from news sites.
  • IfDefinedPlugin (v0.91, $Rev: 9172$): Render content conditionally
  • InterwikiPlugin (Dakar, $Rev: 8713$): Link ExternalSite:Page text to external sites based on aliases defined in a rules topic
  • NatSkinPlugin (2.996, $Rev: 9397$): Supplements the bare bones NatSkin theme for TWiki
  • PreferencesPlugin (Dakar, 8170): Allows editing of preferences using fields predefined in a form
  • RedDotPlugin (1.33, $Rev: 9171$): Renders edit-links as little red dots
  • RedirectPlugin (Dakar, 13093): This plugin allows one to produce TWiki topics that automatically redirect to other TWiki topics or URLs.
  • SlideShowPlugin (Dakar, $Rev: 8713$): Create web based presentations based on topics with headings.
  • SmiliesPlugin (Dakar, 8154): Render smilies as icons, like  :-) for or  :cool: for :cool:
  • TWikiBotPlugin (Dakar, $Rev: 8713$):
  • TablePlugin (Dakar, 8154): Control attributes of tables and sorting of table columns
  • TagCloudPlugin (v0.30, $Rev: 9161$): Renders a tag cloud given a list of terms
  • TimeSincePlugin (0.99, $Rev: 8784$): Display time difference in a human readable way.
  • TwistyPlugin (Dakar, $Rev: 8862$): Twisty section javascript library to open/close content dynamically
  • UserInfoPlugin (1.50, 8832): Render information about users on your TWikiSite
• Related: ACTIVATEDPLUGINS, FAILEDPLUGINS, PLUGINVERSION

PLUGINVERSION -- the version of a TWiki Plugin, or the TWiki Plugins API

• Syntax: %PLUGINVERSION{"name"}% to get the version of a specific plugin
• Example: %PLUGINVERSION{"InterwikiPlugin"}% expands to $Rev: 8713$
• Syntax: %PLUGINVERSION% to get the version of the API
• Expands to: 1.1
• Related: WIKIVERSION, ACTIVATEDPLUGINS, FAILEDPLUGINS, PLUGINDESCRIPTIONS

PUBURL -- the base URL of attachments

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

PUBURLPATH -- the base URL path of attachments

• Syntax: %PUBURLPATH%
• Expands to: /twiki/pub
• Related: ATTACHURL, PUBURL, SCRIPTURL, SCRIPTURLPATH, FileAttachments

QUERYSTRING -- full, unprocessed string of parameters to this URL

• String of all the URL parameters that were on the URL used to get to the current page. For example, if you add ?name=Samantha;age=24;eyes=blue to this URL you can see this in action. This string can be appended to a URL to pass parameter values on to another page.
• Note: URLs built this way are typically restricted in length, typically to 2048 characters. If you need more space than this, you will need to use an HTML form and %URLPARAM{}%.
• Syntax: %QUERYSTRING%
• Expands to:
• Related: URLPARAM

REMOTE_ADDR -- environment variable

• Syntax: %REMOTE_ADDR%
• Expands to: 38.107.179.239
• Related: HTTP_HOST, REMOTE_PORT, REMOTE_USER

REMOTE_PORT -- environment variable

• Syntax: %REMOTE_PORT%
• Expands to: 50456
• Related: HTTP_HOST, REMOTE_ADDR, REMOTE_USER

REMOTE_USER -- environment variable

• Syntax: %REMOTE_USER%
• Expands to:
• Related: HTTP_HOST, REMOTE_ADDR, REMOTE_PORT, USERNAME, WIKINAME, WIKIUSERNAME

REVINFO -- revision information of current topic

• Syntax: %REVINFO%
• Expands to: r2 - 26 Oct 2005 - 18:50 - TWikiContributor
• Related: REVINFO{"format"}

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 Users web prefix	Users.JohnSmith

• Example: %REVINFO{"$date - $wikiusername" rev="1.1"}% returns revision info of first revision
• Related: REVINFO

SCRIPTNAME -- name of current script

• The name of the current script is shown, including script suffix, if any (for example viewauth.cgi)
• Syntax: %SCRIPTNAME%
• Expands to: rdiff
• Related: SCRIPTSUFFIX, SCRIPTURL, SCRIPTURLPATH

SCRIPTSUFFIX -- script suffix

• Some QBFreak.net installations require a file extension for CGI scripts, such as .pl or .cgi
• Syntax: %SCRIPTSUFFIX%
• Expands to:
• Related: SCRIPTNAME, SCRIPTURL, SCRIPTURLPATH

SCRIPTURL -- base URL of TWiki scripts

• Syntax: %SCRIPTURL%
• Expands to: http://www.qbfreak.net/twiki/bin
• Related: PUBURL, SCRIPTNAME, SCRIPTSUFFIX, SCRIPTURL{"script"}, SCRIPTURLPATH

SCRIPTURL{"script"} -- URL of TWiki script

• Syntax: %SCRIPTURL{"script"}%
• Expands to: http://www.qbfreak.net/twiki/bin/script
• Example: To get the authenticated version of the current topic you can write %SCRIPTURL{"viewauth"}%/%WEB%/%TOPIC% which expands to http://www.qbfreak.net/twiki/bin/viewauth/TWiki/TWikiVariables
• Note: In most cases you should use %SCRIPTURLPATH{"script"}% instead, as it works with URL rewriting much better
• Related: PUBURL, SCRIPTNAME, SCRIPTSUFFIX, SCRIPTURL, SCRIPTURLPATH, SCRIPTURLPATH{"script"}

SCRIPTURLPATH -- base URL path of TWiki scripts

• As %SCRIPTURL%, but doesn't include the protocol and host part of the URL
• Syntax: %SCRIPTURLPATH%
• Expands to: /twiki/bin
• Related: PUBURLPATH, SCRIPTNAME, SCRIPTSUFFIX, SCRIPTURL, SCRIPTURLPATH{"script"}

SCRIPTURLPATH{"script"} -- URL path of TWiki script

• As %SCRIPTURL{"script"}%, but doesn't include the protocol and host part of the URL
• Syntax: %SCRIPTURLPATH{"script"}%
• Expands to: /twiki/bin/script
• Related: PUBURLPATH, SCRIPTNAME, SCRIPTSUFFIX, SCRIPTURL, SCRIPTURL{"script"}, SCRIPTURLPATH

SEARCH{"text"} -- search content

• Inline search, shows a search result embedded in a topic
• Syntax: %SEARCH{"text" ...}%
• Supported parameters:

  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="Users, Know" web="all"	Comma-separated list of webs to search. The special word all means all webs that doe not have the NOSEARCHALL variable set to on in their WebPreferences. You can specifically exclude webs from an all search using a minus sign - for example, web="all,-Secretweb".	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; if you want to sort across webs, create a formatted table and sort it with TablePlugin's initsort. Note that dates are sorted most recent date last (i.e at the bottom of the table).	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
  date="..."	limits the results to those pages with latest edit time in the given TimeInterval.	All results
  reverse="on"	Reverse the direction of the search	Ascending search
  casesensitive="on"	Case sensitive search	Ignore case
  bookview="on"	BookView search, e.g. show complete topic text	Show topic summary
  nonoise="on"	Shorthand for nosummary="on" nosearch="on" nototal="on" zeroresults="off" noheader="on" noempty="on"	Off
  nosummary="on"	Show topic title only	Show topic summary
  nosearch="on"	Suppress search string	Show search string
  noheader="on"	Suppress search header Topics: Changed: By:	Show search header, unless seach is inline and a format is specified (Cairo compatibility)
  nototal="on"	Do not show number of topics found	Show number
  zeroresults="off"	Suppress all output if there are no hits	zeroresults="on", displays: "Number of topics: 0"
  noempty="on"	Suppress results for webs that have no hits.	Show webs with no hits
  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
  nofinalnewline="on"	If on, the search variable does not end in a line by itself. Any text continuing immediately after the search variable on the same line will be rendered as part of the table generated by the search, if appropriate.	off
  recurse="on"	Recurse into subwebs, if subwebs are enabled.	off
  separator=", "	Line separator between hits	Newline "$n"

• Example: %SEARCH{"wiki" web="Users" 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)
• Hint: 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

SERVERTIME -- server time

• Syntax: %SERVERTIME%
• Expands to: 22 May 2012 - 04:40
• Note: When used in a template topic, this variable will be expanded when the template is used to create a new topic. See TWikiTemplates#TemplateTopicsVars for details.
• Related: DISPLAYTIME, GMTIME, SERVERTIME{"format"}

SERVERTIME{"format"} -- formatted server time

• Same format qualifiers as %GMTIME%
• Syntax: %SERVERTIME{"format"}%
• Example: %SERVERTIME{"$hou:$min"}% expands to 04:40
• Note: When used in a template topic, this variable will be expanded when the template is used to create a new topic. See TWikiTemplates#TemplateTopicsVars for details.
• Related: DISPLAYTIME, GMTIME, SERVERTIME

SESSION_VARIABLE -- get, set or clear a session variable

• Syntax: %SESSION_VARIABLE{"name"}%
• Syntax: %SESSION_VARIABLE{"name" set="value"}%
• Syntax: %SESSION_VARIABLE{"name" clear=""}%
• Hint: The users ID is in the AUTHUSER session variable, and is read-only
• Related: TWikiUserAuthentication, AUTHREALM, SESSIONID, SESSIONVAR, LOGIN, LOGOUT

SESSIONID -- unique ID for this session

• Syntax: %SESSIONID%
• Expand to: 9b80c39157fab48a6670f2b0ecc98004
• Related: TWikiUserAuthentication, AUTHREALM, SESSIONVAR, LOGIN, LOGOUT, SESSION_VARIABLE

SESSIONVAR -- name of CGI and session variable that stores the session ID

• Syntax: %SESSIONVAR%
• Expand to: TWIKISID
• Related: TWikiUserAuthentication, AUTHREALM, SESSIONID, LOGIN, LOGOUT, SESSION_VARIABLE

SPACEDTOPIC -- topic name, spaced and URL-encoded deprecated

• The current topic name with added URL-encoded spaces, for use in regular expressions that search for backlinks to the current topic
• Syntax: %SPACEDTOPIC%
• Expands to: TWiki%20*Variables%20*Nto%20*Z
• Note: This is a deprecated variable. It can be duplicated with %ENCODE{%SPACEOUT{"%TOPIC%" separator=" *"}%}%
• Related: SPACEOUT, TOPIC, ENCODE

SPACEOUT{"string"} -- renders string with spaces inserted in sensible places

• Inserts spaces after lower case letters that are followed by a digit or a capital letter, and after digits that are followed by a capital letter.
• Useful for spacing out WikiWords
• Syntax: %SPACEOUT{ "%TOPIC%" }%
• Expands to: TWiki Variables
• Supported parameters:

  Parameter:	Description:	Default:
  separator	The separator to put between words e.g. %SPACEOUT{"DogsCatsBudgies" separator=", "}% -> Dogs, Cats, Budgies	' '

• Hint: Spaced out WikiWords are not automatically linked. To SPACEOUT a WikiWord but preserve the link use "double bracket" format. For example, [[WebHome][%SPACEOUT{"WebHome"}%]] expands to Web Home
• Related: SPACEDTOPIC, $PROPERSPACE() of SpreadSheetPlugin

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 everything exept the %STARTINCLUDE% variable itself.
• Note: If you want more than one part of the topic included, use %STARTSECTION{type="include"}% instead
• Syntax: %STARTINCLUDE%
• Related: INCLUDE, STARTSECTION, STOPINCLUDE

STARTSECTION -- marks the start of a section within a topic

• Section boundaries are defined with %STARTSECTION{}% and %ENDSECTION{}%.
• Sections may be given a name to help identify them, and/or a type, which changes how they are used.
  • type="section" - the default, used for a generic section, such as a named section used by INCLUDE.
  • type="include" - like %STARTINCLUDE% ... %STOPINCLUDE% except that you can have as many include blocks as you want (%STARTINCLUDE% is restricted to only one).
  • type="templateonly" - start position of text to be removed when a template topic is used. This is used to embed text that you do not want expanded when a new topic based on the template topic is created. See TWikiTemplates for more information.
• Syntax: %STARTSECTION{"name"}% ................ %ENDSECTION{"name"}%
• Syntax: %STARTSECTION{type="include"}% ........ %ENDSECTION{type="include"}%
• Syntax: %STARTSECTION{type="templateonly"}% ... %ENDSECTION{type="templateonly"}%
• Supported parameters:

  Parameter:	Description:	Default
  "name"	Name of the section. Must be unique inside a topic.	Generated name
  type="..."	Type of the section; type "section", "include" or "templateonly"	"section"

• Note: If a section is not given a name, it will be assigned one. Unnamed sections are assigned names starting with _SECTION0 for the first unnamed section in the topic, _SECTION1 for the second, etc..
• Note: You can define nested sections. It is not recommended to overlap sections, although it is valid in TWiki. Use named sections to make sure that the correct START and ENDs are matched. Section markers are not displayed when a topic is viewed.
• Related: ENDSECTION, INCLUDE, NOP, STARTINCLUDE, STOPINCLUDE

STATISTICSTOPIC -- name of statistics topic

• Syntax: %STATISTICSTOPIC%
• Expands to: WebStatistics, renders as WebStatistics
• Related: HOMETOPIC, NOTIFYTOPIC, 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

• Syntax: %TOC%
• Related: TOC{"Topic"}

TOC{"Topic"} -- table of contents

• 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
• Syntax: %TOC{"SomeTopic" ...}%
• 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
• Hint: TOC will generate links to the headings, so when a reader clicks on a heading it will jump straight where that heading is anchored in the text. If you have two headings with exactly the same text, then their anchors will also be identical and they won't be able to jump to them. To make the anchors unique, you can add an invisible HTML comment to the text of the heading. This will be hidden in normal view, but will force the anchors to be different. For example, ---+ Heading <!--5-->.
• Related: TOC

TOPIC -- name of current topic

• Syntax: %TOPIC%
• Expands to: TWikiVariables, renders as TWikiVariables
• Related: BASETOPIC, INCLUDINGTOPIC, TOPICLIST, WEB

TOPICLIST{"format"} -- topic index of a web

• List of all topics in a web. The "format" defines the format of one topic item. It may include variables: The $name variable gets expanded to the topic name, $qname to double quoted name, $marker to marker parameter where topic matches selection, and $web to the name of the web.
• Syntax: %TOPICLIST{"format" ...}%
• Supported parameters:

  Parameter:	Description:	Default:
  "format"	Format of one line, may include $web (name of web), $name (name of the topic), $qname (name of topic in double quotes), $marker (which expands to marker for the item matching selection only)	"$name"
  format="format"	(Alternative to above)	"$name"
  separator=", "	line separator	"$n" (new line)
  marker="selected"	Text for $marker if the item matches selection	"selected"
  selection="TopicA, TopicB"	Current value to be selected in list	(none)
  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)
• Example: <select>%TOPICLIST{" <option $marker value='$name'>$name</option>" separator=" " selection="%TOPIC%"}%</select> creates an option list of web topics with the current topic selected
• Related: SEARCH, WEBLIST

TWIKIWEB -- name of TWiki documentation web

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

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

• Returns the value of a URL parameter.
• 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. See ENCODE for more details.	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/TWikiVariables?skin=print URL
• Note: URL parameters passed into HTML form fields must be entity ENCODEd
• Note: When used in a template topic, this variable will be expanded when the template is used to create a new topic. See TWikiTemplates#TemplateTopicsVars for details.
• Note: There is a risk that this variable could be misused for cross-site scripting.
• Related: ENCODE, SEARCH, FormattedSearch, QUERYSTRING

USERINFO - retrieve details about the logged in user

• By default, the retrieved info will be formatted as a comma-separated list comprising the username, wikiusername, and emails.
• Syntax: %USERINFO%
• Expands to: =guest, TWikiGuest, =
• you can also use the format parameter to get different formatted results:
• Syntax: %USERINFO{format="$username is really $wikiname"}%
• Expands to guest is really TWikiGuest?
• The tokens $emails, $username, $wikiname, $wikiusername, and $groups are available for use in the format string.
• Related: USERNAME, WIKINAME, WIKIUSERNAME, TWikiUserAuthentication, ChangeEmailAddress

USERNAME -- your login username

• TWiki makes names available in three formats: USERNAME like jsmith, WIKINAME like JohnSmith and WIKIUSERNAME like Users.JohnSmith. Un-authenticated users are all TWikiGuest.
• Syntax: %USERNAME%
• Expands to: guest
• Note: When used in a template topic, this variable will be expanded when the template is used to create a new topic. See TWikiTemplates#TemplateTopicsVars for details.
• Related: REMOTE_USER, USERINFO, WIKINAME, WIKIUSERNAME, TWikiUserAuthentication

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

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

WEB -- name of current web

• Syntax: %WEB%
• Expands to: TWiki
• Related: BASEWEB, INCLUDINGWEB, TOPIC

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 (the name of the web), $qname (the name of the web in double quotes), $indentedname (the name of the web with parent web names replaced by indents, for use in indented lists), and $marker (which expands to marker for the item matching selection only)	"$name"
  format="format"	(Alternative to above)	"$name"
  separator=", "	line separator	"$n" (new line)
  webs="public"	comma separated list of webs, public expands to all non-hidden	"public"
  marker="selected"	Text for $marker if the item matches selection	"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=" "}% creates a dropdown of all public webs + Trash web, with the current web highlighted.
• Related: TOPICLIST, SEARCH

WEBPREFSTOPIC -- name of web preferences topic

• Syntax: %WEBPREFSTOPIC%
• Expands to: WebPreferences, renders as WebPreferences
• Related: HOMETOPIC, WIKIPREFSTOPIC, VAR

WIKIHOMEURL -- site home URL deprecated

• Note: use %WIKILOGOURL% defined in WebPreferences instead.

WIKINAME -- your Wiki username

• The WikiName is the same as %USERNAME% if not defined in the TWikiUsers topic
• Syntax: %WIKINAME%
• Expands to: TWikiGuest
• Note: When used in a template topic, this variable will be expanded when the template is used to create new topic. See TWikiTemplates#TemplateTopicsVars for details.
• Related: REMOTE_USER, USERINFO, USERNAME, WIKIUSERNAME, WIKIUSERSTOPIC

WIKIPREFSTOPIC -- name of site-wide preferences topic

• Syntax: %WIKIPREFSTOPIC%
• Expands to: TWikiPreferences, renders as TWikiPreferences
• Related: HOMETOPIC, WEBPREFSTOPIC

WIKITOOLNAME -- name of your TWiki site

• Syntax: %WIKITOOLNAME%
• Expands to: QBFreak.net
• Related: WIKIHOMEURL, WIKIVERSION

WIKIUSERNAME -- your Wiki username with web prefix

• Your %WIKINAME% with Users web prefix, useful to point to your QBFreak.net home page
• Syntax: %WIKIUSERNAME%
• Expands to: Users.TWikiGuest, renders as TWikiGuest
• Note: When used in a template topic, this variable will be expanded when the template is used to create a new topic. See TWikiTemplates#TemplateTopicsVars for details
• Related: REMOTE_USER, USERINFO, USERNAME, WIKINAME

WIKIUSERSTOPIC -- name of topic listing all registers users

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

WIKIVERSION -- the version of the installed TWiki engine

• Syntax: %WIKIVERSION%
• Expands to: Wed, 08 Feb 2006 build 8740
• Related: PLUGINVERSION, WIKITOOLNAME

TWiki Forms

Add structure to content with forms attached to twiki topics. TWiki forms (with form fields) and formatted search are the base for building database applications.

Overview

By adding form-based input to freeform content, you can structure topics with unlimited, easily searchable categories. A form is enabled for a web and can be added to a topic. The form data is shown in tabular format when the topic is viewed, and can be changed in edit mode using edit fields, radio buttons, check boxes and list boxes. Many different form types can be defined in a web, though a topic can only have only form attached to it at a time.

Typical steps to build an application based on TWiki forms:

1. Define a form template
2. Enable the form for a web
3. Add the form to a template topic
4. Build an HTML form to create new topics based on that template topic
5. Build a FormattedSearch to list topics that share the same form

Defining a Form Template

A Form Template specifies the fields in a form. A Form Template is simply a page containing a TWiki table, where each row of the table is one form field.

Form Template Elements

• form template - a set of fields defining a form
  • A web can use one or more form templates
• form - additional meta data (besides the freeform TEXTAREA) attached to a topic
  • Within a form-enabled web, individual topics can have a form or no form
• form field - a named item in a form (also known as a key)
• field type - selects the field type:

  Input type	Type field	Size field	Value field
  One or more checkboxes	checkbox	number of items per line	comma list of item labels
  One or more checkboxes, plus Set and Clear buttons	checkbox+buttons	(same)	(same)
  One or more radio buttons (radio buttons are mutually exclusive; only one can be selected)	radio	(same)	(same)
  Read-only label text	label	ignored	text
  Drop-down menu or scrollable box	select	1 for drop down, 2 and up for scrollable box	comma-separated list of options
  A one-line text field	text	text box width in number of characters	initial text, if a new topic is created with a form template
  A text box	textarea	columns x rows, e.g. 80x6; default size is 40x5	initial text, if a new topic is created with a form template

• field value - one or more values from a fixed set (select, checkbox, radio type) or free-form (label, text, text area).

Defining a Form

1. Create a new topic with your form name: YourForm, ExpenseReportForm, InfoCategoryForm, RecordReviewForm, whatever you need.
2. Create a TWiki table, with each column head representing one element of an entry field: Name, Type, Size, Values, Tooltip message, and Attributes (see sample below).
3. For each field, fill in a new line; for the type of field, select from the list.
4. Save the topic (you can later choose to enable/disable individual forms).

Example: WebForm
| *Name* | *Type* | *Size* | *Values* | *Tooltip message* | *Attributes* |
| TopicClassification | select | 1 | NoDisclosure, PublicSupported, PublicFAQ | blah blah... |   |
| OperatingSystem | checkbox | 3 | OsHPUX, OsLinux, OsSolaris, OsWin | blah blah... |   |
| OsVersion | text | 16 | | blah blah... |   |

Name	Type	Size	Values	Tooltip message	Attributes
TopicClassification	select	1	NoDisclosure, PublicSupported, PublicFAQ	blah blah...
OperatingSystem	checkbox	3	OsHPUX, OsLinux, OsSolaris, OsWin	blah blah...
OsVersion	text	16		blah blah...

You can also retrieve possible values for select, checkbox or radio types from other topics:

Example: WebForm

• In the WebForm topic, define the form:
  

  Name	Type	Size	Values	Tooltip message	Attributes
  TopicClassification	select	1		blah blah...
  OperatingSystem	checkbox	3		blah blah...
  OsVersion	text	16		blah blah...

  
  Leave the Values field blank.

• Then in the TopicClassification topic, define the possible values:
  

  Name	Type	Tooltip message
  NoDisclosure	option	blah blah...
  Public Supported	option	blah blah...
  Public FAQ	option	blah blah...

Field values can also be obtained as the result of a FormattedSearch. For example,

%SEARCH{"Office$" scope="topic" web="%MAINWEB%" nototal="on" nosummary="on" nosearch="on" regex="on" format="$web.$topic" separator=", " }%

when used in the value field of the form definition, will take the set of field values to be all topic names in the Main web which end in "Office".

Notes:

• A very few field names are reserved. If you try to use one of these names, TWiki will automatically append an underscore to the name when the form is used.
• The field value will be used to initialize a field when a form is created, unless specific values are given by the topic template or query parameters. The first item in the list for a select or radio type is the default item. For label, text, and textarea fields the value may also contain commas. checkbox fields cannot be initialized through the form template.
• If a label field has no name (blank first column in the form definition) it will not be shown when the form is viewed, only when it is edited.
• The topic definition is not read when a topic is viewed.
• Field names can include any text, but you should stick to alphanumeric characters. If you want to use a non-wikiname for a select, checkbox or radio field, and want to get the values from another topic, you can use [[...]] links. This notation can also be used when referencing another topic to obtain field values, but a name other than the topic name is required as the name of the field.
• Field names have to be unique. If the same name is necessary (as when the field values for several fields are obtained from the same topic), an alternative name must be assigned using the [[...]] notation.
• The topic defining field values can also be generated through a FormattedSearch, which must yield a suitable table as the result.
• Form definition topics can be protected in the usual manner, using TWikiAccessControl, to limit who can change the form template and/or individual value lists. Note that view access is required to be able to edit topics that use the form definition, though view access to the form definition is not required to view a topic where the form has been used.
• The Tooltip message column is used as a tooltip for the field name (only if field name is a WikiName) - you only see the tooltip in edit view.
• The Attributes column is used to define special behavior for that form field (multiple attributes can be entered, with or without separators):
  • An attribute H indicates that this field should not be shown in view mode. However, the field is available for editing and storing information.
  • An attribute M indicates that this field is mandatory. The topic cannot be saved unless a value is provided for this field. If the field is found empty during topic save, an error is raised and the user is redirected to an oops page. Mandatory fields are indicated by an asterisks next to the field name.

Enabling Forms by Web

Forms have to be enabled for each individual web. The WEBFORMS variable in WebPreferences is optional and defines a list of possible form templates.

Example:

• Set WEBFORMS = BugForm, FeatureForm, Books.BookLoanForm

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

Add a form to a topic

• Edit a topic and follow the "Add form" button to add a Form to the topic. This is typically done to a template topic, either to the WebTopicEditTemplate topic in a web, or a new topic that serves as an application specific template topic. Initial Form values can be set there.

• Additionally a new topic can be given a Form using the formtemplate parameter in the (edit or save) URL. Initial values can then be provided in the URLs or as form values:
  • other than checkboxes: name, ex: ?BugPriority=1
  • checkbox: namevalue=1, ex: ?ColorRed=1.
    Boxes with a tick must be specified.
  • Example: This will add a textfield for the new topic name and a "Create"-Button to your topic. When the button is pressed, the topic editor will open with the form "MyForm" already attached to the new topic.

        <form name="newtopic" action="%SCRIPTURLPATH{"edit"}%/%WEB%/">
           <input type="hidden" name="formtemplate" value="MyForm" />
           New topic name <input type="text" name="topic" size="40" />
           <input type="submit" value="Create" />
        </form>
           

• Tip: For TWiki applications you can automatically generate unique topicnames.

• Note: Initial values will not be submitted to the form of a new topic if you only use the formtemplate parameter.

Build an HTML form to create new Form-based topics

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

Changing a form

• You can change a form definition, and TWiki will try to make sure you don't lose any data from the topics that use that form.

• If you change the form definition, the changes will not take affect in a topic that uses that form until you edit and save it.

• If you add a new field to the form, then it will appear next time you edit a topic that uses the form.

• If you delete a field from the form, or change a field name, then the data will not be visible when you edit the topic (the changed form definition will be used). If you save the topic, the old data will be lost (though thanks to revision control, you can always see it in older versions of the topic)

Searching for Form Data

Example
TWiki users often want to have an overview of topics they contributed to. With the $formfield parameter it is easy to display the value of a classification field next to the topic link:

| *Topic* | *Classification* |
%SEARCH{"%MAINWEB%.UserName" scope="text" regex="off" nosearch="on" nototal="on" order="modified" reverse="on"
format="|<b>[[$web.$topic][$topic]]</b> |<nop>$formfield(TopicClassification) |" web="Sandbox"}%

Extending the range of form data types

• any type name starting with checkbox
• any type name with +multi anywhere in the name

Gotcha!

• Some browsers may strip linefeeds from text fields when a topic is saved. If you need linefeeds in a field, make sure it is a textarea.

Importing Category Table Data

Very, very old TWiki releases used a system called the "TWikiCategoryTable". Later releases support automatic import of this data.

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

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

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