TWiki Reference Manual (01-Sep-2001)

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

Note: Read the most up to date version of this document at http://TWiki.org/cgi-bin/view/TWiki/TWikiDocumentation

Related Topics: TWikiSite, TWikiHistory, TWikiPlannedFeatures, TWikiEnhancementRequests

Warning: Can't find topic TWikiImplementationNotes

TWiki Installation Guide

Installation instructions for the TWiki Dakar production release

Please review the AdminSkillsAssumptions before you install TWiki.

TWiki should be fine with any web server and OS that meet the system requirements. See the cookbooks list at TWiki:Codev.CategoryCookbook for guidance for your particular platform.

If you need help, ask a question in the TWiki:Support web or on TWiki:Codev.TWikiIRC (irc.freenode.net, channel #twiki)

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 (optional)

• Edit the TWikiPreferences topic in the TWiki web. 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)
  • Alternately, you can 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.
• Enable authentication, if required. Read TWikiUserAuthentication..
• Enable email notification (WebChangesAlerts). Read TWikiSiteTools.
• Install Plugins. 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 for the other plugins can be found in the plugin topics on TWiki.org.

Troubleshooting

Failing that, please check the topics listed below, they include some important tips for HP-UX, Solaris, OS/390, and many other platforms.

• For Unix or Linux, check TWiki:Codev/TWikiOnUnix and TWiki:Codev/TWikiOnLinux.
• For Windows, check the TWiki:Codev/WindowsInstallCookbook.
• For MacOS X, check TWiki:Codev/TWikiOnMacOSX.
• To install TWiki on SourceForge, for use on a software development project, read TWiki:Codev/TWikiOnSourceForge
• For other platforms, see TWiki:Codev/TWikiOn, and search the TWiki:Codev and TWiki:Support webs for other installation notes.

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 Sep-2004 "Cairo" production release to TWiki "Dakar"

Overview

Dakar is a major new release. You can chose between an automated upgrade using a script or a manual update.

Upgrade Requirements

• Please review the AdminSkillsAssumptions before you upgrade TWiki
• To upgrade from a Cairo standard installation to the latest Dakar Production Release, follow the instructions below
• NOTE: To upgrade from a pre-Cairo TWiki, start with TWikiUpgradeToCairo
• To upgrade from a Beta of the new release, or if you made custom modifications, read through all new reference documentation, then use the procedure below as a guideline
• Once the upgrade has been applied, an existing earlier installation will still be able to read all the topics, but will not be able to write. Make sure you take a backup!
• Not all Cairo plugins are supported with Dakar. Make sure the plugins you use can be upgraded as well!

Major Changes Compared to TWiki Cairo

SEE TWiki:Codev.DakarReleaseNotes FOR NOW

Automated Upgrade Procedure

If you would prefer to do things manually, 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 permissions so 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.

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.

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

1. Transfer any local settings from TWikiPreferences to the topic pointed at by {LocalSitePreferences} (usually TWikiPreferences). This avoids having to write over files in the distribution.
2. 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.
3. Point your webserver at the new install.

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

TWiki User Authentication

TWiki site access control and user activity tracking options

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.

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.

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

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, email 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 TWiki:Main 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).

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

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

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

TWiki can automatically map an Intranet (Login) Username to a TWiki Username 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 Main web name in front of the Wiki username, followed by a period, and no spaces. Ex:

Main.WikiUsername or %MAINWEB%.WikiUsername

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

Changing Passwords

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

Controlling access to individual scripts

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

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:Codev.SecuringYourTWiki for more information

TWiki Access Control

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

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

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 be denied view to TWikiGuest - otherwise people will not be able to register.

Related Topics: SiteMap, UserDocumentationCategory, AdminDocumentationCategory, AdminToolsCategory

This table comes from SitePermissions

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

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

Authentication vs. Access Control

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

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

Users and Groups

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

Managing Users

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

• WikiName and encrypted password are recorded 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 Main 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 created in the Main web, like the TWikiAdminGroup. To create a new group:

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

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 SuperAdminGroup

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, you can create superusers:

• Edit the SuperAdminGroup as described above and add the wikinames of a group of Users who are always allowed to edit/view topics e.g.
  • Set GROUP= ElizabethWindsor?,Main.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 FS 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

Obfusticating 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 = Main.SomeGroup
-->

TWiki Templates

Definition of the templates used to render all HTML pages displayed in TWiki

Overview

There are three types of template:

• Master Templates: Define blocks of text for use in other templates
• HTML Page Templates: Define the layout of FS pages
• Template Topics: Define default text when you create a new topic

All three types of template use the TWiki template system.

The TWiki Template System

Templates are plain text with embedded template directives that tell TWiki how to compose blocks of text together to create something new.

How Template Directives Work

• Template directives are embedded in templates.
• Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
• Directives:
  • %TMPL:INCLUDE{"file"}%: Includes a template file. The file is found as described below.
  • %TMPL:DEF{"block"}%: Define a block. Text between this and the %TMPL:END% directive is not used in-place, but is saved for later use with %TMPL:P. Leading and trailing whitespace is ignored.
  • %TMPL:END%: Ends a block definition.
  • %TMPL:P{"var"}%: Includes a previously defined block.
  • %{...}%: is a comment.
• Two-pass processing lets you use a variable before or after declaring it.
• Templates and TWikiSkins work transparently and interchangeably. For example, you can create a skin that overloads only the twiki.tmpl master template, like twiki.print.tmpl, that redefines the header and footer.
• Use of template directives is optional: templates work without them.
• NOTE: Template directives work only for templates: they do not get processed in normal topic text.

TMPL:P also supports simple parameters. For example, given the definition %TMPL:DEF{"x"}% x%P%z%TMPL:END% then %TMPL:P{"x" P="y"}% will expand to xyz.

Note that parameters can simply be ignored; for example=%TMPL:P{"x"}%= will expand to x%P%z.

Any alphanumeric characters can be used in parameter names. You are highly recommended to use parameter names that cannot be confused with TWikiVariables.

Note that three parameter names, context, then and else are reserved. They are used to support a limited form of "if" condition that you can use to select which of two templates to use, based on a context identifier:

%TMPL:DEF{"link_inactive"}%<input type="button" disabled value="Link>%TMPL:END%
%TMPL:DEF{"link_active"}%<input type="button" onclick="link()" value="Link" />%TMPL:END%
%TMPL:P{context="inactive" then="inactive_link" else="active_link"}% for %CONTEXT%

Finding Templates

Templates are stored either in the twiki/templates directory, or can also be read from user topics. As an example, twiki/templates/view.tmpl is the default template file for the twiki/bin/view script.

Templates that are included using %TMPL:INCLUDE% are also found using the same search algorithm, unless you explicitly put '.tmpl' at the end of the template name. In this case, the string is assumed to be the full name of a template in the templates directory, and the algorithm isn't used.

TWiki uses the following search order to determine which template file or topic to use for a particular script. The skin path is set as described in TWikiSkins.

1. templates/web/script.skin.tmpl for each skin on the skin path
   • this usage is supported for compatibility only and is deprecated. Store web-specific templates in TWiki topics instead.
2. templates/script.skin.tmpl for each skin on the skin path
3. templates/web/script.tmpl
   • this usage is supported for compatibility only and is deprecated. Store web-specific templates in TWiki topics instead.
4. templates/script.tmpl
5. The TWiki topic web.topic if the template name can be parsed into web.topic
6. The TWiki topic web.SkinSkinScriptTemplate for each skin on the skin path
7. The TWiki topic web.ScriptTemplate
8. The TWiki topic TWiki.SkinSkinScriptTemplate for each skin on the skin path
9. The TWiki topic TWiki.ScriptTemplate

Legend:

• script refers to the script name, e.g view, edit
• Script refers to the same, but with the first character capitalized, e.g View
• skin refers to a skin name, e.g dragon, pattern. All skins are checked at each stage, in the order they appear in the skin path.
• Skin refers to the same, but with the first character capitalized, e.g Dragon
• web refers to the current web

1. templates/Thisweb/example.print.tmpl deprecated; don't rely on it
2. templates/Thisweb/example.pattern.tmpl deprecated; don't rely on it
3. templates/example.print.tmpl
4. templates/example.pattern.tmpl
5. templates/Thisweb/example.tmpl deprecated; don't rely on it
6. templates/example.tmpl
7. Thisweb.PrintSkinExampleTemplate
8. Thisweb.PatternSkinExampleTemplate
9. Thisweb.ExampleTemplate
10. TWiki.PrintSkinExampleTemplate
11. TWiki.PatternSkinExampleTemplate
12. TWiki.ExampleTemplate

Template names are usually derived from the name of the currently executing script; however it is also possible to override these settings in the view and edit scripts, for example when a topic-specific template is required. Two preference variables can be user to override the templates used:

• VIEW_TEMPLATE sets the template to be used for viewing a topic
• EDIT_TEMPLATE sets the template for editing a topic.

Master Templates

Template variable:	Defines:
%TMPL:DEF{"sep"}%	"|" separator
%TMPL:DEF{"htmldoctype"}%	Start of all HTML pages
%TMPL:DEF{"standardheader"}%	Standard header (ex: view, index, search)
%TMPL:DEF{"simpleheader"}%	Simple header with reduced links (ex: edit, attach, oops)
%TMPL:DEF{"standardfooter"}%	Footer, excluding revision and copyright parts
%TMPL:DEF{"oops"}%	Skeleton of oops dialog

HTML Page Templates

HTML page templates are files of HTML mixed with template directives that tell TWiki how to build up an HTML page. As described above, the template system supports the use of 'include' directives that let you re-use the same sections of HTML - such as headers and footers - in several different places.

TWiki uses HTML page templates when composing the output from all actions, like topic view, edit, and preview. This allows you to change the look and feel of all pages by editing just a few template files.

HTML page templates are also used in the definition of TWikiSkins.

Template Topics

Template topics define the default text for new topics. There are three types of template topic:

Topic Name:	What it is:
WebTopicViewTemplate	Error page shown when you try to view a nonexistent topic
WebTopicNonWikiTemplate	Alert page shown when you try to view a nonexistent topic with a non-WikiName
WebTopicEditTemplate	Default text shown when you create a new topic.

1. A topic name specified by the templatetopic CGI parameter
   • if no web is specified, the current web is searched first and then the TWiki web
2. WebTopicEditTemplate in the current web
3. WebTopicEditTemplate in the TWiki web

Edit Template Topics and Variable Expansion

The following variables get expanded when a user creates a new topic based on a template topic:

Variable:	Description:
%DATE%	Signature format date. See TWikiVariables#VarDATE
%GMTIME%	Date/time. See TWikiVariables#VarGMTIME
%GMTIME{...}%	Formatted date/time. See TWikiVariables#VarGMTIME2
%NOP%	A no-operation variable that gets removed. Useful to prevent a SEARCH from hitting an edit template topic; also useful to escape a variable like %URLPARAM%NOP%{...}%
%NOP{ ... }%	Text that gets removed when a new topic based on the template is created. See notes below.
%SERVERTIME%	Date/time. See TWikiVariables#VarSERVERTIME
%SERVERTIME{...}%	Formatted date/time. See TWikiVariables#VarSERVERTIME2
%USERNAME%	Login name of user who is instantiating the new topic, e.g. guest
%URLPARAM{"name"}%	Value of a named URL parameter
%WIKINAME%	WikiName of user who is instantiating the new topic, e.g. TWikiGuest
%WIKIUSERNAME%	User name of user who is instantiating the new tpoic, e.g. Main.TWikiGuest

The NOP tag is used to embed text that you do not want expanded when a new topic based on the template is created. For example, you might want to write in the template:

This template can only be changed by:
   * Set ALLOWTOPICCHANGE = WikiMastersGroup

%NOP% (or %NOP{}% can be used to prevent expansion of TWiki variables that would otherwise be expanded during topic creation e.g. %SERVERTIME%.

Notes:

• %NOP{ ... }% can span multiple lines.
• The scan for the closing }% pattern is "non-greedy", that is, it stops at the first occurence. That means you have to protect variables with parameters located inside %NOP{ ... }%. To do this, insert a %NOP% between } and %. Example: %NOP{ %GMTIME{"$year"}%NOP%% }%.

All other variables are unchanged, e.g. are carried over "as is" into the new topic.

Template Topics in Action

Here is an example for creating new topics based on a specific template topic:

The above form asks for a topic name. A hidden input tag named templatetopic specifies ExampleTopicTemplate as the template topic to use. Here is the HTML source of the form:

<form name="new" action="%SCRIPTURL{"edit"}%/%INTURLENCODE{"%WEB%"}%/">
   * New example topic: 
     <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
     <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
     <input type="hidden" name="topicparent" value="%TOPIC%" />
     <input type="hidden" name="onlywikiname" value="on" />
     <input type="hidden" name="onlynewtopic" value="on" />
     <input type="submit" class="twikiSubmit" value="Create" />
     (date format is <nop>YYYYxMMxDD)
</form>

See TWikiScripts for details of the parameters that the edit script understands.

TIP: You can use the %WIKIUSERNAME% and %DATE% variables in your topic templates to include the signature of the person creating a new topic. The variables are expanded into fixed text when a new topic is created. The standard signature is:
-- %WIKIUSERNAME% - %DATE%

Automatically Generated Topicname

If you want to make a TWiki application where you need automatically generated unique topicnames, you can use 10 X's in the edit / save URL, and they will be replaced on topic save with a count value. For example, BugIDXXXXXXXXXX will result in topics named BugID0, BugID1, BugID2 etc.

Example link to create a new topic:
[[%SCRIPTURL{"edit"}%/%WEB%/BugIDXXXXXXXXXX?templatetopic=BugTemplate&topicparent=%TOPIC%&t=%SERVERTIME{"$day$hour$min$sec"}%][Create new item]]

Master Templates by Example

Attached is an example of an oops based template oopsbase.tmpl and an example oops dialog oopstest.tmpl based on the base template. %A% NOTE: This isn't the release version, just a quick, simple demo.

Base template oopsbase.tmpl

The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%

%TMPL:DEF{"sep"}% | %TMPL:END% <html> <head> <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title> <base href="%SCRIPTURL{"view"}%/%WEB%/%TOPIC%"> <meta name="robots" content="noindex"> </head> <body bgcolor="#FFFFFF"> <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr> <td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%"> <a href="%WIKIHOMEURL%"> <img src="%PUBURLPATH%/wikiHome.gif" border="0"></a> </td> <td> <b>%WIKITOOLNAME% . %WEB% . </b><font size="+2"> <B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font> </td> </tr> <tr bgcolor="%WEBBGCOLOR%"> <td colspan="2"> %TMPL:P{"webaction"}% </td> </tr> </table> --- ++ %TMPL:P{"heading"}% %TMPL:P{"message"}% <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr bgcolor="%WEBBGCOLOR%"> <td valign="top"> Topic <b>%TOPIC%</b> . { %TMPL:P{"topicaction"}% } </td> </tr> </table> </body>

Test template oopstest.tmpl

Each oops template basically just defines some variables and includes the base template that does the layout work.

</table >

Sample screen shot of oopstest.tmpl

With URL: .../bin/oops/Sandbox/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify

%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END% %TMPL:DEF{"webaction"}% test =webaction= %TMPL:END% %TMPL:DEF{"heading"}% Test heading %TMPL:END% %TMPL:DEF{"message"}% Test =message=. Blah blah blah blah blah blah blah blah blah blah blah... * Some more blah blah blah blah blah blah blah blah blah blah... * Param1: %PARAM1% * Param2: %PARAM2% * Param3: %PARAM3% * Param4: %PARAM4% %TMPL:END% %TMPL:DEF{"topicaction"}% Test =topicaction=: [[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}% [[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END% %TMPL:INCLUDE{"oopsbase"}%

Related Topics: TWikiSkins, DeveloperDocumentationCategory, AdminDocumentationCategory

TWiki Skins

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

Overview

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

Defining Skins

Skin files are located in the twiki/templates directory and are named with the syntax: <scriptname>.<skin>.tmpl. For example, the Printable skin for the view template is view.print.tmpl. Skin files may also be defined in TWiki topics - see TWikiTemplates for details.

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

Note: Two skin names have reserved meanings; text skin, and skin names starting with rss have hard-coded meanings.

The following template files are referenced in the TWiki core code, and must be defined in the templates directory for a skin to work. Remember that if a skin doesn't define a template, then TWiki will fall back to the default version of the file.

Certain template files are expected to provide certain TMPL:DEFs - these are listed in sub-bullets.

• addform
• attachagain
• attachnew
• attachtables
  • ATTACH:files:footer, ATTACH:files:header, ATTACH:files:row, ATTACH:versions:footer, ATTACH:versions:header, ATTACH:versions:row
• changeform
• changes
• edit
• form
• formtables
  • FORM:display:footer, FORM:display:header, FORM:display:row
• login
  • LOG_IN, LOG_IN_BANNER, LOG_OUT, LOGGED_IN_BANNER, NEW_USER_NOTE, UNRECOGNISED_USER
• mirrorlink
• mirrornote
• moveattachment
• oopsaccessdenied
  • no_such_topic, no_such_web, only_group, topic_access
• oopsattention
  • already_exists, bad_email, bad_ver_code, bad_wikiname, base_web_missing, confirm, created_web, delete_err, illegally_named_upload, invalid_web_color, invalid_web_name, in_a_group, mandatory_field, merge_notice, missing_action, missing_fields, move_err, missing_action, no_form_def, no_users_to_reset, notwikiuser, oversized_upload, password_changed, password_mismatch, problem_adding, remove_user_done, rename_err, rename_not_wikiword, rename_topic_exists, rename_web_err, rename_web_exists, rename_web_prerequisites, reset_bad, reset_ok, save_error, send_mail_error, thanks, topic_exists, unrecognized_action, web_creation_error, web_exists, web_missing, wrong_password, zero_size_upload
• oopsleaseconflict
  • active, old
• oopsmirror
• oopssaveerr
• preview
• rdiff
• registernotify
• registernotifyadmin
• rename
• renameconfirm
• renamedelete
• renameweb
• renamewebconfirm
• renamewebdelete
• searchbookview
• searchformat
• search
• settings
• view

Variables in Skins

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

The "Go" Box and Navigation Box

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

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

Using Cascading Style Sheets

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

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

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

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

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

Attachment Tables

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

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

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

Packaging and Publishing Skins

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

Browsing Installed Skins

You can try all installed skins in TWikiSkinBrowser.

Activating Skins

TWiki uses a skin search path, which lets you combine skins additively. The skin path is defined using a combination of TWikiVariables and URL parameters.

TWiki works by asking for a template for a particular function - for example, 'view'. The detail of how templates are searched for is described in TWikiTemplates, but in summary, the templates directory is searched for a file called view.skin.tmpl, where skin is the name of the skin e.g. pattern. If no template is found, then the fallback is to use view.tmpl. Each skin on the path is searched for in turn. For example, if you have set the skin path to local,pattern then view.local.tmpl will be searched for first, then view.pattern.tmpl and finally view.tmpl.

The basic skin is defined by setting the %SKIN% TWiki Variable:

• Set SKIN = catskin, bearskin

You can also add a parameter to the URL, such as ?skin=catskin, bearskin. Example activation of PlainSkin that removes all page decoration:

• /bin/view/TWiki/TWikiSkins?skin=plain

Setting %SKIN% (or the ?skin parameter in the URL) replaces the existing skin path setting. You can also extend the existing skin path as well, using covers.

• Set COVER = ruskin

This pushes a different skin to the front of the skin search path (so for our example above, that final skin path will be ruskin, catskin, bearskin). There is also an equivalent cover URL parameter.

The full skin path is built up as follows: %SKIN% (or ?skin if it is set), then %COVER% is added, then ?cover.

Hard Coded Skins

The text skin is reserved for TWiki internal use.

Skin names starting with rss also have a special meaning; if one or more of the skins in the skin path starts with 'rss' then 8-bit characters will be encoded as XML entities in the output, and the content-type header will be forced to text/xml.

Related Topics: AdminDocumentationCategory, DeveloperDocumentationCategory

TWiki Variables

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

TWikiVariables are text strings - %VARIABLE% - that expand into content whenever a page is rendered for viewing. Some variables can even take parameters - %VARIABLE{parameter="value"}%.

• 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.
• Optional plugins may extend the set of predefined variables

Setting Variables

1. local site level in TWikiPreferences
2. user level in individual user topics in Main 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.

There are many predefined variables defined by default, and many more may already have been defined for your site. You can put %ALL_VARIABLES% into a topic anywhere in your TWiki to get a full listing of the variables defined there.

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] = [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 page, and upload a logo file, ex: mylogo.gif. You can upload by attaching the file to WebPreferences, or, to avoid clutter, to any other topic in the same web, ex: LogoTopic - Sample variable setting in WebPreferences:
  • Set MYLOGO = %PUBURLPATH%/TWiki/LogoTopic/mylogo.gif

You can also set preference 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

Local values for variables

   * Set EDITBOXHEIGHT = 10
   * Local EDITBOXHEIGHT = 20

Use this powerful feature with great care! %ALL_VARIABLES% 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.

Predefined Variables

Most predefined variables return values that were either set in the configuration when TWiki was installed, or taken from server info (like 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%.

ACTIVATEDPLUGINS -- list of currently activated plugins

• Syntax: %ACTIVATEDPLUGINS%
• Expands to: CommentPlugin, EditTablePlugin, ExifMetaDataPlugin, HeadlinesPlugin, InterwikiPlugin, PreferencesPlugin, RedirectPlugin, SlideShowPlugin, SmiliesPlugin, SpreadSheetPlugin, TablePlugin
• Related: PLUGINDESCRIPTIONS, FAILEDPLUGINS, PLUGINVERSION

ATTACHURL -- full URL for attachments in the current topic

• Syntax: %ATTACHURL%
• Expands to: https://fs.rainysky.org/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: /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 credentials.
• 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: 17 Jun 2026
• 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: 17 Jun 2026 - 14:23
• 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 14:23
• Related: DISPLAYTIME, GMTIME, SERVERTIME

ENCODE{"string"} -- encodes a string

• Syntax: %ENCODE{"string"}%
• Supported parameters:

  Parameter:	Description:	Default:
  "string"	String to encode	required (can be empty)
  type="entity"	Encode special characters into HTML entities, like a double quote into "	URL encoding
  type="url"	Encode special characters for URL parameter use, like a double quote into %22	(this is the default)

• Example: %ENCODE{"spaced name"}% expands to spaced%20name
• Related: URLPARAM

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

• Syntax: %ENDSECTION{"name"}%
• Supported parameters:

  Parameter:	Description:	Default:
  "name"	Name of the section. Must be unique inside a topic, and must match with a previous %SECTION% variable.	Mandatory parameter without a default

• Related: INCLUDE, SECTION, STARTINCLUDE, STOPINCLUDE

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

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

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

• Syntax: %FORMFIELD{"fieldname"}%
• Supported parameters:

  Parameter:	Description:	Default:
  "fieldname"	The name of a TWiki form field	required
  topic="..."	Topic where form data is located. May be of the form Web.TopicName	Current topic
  format="..."	Format string. $value expands to the field value, 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: 17 Jun 2026 - 14:23
• 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	2026-06-17T14:23Z
  $rcs	RCS format timestamp	2026/06/17 14:23:23
  $http	E-mail & http format timestamp	Wed, 17 Jun 2026 14:23:23 GMT
  $epoch	Number of seconds since 00:00 on 1st January, 1970	1781706203

• Variables can be shortened to 3 characters
• Example: %GMTIME{"$day $month, $year - $hour:$min:$sec"}% expands to 17 Jun, 2026 - 14:23:23
• 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"}%
  %HTTP{"User-Agent"}%	Mozilla/5.0 AppleWebKit?/537.36 (KHTML, like Gecko; compatible; ClaudeBot?/1.0; +claudebot@anthropic.com)

• 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: fs.rainysky.org
• Related: REMOTE_ADDR, REMOTE_PORT, REMOTE_USER

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

• Small graphic (commonly 16x16 pixels) used to enhance topics. Specify the name of the graphic.
• A set of 16x16 pixel icons of common attachment types is provided. Specify file type only, file name, or full path name.
• Syntax: %ICON{"name"}% or %ICON{"type"}%
• Graphic samples: arrowbright, bubble, choice-yes, hand
• Filetype samples: bmp, doc, gif, hlp, html, mp3, pdf, ppt, txt, xls, xml, zip
• Example: %ICON{"info"}% expands to
• Related: TWikiPreferences, FileAttachments, TWikiDocGraphics

ICONPATH{"name"} -- url path of small documentation graphic or icon of common attachment types

• See ICON
• Syntax: %ICONPATH{"name"}% or %ICONPATH{"type"}%
• Example: %ICONPATH{"info"}% expands to https://fs.rainysky.org/pub/TWiki/TWikiDocGraphics/info.gif which renders as
• Related: TWikiPreferences, FileAttachments, TWikiDocGraphics

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

• Syntax: %IF{"CONDITION" then="THEN" else="ELSE"}%
• In the example above, if CONDITION evaluates to TRUE, then THEN will be shown; otherwise ELSE will be shown.
• Related: IfStatements has more information on how to write %IF{}% statements
• 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)	on preferences setting
  section="name"	Includes only the specified section, as defined in the included topic by the SECTION 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, SECTION, 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

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"
  sep	separator between items.	"\n" (newline)

• format variables:

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

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

LOGIN -- present a full login link

• Syntax: %LOGIN%
• Expand to: Log In
• 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 jpw@rainysky.org if you have any questions.
  • %MAKETEXT{"Did you want to [[[_1]][reset [_2]'s password]]?" args="TWiki.ResetPassword,%WIKIUSERNAME%"}%
    expands to
    Did you want to reset Main.TWikiGuest's password?
• Notes:
  • that 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 should not use translatable phrases starting with an underscore.

MAINWEB -- name of Main web

• The web containing TWikiUsers, individual user topics and TWikiGroups
• Syntax: %MAINWEB%
• Expands to: Main
• 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%
• Syntax: %NOP{...}%
• Available in template topics only. See TWikiTemplates#HtmlTemplates for details. In normal topic text, simply expands to whatever is in the curly braces (if anything).

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:
  • CommentPlugin (Dakar, 6827): Allows users to quickly post comments to a page without an edit/preview/save cycle.
  • EditTablePlugin (Dakar, 6827): Edit TWiki tables using edit fields, date pickers and drop down boxes
  • ExifMetaDataPlugin (1.010): Displays EXIF data for jpeg images attached to a topic.
  • GuidPlugin: (disabled)
  • HeadlinesPlugin (1.95, 7779): Build news portals that show headline news based on RSS news feeds from news sites.
  • InterwikiPlugin (Dakar, $Rev: 7873$): Link ExternalSite:Page text to external sites based on aliases defined in the %RULESTOPIC% topic
  • PreferencesPlugin (Dakar, 6827): Allows editing of preferences using fields predefined in a form
  • RedirectPlugin (1.000): This plugin allows one to produce TWiki topics that automatically redirect to other TWiki topics or URLs.
  • SlideShowPlugin (Dakar, $Rev: 7873$): Create web based presentations based on topics with headings.
  • SmiliesPlugin (Dakar, 6827): Render smilies as icons, like  :-) for or  :cool: for :cool:
  • SpreadSheetPlugin (Dakar, 6827): Add spreadsheet calculation like "$SUM( $ABOVE() )" to tables located in FS topics.
  • TablePlugin (Dakar, 6850): Control attributes of tables and sorting of table columns
• Related: ACTIVATEDPLUGINS, FAILEDPLUGINS, PLUGINVERSION

PLUGINVERSION -- the version of the TWiki Plugin API

• This is the $TWiki::Plugins::VERSION number, also indicating the version of the Func module
• Syntax: %PLUGINVERSION%
• Expands to: 1.1
• Related: PLUGINVERSION{"name"}, WIKIVERSION

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

• Syntax: %PLUGINVERSION{"name"}%
• Example: %PLUGINVERSION{"InterwikiPlugin"}% expands to $Rev: 7873$
• Related: PLUGINVERSION, WIKIVERSION, ACTIVATEDPLUGINS, FAILEDPLUGINS, PLUGINDESCRIPTIONS

PUBURL -- the base URL of attachments

• Syntax: %PUBURL%
• Expands to: https://fs.rainysky.org/pub
• Example: You can refer to a file attached to another topic with %PUBURL%/%WEB%/OtherTopic/image.gif
• Related: ATTACHURL, PUBURLPATH, SCRIPTURL, FileAttachments

PUBURLPATH -- the base URL path of attachments

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

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

• Syntax: %QUERYSTRING%
• Expands to: rev=36;skin=print.pattern%2Cpattern
• 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{}%.
• Related: URLPARAM

REMOTE_ADDR -- environment variable

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

REMOTE_PORT -- environment variable

• Syntax: %REMOTE_PORT%
• Expands to: 20606
• 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 - 17 Dec 2005 - 13:33 - 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 Main web prefix	Main.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: view
• Related: SCRIPTSUFFIX, SCRIPTURL

SCRIPTSUFFIX -- script suffix

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

SCRIPTURL -- script URL

• Syntax: %SCRIPTURL%
• Expands to: https://fs.rainysky.org/bin
• Example: To get the authenticated version of current topic write "}%L%/viewauth%SCRIPTSUFFIX%/%WEB%/%TOPIC% which expands to /bin/viewauth/TWiki/TWikiVariablesNtoZ
• Syntax: %SCRIPTURL{"script"}%
• Expands to: /bin/script
• Example: To get the authenticated version of current topic write %SCRIPTURL{"viewauth"}%/TWiki/TWikiVariablesNtoZ which expands to /bin/viewauth/TWiki/TWikiVariablesNtoZ
• This second form of SCRIPTURL handles URL rewriting (see TWiki:TWiki.ShorterURLCookbook).
• Related: PUBURL, SCRIPTNAME, SCRIPTSUFFIX, SCRIPTURLPATH

SCRIPTURLPATH -- script URL path

• Syntax: %SCRIPTURLPATH%
• Expands to: /bin
• As SCRIPTURL, but doesn't include the host part of the URL. Of limited use, and not recommended.
• Related: PUBURLPATH, SCRIPTNAME, SCRIPTSUFFIX, SCRIPTURL

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="Main, 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="Main" scope="topic"}%
• Example with format: %SEARCH{"FAQ" scope="topic" nosearch="on" nototal="on" header="| *Topic: * | *Summary: * |" format="| $topic | $summary |"% (displays results in a table with header - details)
• 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

SECTION{"name"} -- marks the start of a named section

• Syntax: %SECTION{"name"}%
• Supported parameters:

  Parameter:	Description:	Default:
  "name"	Name of the section. Must be unique inside a topic.	Mandatory parameter without a default

• Related: INCLUDE, ENDSECTION, STARTINCLUDE, STOPINCLUDE

SERVERTIME -- server time

• Syntax: %SERVERTIME%
• Expands to: 17 Jun 2026 - 08:23
• 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 08:23
• 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: 06dee22077b4fe04427b85616c5e12ff
• 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

• The current topic name with added spaces, for regular expression search of backlinks
• Syntax: %SPACEDTOPIC%
• Expands to: TWiki%20*Variables%20*Nto%20*Z
• Hint: This variable is provided almost exclusively for generating URLs for searching for backlinks to topics
• Related: TOPIC

STARTINCLUDE -- start position of topic text if included

• If present in included topic, start to include text from this location up to the end, or up to the location of the %STOPINCLUDE% variable. A normal view of the topic shows everything exept the %STARTINCLUDE% variable itself. An optional parameter can be used to control whether the content is expanded.
• Syntax: %STARTINCLUDE%
• Syntax: %STARTINCLUDE{param}%
  • If param does not expand to a non-zero integer, then nothing will be included.
• Related: ENDSECTION, INCLUDE, SECTION, 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: ENDSECTION, INCLUDE, SECTION, STARTINCLUDE

TOC -- table of contents of current topic

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

TOC{"Topic"} -- table of contents

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

  Parameter:	Description:	Default:
  "TopicName"	topic name	Current topic
  web="Name"	Name of web	Current web
  depth="2"	Limit depth of headings shown in TOC	6
  title="Some text"	Title to appear at top of TOC	none

• Example: %TOC{depth="2"}%
• Example: %TOC{"TWikiDocumentation" web="TWiki" title="Contents:"}%
• Example: see TWiki:Sandbox.TestTopicInclude
• 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: TWikiVariablesNtoZ, renders as TWikiVariablesNtoZ
• Related: BASETOPIC, INCLUDINGTOPIC, TOPICLIST, WEB

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

• The "format" defines the format of one topic item. It may include variables: The $name variable gets expanded to the topic name; the $web variable gets expanded to the name of the web.
• Syntax: %TOPICLIST{"format" ...}%
• Supported parameters:

  Parameter:	Description:	Default:
  "format"	Format of one line, may include $name and $web variables	"$name"
  format="format"	(Alternative to above)	"$name"
  separator=", "	line separator	"\n" (new line)
  web="Name"	Name of web	Current web

• Example: %TOPICLIST{"   * $web.$name"}% creates a bullet list of all topics
• Example: %TOPICLIST{separator=", "}% creates a comma separated list of all topics
• Example: %TOPICLIST{" <option>$name</option>"}% creates an option list (for drop down menus)
• Related: SEARCH, WEBLIST

TWIKIWEB -- name of TWiki documentation web

• The web containing all documentation and site-wide preference settings for FS
• 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, like a double quote into &#034;. This is needed if text is put into an HTML form field	no encoding
  encode="url"	Encode special characters for URL parameter use, like a double quote into %22	no encoding
  multiple="on" multiple="[[$item]]"	If set, gets all selected elements of a <select multiple="multiple"> tag. A format can be specified, with $item indicating the element, e.g. multiple="Option: $item"	first element
  separator=", "	Separator between multiple selections. Only relevant if multiple is specified	"\n" (new line)

• Example: %URLPARAM{"skin"}% returns print for a .../view/TWiki/TWikiVariablesNtoZ?skin=print URL.
• 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: SEARCH, FormattedSearch, QUERYSTRING

USERNAME -- your login username

• TWiki makes names available in three formats: USERNAME like jsmith, WIKINAME like JohnSmith and WIKIUSERNAME like Main.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, WIKINAME, WIKIUSERNAME, TWikiUserAuthentication

USERLANGUAGE -- 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:
  • Is the LANGUAGE preference is set, it's used as user's language instead of any language detected from the browser.
  • Avoid to define it LANGUAGE at a non per-user way, so each user can choose his/her preferred language.
• Related: LANGUAGES

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

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

WEB -- name of current web

• 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 variable. (to support HierarchicalWebs?, there are 2 added variables $webindent and $indentedname)	"$name"
  format="format"	(Alternative to above)	"$name"
  separator=", "	line separator	"\n" (new line)
  webs="public"	comma sep list of Web, public expands to all non-hidden	"public"
  marker="selected"	Text for $marker where item matches selection, otherwise equals ""	"selected"
  selection="%WEB%"	Current value to be selected in list	section="%WEB%"

• Example: %WEBLIST{"   * [[$name.WebHome]]"}% creates a bullet list of all webs.
• Example: %WEBLIST{"<option $marker value=$qname>$name</option>" webs="Trash,public" selection="TWiki" separator=" "}% Dropdown of all public Webs + Trash Web, current Web highlighted.
• Related: TOPICLIST, SEARCH

WEBPREFSTOPIC -- name of web preferences topic

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

WIKIHOMEURL -- site home URL

• Note: DEPRECATED, use %WIKILOGOURL% defined in WebPreferences instead. This variables value is defined in lib/TWiki.cfg::$wikiHomeUrl which is marked deprecated. Will be removed in future versions.

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, 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: FS
• Related: WIKIHOMEURL, WIKIVERSION

WIKIUSERNAME -- your Wiki username with web prefix

• Your %WIKINAME% with Main web prefix, useful to point to your FS home page
• Syntax: %WIKIUSERNAME%
• Expands to: Main.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, USERNAME, WIKINAME

WIKIUSERSTOPIC -- name of topic listing all registers users

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

WIKIVERSION -- the version of the installed TWiki engine

• Syntax: %WIKIVERSION%
• Expands to: Wed, 14 Dec 2005 build 7851
• Related: PLUGINVERSION, WIKITOOLNAME

TWiki Meta Data

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

Overview

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

Meta Data Syntax

• Format is the same as in TWikiVariables, except all fields have a key.
  • %META:<type>{key1="value1" key2="value2" ...}%

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

• Each meta variable is on one line.

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

Example of Format

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

Meta Data Specifications

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

META:TOPICINFO

META:TOPICMOVED

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

%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%

Notes:

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

META:TOPICPARENT

META:FILEATTACHMENT

Extra fields that are added if an attachment is moved:

META:FORM

META:FIELD

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

Recommended Sequence

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

• form fields remain in the order they are defined
• the diff function output appears in a logical order

The recommended sequence is:

• META:TOPICINFO
• META:TOPICPARENT (optional)
• text of topic
• META:TOPICMOVED (optional)
• META:FILEATTACHMENT (0 or more entries)
• META:FORM (optional)
• META:FIELD (0 or more entries; FORM required)

Viewing Meta Data in Page Source

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

Rendering Meta Data

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

You can render form fields in topic text by using the FORMFIELD variable. Example:
%FORMFIELD{"TopicClassification"}%
For details, see TWikiVariables#VarFORMFIELD.

Current support covers:

Known Issues

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

Related Topics: DeveloperDocumentationCategory, UserDocumentationCategory

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="Main.$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 text area fields that value may also contain commas. Checkbox fields cannot be initialized through the form template.
• 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 one wants to use a name other than the topic name 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 asteriks 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="%SCRIPTURL{"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{"Main.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.

TWiki Plugins

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

Overview

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

• add virtually unlimited features while keeping the main TWiki code compact and efficient;
• heavily customize an installation and still do clean updates to new versions of TWiki;
• rapidly develop new TWiki functions in Perl using the Plugin API.

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

TWiki plugins are developed and contributed by interested members of the community. Plugins are provided on an 'as is' basis; they are not a part of TWiki, but are independently developed and maintained.

Installing Plugins

Each TWiki Plugin comes with its own documentation: Step-by-step installation instructions, a detailed description of any special requirements, version details, and a working example for testing. Many plugins have an install script that automates these steps for you.

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

Each Plugin has a standard release topic, located in the TWiki:Plugins web at TWiki.org. There's usually a number of other related topics, such as a developers page, and an appraisal page.

On-Site Pretesting

The recommended approach to testing new Plugins before making them public is to create a second local TWiki installation, and test the plugin there. You can allow selected users access to the test area. Once you are satisifed that it won't compromise your main installation, you can install it there as well.

InstalledPlugins shows which Plugins are: 1) installed, 2) loading properly and 3) what TWiki:Codev.PluginHandlers they invoke. Any failures are shown in the Errors section. The %FAILEDPLUGINS% variable can be used to debug failures. You may also want to check your webserver error log and the various TWiki log files.

Some Notes on Plugin Performance

The performance of the system depends to some extent on the number of Plugins installed and on the Plugin implementation. Some Plugins impose no measurable performance decrease, some do. For example, a Plugin might use many Perl libraries that need to be initialized with each page view (unless you run mod_perl). You can only really tell the performance impact by installing the Plugin and by measuring the performance with and without the new Plugin. Use the TWiki:Plugins.PluginBenchmarkAddOn, or test manually with the Apache ab utility. Example on Unix:
time wget -qO /dev/null /bin/view/TWiki/AbcPlugin

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

Managing Installed Plugins

Some Plugins require additional settings or offer extra options that you have to select. Also, you may want to make a Plugin available only in certain webs, or temporarily disable it. And may want to list all available Plugins in certain topics. You can handle all of these management tasks with simple procedures.

Enabling Plugins

Plugins can be enabled and disabled with the configure script. An installed Plugin needs to be enabled before it can be used.

Plugin Evaluation Order

By default, TWiki executes Plugins in alphabetical oder on Plugin name. It is possible to change the order, for example to evaluate a database variables before the speadsheet CALCs. This can be done with the configure script.

Plugin Specific Settings

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

1. One line description, used to form the bullets describing the Plugins in the TextFormattingRules topic:
   • Set SHORTDESCRIPTION = Create dynamic foo bar reports
2. Debug Plugin, output can be seen in data/debug.txt. Set to 0=off or 1=on:
   • Set DEBUG = 0

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

Listing Active Plugins

Plugin status variables let you list all active Plugins wherever needed.

%ACTIVATEDPLUGINS%

%PLUGINDESCRIPTIONS%

• CommentPlugin (Dakar, 6827): Allows users to quickly post comments to a page without an edit/preview/save cycle.
• EditTablePlugin (Dakar, 6827): Edit TWiki tables using edit fields, date pickers and drop down boxes
• ExifMetaDataPlugin (1.010): Displays EXIF data for jpeg images attached to a topic.
• GuidPlugin: (disabled)
• HeadlinesPlugin (1.95, 7779): Build news portals that show headline news based on RSS news feeds from news sites.
• InterwikiPlugin (Dakar, $Rev: 7873$): Link ExternalSite:Page text to external sites based on aliases defined in the %RULESTOPIC% topic
• PreferencesPlugin (Dakar, 6827): Allows editing of preferences using fields predefined in a form
• RedirectPlugin (1.000): This plugin allows one to produce TWiki topics that automatically redirect to other TWiki topics or URLs.
• SlideShowPlugin (Dakar, $Rev: 7873$): Create web based presentations based on topics with headings.
• SmiliesPlugin (Dakar, 6827): Render smilies as icons, like  :-) for or  :cool: for :cool:
• SpreadSheetPlugin (Dakar, 6827): Add spreadsheet calculation like "$SUM( $ABOVE() )" to tables located in FS topics.
• TablePlugin (Dakar, 6850): Control attributes of tables and sorting of table columns

%FAILEDPLUGINS%

TWiki::Plugins::GuidPlugin could not be loaded.  Errors were: 
Can't locate loadable object for module Data::UUID in @INC (@INC contains: /home/rainysky/public_html/fs/lib/CPAN/lib//arch/ /home/rainysky/public_html/fs/lib/CPAN/lib//5.16.3/x86_64-linux-thread-multi/ /home/rainysky/public_html/fs/lib/CPAN/lib//5.16.3/ /home/rainysky/public_html/fs/lib/CPAN/lib// /home/rainysky/public_html/fs/lib . /usr/local/lib64/perl5 /usr/local/share/perl5 /usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl /usr/lib64/perl5 /usr/share/perl5) at /home/rainysky/public_html/fs/lib/TWiki/Plugins/GuidPlugin.pm line 60.
Compilation failed in require at /home/rainysky/public_html/fs/lib/TWiki/Plugins/GuidPlugin.pm line 60.
BEGIN failed--compilation aborted at /home/rainysky/public_html/fs/lib/TWiki/Plugins/GuidPlugin.pm line 60.
Compilation failed in require at (eval 37) line 1.
BEGIN failed--compilation aborted at (eval 37) line 1.

----

The TWiki Plugin API

The Application Programming Interface (API) for TWiki Plugins provides the specifications for hooking into the core TWiki code from your external Perl Plugin module.

Available Core Functions

The TWikiFuncDotPm module (lib/TWiki/Func.pm) describes all the interfaces available to Plugins. Plugins should only use the interfaces described in this module.

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

Predefined Hooks

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

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

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

Hints on Writing Fast Plugins

• Delay initialization as late as possible. For example, if your plugin is a simple syntax processor, you might delay loading extra Perl modules until you actually see the syntax in the text.
• For example, use an eval block like this:
  eval { require IPC::Run }
return "<font color=\"red\">SamplePlugin: Can't load required modules ($@)</font>" if $@;
• You can use a flag to avoid running the initialization twice
• The TWiki:Plugins.PluginBenchmarkAddOn comes in handy to measure and fine-tune the performance of your Plugin

Plugin Version Detection

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

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

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

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

Security

• Badly written plugins can open huge security holes in TWiki. This is especially true if care isn't taken to prevent execution of arbitrary commands on the server.
• Don't allow sensitive configuration data to be edited by users. it is better to add sensitive configuration options to the TWiki::cfg hash than adding it as preferences in the plugin topic
  • See TWiki:Plugins.MailInContrib for an example of this
  • TWiki:Plugins.BuildContrib can help you with this
• Always use the TWiki::Sandbox to execute commands.
• Always audit the plugins you install, and make sure you are happy with the level of security provided. While every effort is made to monitor plugin authors activities, at the end of the day they are uncontrolled user contributions.

Creating Plugins

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

Anatomy of a Plugin

A basic TWiki Plugin consists of two elements:

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

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

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

Creating the Perl Module

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

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

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

Measuring and Improving the Plugin Performance

A high quality Plugin performs well. You can use the TWiki:Plugins.PluginBenchmarkAddOn to measure your TWiki:Plugins.PluginBenchmarks. The data is needed as part of the Documentation Topic.

See also Hints on Writing Fast Plugins.

Writing the Documentation Topic

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

1. Copy the Plugin topic template from TWiki.org. To copy the text, go to TWiki:Plugins/PluginPackage and:
   • enter the Plugin name in the "How to Create a Plugin" section
   • click Create
   • select all in the Edit box & copy
   • Cancel the edit
   • go back to your site to the TWiki web
   • In the GoBox enter your Plugin name, for example MyFirstPlugin, press enter and create the new topic
   • paste & save new Plugin topic on your site
2. Customize your Plugin topic.
   • Important: In case you plan to publish your Plugin on TWiki.org, use Interwiki names for author names and links to TWiki.org topics, such as TWiki:Main/TWikiGuest. This is important because links should work properly in a Plugin topic installed on any TWiki, not just on TWiki.org.
3. Document the performance data you gathered while measuring the performance
4. Save your topic, for use in packaging and publishing your Plugin.

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

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

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

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

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

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

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

Packaging for Distribution

The TWiki:Plugins.BuildContrib is a powerful build environment that is used by the TWiki project to build TWiki itself, as well as many of the plugins. You don't have to use it, but it is highly recommended!

If you don't want (or can't) use the BuildContrib, then a minimum Plugin release consists of a Perl module with a WikiName that ends in Plugin, ex: MyFirstPlugin.pm, and a documentation page with the same name(MyFirstPlugin.txt).

1. Distribute the Plugin files in a directory structure that mirrors TWiki. If your Plugin uses additional files, include them all:
   • lib/TWiki/Plugins/MyFirstPlugin.pm
   • data/TWiki/MyFirstPlugin.txt
   • pub/TWiki/MyFirstPlugin/uparrow.gif [a required graphic]
2. Create a zip archive with the Plugin name (MyFirstPlugin.zip) and add the entire directory structure from Step 1. The archive should look like this:
   • lib/TWiki/Plugins/MyFirstPlugin.pm
   • data/TWiki/MyFirstPlugin.txt
   • pub/TWiki/MyFirstPlugin/uparrow.gif

Publishing for Public Use

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

Publish your plugin by following these steps:

1. Post the Plugin documentation topic in the TWiki:Plugins/PluginPackage:
   • enter the Plugin name in the "How to Create a Plugin" section, for example MyFirstPlugin
   • paste in the topic text from Writing the Documentation Topic and save
2. Attach the distribution zip file to the topic, ex: MyFirstPlugin.zip
3. Link from the doc page to a new, blank page named after the Plugin, and ending in Dev, ex: MyFirstPluginDev. This is the discussion page for future development. (User support for Plugins is handled in TWiki:Support.)
4. Put the Plugin into the SVN repository, see TWiki:Plugins/ReadmeFirst (optional)

Once you have done the above steps once, you can use the BuildContrib to upload updates to your plugin.

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

Recommended Storage of Plugin Specific Data

Plugins sometimes need to store data. This can be Plugin internal data such as cache data, or data generated for browser consumption such as images. Plugins should store data using TWikiFuncDotPm functions that support saving and loading of topics and attachments.

Plugin Internal Data

You can create a Plugin "work area" using the TWiki::Func::getWorkArea() function, which gives you a persistant directory where you can store data files. By default they will not be web accessible. The directory is guaranteed to exist, and to be writable by the webserver user. For convenience, TWiki::Func::storeFile() and TWiki::Func::readFile() are provided to persistently store and retrieve simple data in this area.

Web Accessible Data

Topic specific data such as generated images can be stored in the topics attachment area, which is web accessible. Use the TWiki::Func::saveAttachment() function to store the data.

Recommendation for file name:

• Prefix the filename with an underscore (the leading underscore avoids a nameclash with files attached to the same topic)
• Identify where the attachment originated from, typically by including the Plugin name in the file name
• Use only alphanumeric characters, underscores, dashes and periods to avoid platform dependency issues and URL issues
• Example: _FooBarPlugin_img123.gif

Web specific data can be stored in the Plugin's attachment area, which is web accessible. Use the TWiki::Func::saveAttachment() function to store the data.

Recommendation for file names in Plugin attachment area:

• Prefix the filename with an underscore
• Include the name of the web in the filename
• Use only alphanumeric characters, underscores, dashes and periods to avoid platform dependency issues and URL issues
• Example: _Main_roundedge-ul.gif

Handling deprecated functions

From time-to-time, the TWiki developers will add new functions to the interface (either to TWikiFuncDotPm, or new handlers). Sometimes these improvements mean that old functions have to be deprecated to keep the code manageable.

FIXME: The following is not KISS

When this happens, the deprecated functions will be supported in the interface for at least one more TWiki release (i.e. one more after the one they are first deprecated in). When a plugin uses (or defines) the deprecated function, a warning will be generated in the TWiki warnings log. Admins who see these warnings in their logs should check TWiki.org and if necessary, contact the plugin author, for an updated version of the plugin.

Updated plugins may still need to define deprecated handlers for compatibility with old TWiki versions. In this case, the plugin package that defines old handlers can set a flag to prevent the warnings from being issued. This is done by defining a global hash that maps from the handler name to the TWiki::Plugins version in which the handler was first deprecated. For example, if we need to define the endRenderingHandler for compatibility with TWiki::Plugins versions before 1.1, we would add this to the plugin:

package TWiki::Plugins::SinkPlugin;
use vars qw( %TWikiCompatibility );
$TWikiCompatibility{endRenderingHandler} = 1.1;

There is no way to prevent warnings from being issued when deprecated functions in the TWikiFuncDotPm interface are called. In this case, plugins authors should be encouraged recode their plugins as described in the TWikiFuncDotPm documentation of the deprecated function.

Related Topics: DeveloperDocumentationCategory, AdminDocumentationCategory

Warning: Can't find topic MonitoringSiteActivity

Managing Topics

Browser-based rename, move, and delete for individual topics

Overview

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

How to Rename/Move/Delete a Topic

1. Click on [More] (bottom right of page) on the topic to be changed, then, in the new screen, on [Rename/move]. You can now rename and/or move/delete in one operation:
2. Move/Delete: Select the target web if other than the current web - choose Trash to delete a topic.
3. Rename: Enter the new topic name - default is current name
   NOTE: You'll be warned if any of the topics to be affected are locked (being edited), or if there is a name conflict.
4. Prevent updates by unchecking individual items on the list of referring links - these topics will NOT to be updated with the new name (by default, all referring links will be updated).
5. Click on [Rename/Move]: the topic will be renamed and links to the topic updated as requested.
   • If any of the referring pages are locked then they will be listed: you can correct these later by again pressing [Rename/Move].
   • There is a Put back feature that allows you to undo a Rename/Move/Delete - an instruction line and undo link will appear at the bottom of the modified topic. This allows you to revert from the last modification only.

Deleted Topics: How to Clear the Trash

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

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

• This can only be done from on the server, not through the browser.
  • Since simple FTP access to the Trash directory is all that's required for maintenance, it's possible to grant Trash admin privileges to multiple users, while strictly limiting server access.

Redirecting from an Old Topic

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

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

How Rename/Move Works

1. %SEARCH%, with a special template, finds and displays all occurrences of the topic name in other topics, site-wide. These referring links are by default automatically changed to the new topic and/or web name. This includes relevant TWikiMetaData definitions.
   • User can omit one or more topics from the update list by unchecking them.
   • <pre> and <verbatim> are honoured - no changes are made to text within these areas.
2. The topic is moved (if locks allow).
3. References are changed (locks and permissions permitting).
4. Any referring topics that can't be changed due to locks are listed - user can take note and change them at another time.

How Referring Topics Are Found

First, matching topics in the current web are listed - matches are to topic. Next, all webs (including the current one) are listed that match web.topic. All webs will be searched during rename, even if NOSEARCHALL is defined on a web, though access permissions will of course be honoured.

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

Effect of User Access Settings

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

Special Considerations

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

• When referring links are updated, the modified topics appear in WebChanges, creating the impression that editorial changes were made. This can undermine the usefulness of WebChanges.
• Due to current limitations, fairly heavy use of Rename/Move/Delete functions can lead to an accumulation of minor technical problems (ex: broken links) and usability issues (ex: user confusion). If Rename... is used heavily, these negatives will obviously increase, in number and effect.

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

Known Issues

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

The following shows some limitations of square bracket processing.

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

Related Topics: UserDocumentationCategory, AdminDocumentationCategory

Managing Webs

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

Overview

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

Choose Web Template

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

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

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

Adding a New Web

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

Name of new web:		The name must start with an upper case letter, followed by upper or lower case letters or numbers. Specify a short name to avoid long URLs.
Based on web:	_default Main Sandbox TWiki	Select a TemplateWeb
Web color:		Enter a StandardColors code for the web
Description:	Enter a short description of the web. Write Web.TopicName instead of just TopicName if you include links. This will list the web in the SiteMap (leave field empty if you prefer not to update the directory.)
Use to...	Continue the sentence describing the intended use. This is also for the SiteMap
Exclude web from "search all":	No   Yes	Specify if you want to exclude the web from a "search all webs" search. Note that the SiteMap will not list the web if you select Yes.

Notes:

• Attachments will NOT get copied over along with their topics
• While creating the new web, TWiki will update the following variables in the WebPreferences: WEBBGCOLOR, SITEMAPLIST, SITEMAPWHAT, SITEMAPUSETO and NOSEARCHALL. These variables are used to dynamically generate the SiteMap
• TWiki does not edit the TWiki.TWikiPreferences to update the WIKIWEBLIST. This must be done by hand

Renaming or Deleting a Web

Rename a web via the Tools section in each web's WebPreferences topic. You may delete a web by moving it into a Trash web.

Permissions

You may only rename a web if you have permissions to rename all the topics within that web, including any topics in that web's subwebs. You will also need permissions to update any topics containing references to that web.

Edit Conflicts

If anyone is editing a topic which requires updating, or which lives in the web being renamed, a second confirmation screen will come up which will indicate which topics are still locked for edit. You may continue to hit the refresh button until an edit lease is obtained for each topic which requires updating (the "Refresh" button will change to "Submit"), or hit "Cancel", which will cancel your edit lease on all affected topics.

Renaming the webs in the distribution

If you plan to rename the Main web, remember that TWiki stores user and group topics in %MAINWEB%, which by default is Main (this is assigned in the site configuration). That means that every WikiName signature - Main.SomeUserName - points to it and would need updating (unless the variable, %MAINWEB%.SomeUserName, is used throughout). This potentially large change can be performed automatically with the renameweb function mentioned above, in the Main.WebPreferences topic.

If you want to rename the TWiki web, remember it is referred to by %TWIKIWEB% which is also defined by a configuration setting.

Hierarchical Webs

Hierarchical web support is enabled by turning on the {EnableHierarchicalWebs} setting in configure. Without this setting, TWiki will only allow a single level of hierarchy (webs). If you set this, you can use multiple levels, like a directory tree, i.e. webs within webs.

Note: You might not need hierarchical webs. TWiki topics already have a parent/child relationship within a web, which is shown in the breadcrumb. Try to keep the number of webs to a minimum in order to keep search and cross-referencing simple.

You can create hierarchical webs via the Adding a New Web form above, by using a slash- or dot-separated path name which is based on an existing web name in the Name of new web: field.

Example:

To create a subweb named Bar inside a web named Foo, use Foo/Bar or Foo.Bar as the new web name in the form above.

Subweb Preferences are Inherited

The preferences of a subweb are inherited from the parent web and overridden locally. Preferences are ultimately inherited from the TWiki.TWikiPreferences topic.

Example Preference Inheritance for Sandbox/TestWeb/SubWeb.SubWebTopic topic:

1. TWiki.TWikiPreferences site-wide preferences
2. Sandbox.WebPreferences inherits from and overrides settings in TWiki.TWikiPreferences
3. Sandbox/TestWeb.WebPreferences inherits from and overrides settings in Sandbox.WebPreferences
4. Sandbox/TestWeb/SubWeb.WebPreferences inherits from and overrides settings in Sandbox/TestWeb.WebPreferences
5. Sandbox/TestWeb/SubWeb.SubWebTopic inherits from and overrides settings in Sandbox/TestWeb/SubWeb.WebPreferences

Navigation

The Pattern skin (default) indicates Subwebs by indententing them in the sidebar relative to their level in the hierarchy.

Related Topics: AdminDocumentationCategory, AdminToolsCategory

Warning: Can't find topic AppendixFileSystem