TWiki > TWiki > TWikiDocumentation (r1.16)	TWiki webs: Main | TWiki | Know | Sandbox
	TWiki . { Welcome | Register | Changes | Topics | Index | Search | Go }

Documentation of the TWiki Implementation (version 01 Feb 2003)

• (1) Implementation Notes
• (2) Installation Notes
• (3) Upgrading Earlier Versions of TWiki
• (4) TWiki Authentication
• (5) Wiki Username vs. Login Username
• (6) TWiki Access Control
• (7) Wiki Templates
• (8) Wiki Variables
• (9) Notification of Changes by Email
• (10) TWiki Category Table
• (11) TWiki Administration

Related Topics: TWikiWeb?, TWikiHistory, TWikiPlannedFeatures, TWikiEnhancementRequests.

TWiki Username vs. Login Username

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

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

• Login username: When you login to the intranet, you use your existing login username, for example pthoeny. This name is normally passed to TWiki by the REMOTE_USER environment variable. TWiki uses this name internally to log topic changes. Login usernames are maintained by your system administrator.
• TWiki username: This is your name in WikiNotation, for example PeterThoeny, recorded when you register in TWikiRegistration; doing so also generates your personal home page in the Main web of your TWiki site.

TWiki can map the intranet username to the Wiki username automatically, provided that the Login username and Wiki username pair has been entered in the TWikiUsers topic. This happens automatically when you register.

NOTE: To correctly enter a WikiName - your own or someone else's - be sure to specify the Main web in front of the Wiki username: write Main.WikiUsername or %MAINWEB%.WikiUsername. This assures that the name will be linked automatically to the Main web, where user home pages are stored, even if the text is entered in a different web.

-- PeterThoeny - 30 Jan 2003

TWiki Access Control

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

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

An Important Control Consideration

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

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

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

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

As a collaboration guideline:

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

Users and Groups

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

Managing Users

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

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

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

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

Managing Groups

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

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

Restricting Write Access

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

Deny Editing by Topic

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

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

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

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

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

Deny Editing by Web

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

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

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

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

Restricting Rename Access

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

Deny Renaming by Topic

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

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

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

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

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

Deny Renaming by Web

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

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

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

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

Restricting Read Access

You can define who is allowed to see a web.

Deny Viewing by Topic

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

Deny Viewing by Web

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

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

Obfuscate Webs

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

• Set NOSEARCHALL = on

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

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

Authenticate all Webs and Restrict Selected Webs

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

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

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

Authenticate and Restricting Selected Webs Only

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

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

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

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

Hiding Control Settings

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

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

The SuperAdminGroup

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

• Set the $superAdminGroup variable in lib/TWiki.cfg to the name of a group of Users who are always allowed to edit/view topics.

$superAdminGroup = "TWikiAdminGroup";

• The default setting is not to have superusers.

-- PeterThoeny - 04 May 2002
-- MikeMannix - 12 May 2002

TWiki Templates

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

Overview

The new modular template system offers flexible, easy control over the layout of all TWiki pages. The master template approach groups parts that are shared by several templates - like headers and footers - in a common file. Special variables allow individual layouts to include parts from a master template - variables are mixed with regular HTML markup for template-specific content. Templates are used to define page layout, and also to supply default content for new pages.

Major changes from the previous template system

Where the old templates were each complete HTML documents, the new templates are defined using variables to include template parts from a master file. You can now change one instance of a common element to update all occurrences; previously, every affected template had to be updated. This simplifies the conversion of templates into XHTML format, and provides a more versatile solution for templates and for TWikiSkins. The new system:

• separates a set of common template parts into a base template that is included by all of the related templates;
• defines common variables, like a standard separator (ex: "|"), in the base template;
• defines variable text in the individual templates and passes it back to the base template.

How Template Variables Work

• Special template directives (or preprocessor commands) are embedded in normal templates.
• All template preprocessing is done in &TWiki::Store::readTemplate() so that the caller simply gets an expanded template file (the same as before).
• Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
• Directives:
  • %TMPL:INCLUDE{"file"}%: Includes a template file. The template directory of the current web is searched first, then the templates root (twiki/templates).
  • %TMPL:DEF{"var"}%: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
  • %TMPL:END%: Ends variable definition.
  • %TMPL:P{"var"}%: Prints a previously defined variable.
• Variables live in a global name space: there is no parameter passing.
• 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 topic text.

Types of Template

There are three types of template:

• Master Template: Stores common parts; included by other templates
• HTML Page Templates: Defines the layout of TWiki pages
• Template Topics: Defines default text when you create a new topic

Master Templates

Common parts, appearing in two or more templates, can be defined in a master template and then shared by others: twiki.tmpl is the default master template.

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

TWiki uses HTML template files for 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.

Templates are in the twiki/templates directory. As an example, twiki/templates/view.tmpl is the template file for the twiki/bin/view script. Templates can be overloaded by individual webs. The following search order applies:

1. twiki/templates/$webName/$scriptName.tmpl
2. twiki/templates/$scriptName.tmpl
   • $webName is the name of the web (ex: Main)
   • $scriptName is the script (ex: view).

NOTE: TWikiSkins can be defined to overload the standard templates.

Special variables are used in templates, especially in view, to display meta data.

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.
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%	Current date, e.g. 02 Feb 2025
%WIKIUSERNAME%	User name, e.g. Main.TWikiGuest
%URLPARAM{"name"}%	Value of a named URL parameter
%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{ ... }%	A no-operation text that gets removed. Useful to write-protect an edit template topic, but not the topics based this template topic. See notes below. Example: %NOP{    * Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup }%

Notes:

• Unlike other variables, %NOP{ ... }% can span multiple lines.
• The scan for the closing }% pattern is "non-greedy", that is, it stops at the first occurance. That means, you need to escape variables with parameters located inside %NOP{ ... }%: Insert a %NOP% between } and %. Silly 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="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%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="onlywikiname" value="on" />
     <input type="submit" value="Create" />
     (date format is <nop>YYYYxMMxDD)
</form>

The onlywikiname parameter enforces WikiWords for topic names.

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%

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%SCRIPTSUFFIX%/%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.

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

Sample screen shot of oopstest.tmpl

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

Known Issues

• A drawback of referring to a master template is that you can only test a template from within TWiki, where the include variables are resolved. In the previous system, each template was a structurally complete HTML document with a .tmpl filename extension - it contained unresolved %VARIABLES%, but could still be previewed directly in a browser.

-- PeterThoeny - 01 Feb 2003
-- MikeMannix - 14 Sep 2001
-- TWiki:Main/DavidLeBlanc - 11 Mar 2002

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 opened. When a topic is rendered for viewing, VARIABLES are replaced by data, either user-entered, or info automatically generated by TWiki (like the date, or the current username). There are predefined variables, and Preference variables that you configure. You can also define custom variables, with new names and values.

Predefined Variables

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

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

This version of TWiki - 01 Feb 2003 - expands the following variables (enclosed in % percent signs):

Variable:	Expanded to:
%WIKIHOMEURL%	The base script URL of TWiki, is the link of the Home icon in the upper left corner, is http://your.domain.com/twiki
%SCRIPTURL%	The script URL of TWiki, is http://qtella.sourceforge.net/cgi-bin
%SCRIPTURLPATH%	The path of the script URL of TWiki, is /cgi-bin
%SCRIPTSUFFIX%	The script suffix, ex: .pl, .cgi is
%PUBURL%	The public URL of TWiki, is http://qtella.sourceforge.net/twiki/pub Example: You can refer to a file attached to another topic as %PUBURL%/%WEB%/OtherTopic/image.gif
%PUBURLPATH%	The path of the public URL of TWiki, is /twiki/pub
%ATTACHURL%	The attachment URL of the current topic, is http://qtella.sourceforge.net/twiki/pub/TWiki/TWikiVariables Example: If you attach a file you can refer to it as %ATTACHURL%/image.gif
%ATTACHURLPATH%	The path of the attachment URL of the current topic, is /twiki/pub/TWiki/TWikiVariables
%URLPARAM{"name"}%	Returns the value of a URL parameter. Note that there is a low risk that this variable could be misused for cross-scripting. Ex: %URLPARAM{"skin"}% returns print for a .../view/TWiki/TWikiVariables?skin=print URL. Is
%URLENCODE{"string"}%	Encodes a string for use as a URL parameter. Ex: %URLENCODE{"spaced name"}% returns spaced%20name
%WIKITOOLNAME%	The name of your TWiki site - TWiki
%WIKIVERSION%	Your current TWiki version - 01 Feb 2003
%USERNAME%	Your login username - guest
%WIKINAME%	Your Wiki username. Same as %USERNAME% if not defined in the TWikiUsers topic. Is TWikiGuest
%WIKIUSERNAME%	Your %WIKINAME% including the Main web name - always use full signatures - Main.TWikiGuest
%MAINWEB%	The web containing TWikiUsers, OfficeLocations and TWikiGroups is Main
%TWIKIWEB%	The web containing all documentation and site-wide preference settings for TWiki - TWiki
%WEB%	The current web is TWiki
%BASEWEB%	The web name where the includes started, e.g. the web of the first topic of nested includes. Same as %WEB% in case there is no include.
%INCLUDINGWEB%	The web name of the topic that includes the current topic - same as %WEB% if there is no INCLUDE.
%HOMETOPIC%	The home topic in each web - WebHome
%NOTIFYTOPIC%	The notify topic in each web - WebNotify
%WIKIUSERSTOPIC%	The index topic of all registered users - TWikiUsers
%WIKIPREFSTOPIC%	The site-wide preferences topic - TWikiPreferences
%WEBPREFSTOPIC%	The local web preferences topic in each web - WebPreferences
%STATISTICSTOPIC%	The web statistics topic WebStatistics
%TOPIC%	The current topic name - TWikiVariables
%BASETOPIC%	The name of the topic where a single or nested INCLUDE started - same as %TOPIC% if there is no INCLUDE.
%INCLUDINGTOPIC%	The name of the topic that includes the current topic. Same as %TOPIC% in case there is no include.
%SPACEDTOPIC%	The current topic name with added spaces, for regular expression search of Ref-By, is TWiki%20*Variables
%TOPICLIST{"format"}%	Topic index of a web. The "format" defines the format of one topic item. It may include variables: The $name variable gets expanded to the topic name; the $web variable gets expanded to the name of the web. Parameters are format, separator and web: Parameter: Description: Default: "format" Format of one line, may include $name and $web variables "$name" format="format" (Alternative to above) "$name" separator=", " line separator "\n" (new line) web="Name" Name of web Current web Examples: %TOPICLIST{"   * $web.$name"}% creates a bullet list of all topics. %TOPICLIST{separator=", "}% creates a comma separated list of all topics. %TOPICLIST{" <option>$name</option>"}% creates an option list (for drop down menus).
%WEBLIST{"format"}%	Web index, ex: list of all webs. Hidden webs are excluded, e.g. webs with a NOSEARCHALL=on preference variable. The "format" defines the format of one web item. The $name variable gets expanded to the name of the web, $qname gets expanded to double quoted name, $marker to marker where web matches selection. Parameters are format, separator and web: Parameter: Description: Default: "format" Format of one line, may include $name variable "$name" format="format" (Alternative to above) "$name" separator=", " line separator "\n" (new line) webs="public" comma sep list of Web, public expands to all non-hidden "public" marker="selected" Text for $marker where item matches selection, otherwise equals "" "selected" selection="%WEB%" Current value to be selected in list section="%WEB%" Examples: %WEBLIST{"   * [[$name.WebHome]]"}% creates a bullet list of all webs. %WEBLIST{"<option $marker value=$qname>$name</option>" webs="Trash,public" selection="TWiki" separator=" "}% Dropdown of all public Webs + Trash Web, current Web highlighted.
%GMTIME%	GM time, is Sun Feb 2 08:35:55 2025
%GMTIME{"format"}%	Formatted GM time based on time variables. Variable: Unit: Example $seconds seconds 59 $minutes minutes 59 $hours hours 23 $day day of month 31 $month month in ISO format Dec $mo 2 digit month 12 $year 4 digit year 1999 $ye 2 digit year 99 Variables can be shortened to 3 characters. Example: %GMTIME{"$day $month, $year - $hour:$min:$sec"}% is 02 Feb, 2025 - 08:35:55
%SERVERTIME%	Server time, is Sun Feb 2 08:35:55 2025
%SERVERTIME{"format"}%	Formatted server time. Example: %SERVERTIME{"$hou:$min"}% is 08:35
%HTTP_HOST%	HTTP_HOST environment variable, is qtella.sourceforge.net
%REMOTE_ADDR%	REMOTE_ADDR environment variable, is 127.0.0.1
%REMOTE_PORT%	REMOTE_PORT environment variable, is 45956
%REMOTE_USER%	REMOTE_USER environment variable, is
%INCLUDE{"page" ...}%	Server side include to IncludeTopicsAndWebPages: 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/"}%   pattern="..." A RegularExpression pattern to include a subset of a topic or page none rev="1.2" Include a previous topic revision; N/A for URLs top revision
%STARTINCLUDE%	If present in included topic, start to include text from this location up to the end, or up to the location of the %STOPINCLUDE% variable. A normal view of the topic shows everyting exept the %STARTINCLUDE% variable itself.
%STOPINCLUDE%	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.
%TOC%	Table of Contents of current topic.
%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. Parameters are topic name, web and depth: 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 Examples: %TOC{depth="2"}%, %TOC{"TWikiDocumentation" web="TWiki"}%
%SEARCH{"text" ...}%	Inline search, shows a search result embedded in a topic. Parameters are the search term, web, scope, order and many more: [1] Parameter: Description: Default: "text" Search term. Is a regular expression or literal, depending on the regex parameter. For regular expressions ";" is used to mean and e.g. "search;agrep" will find all topic containing search and agrep. required search="text" (Alternative to above) N/A web="Name" web="Main Know" web="all" Wiki web to search: A web, a list of webs separated by whitespace, or all webs. [2] Current web scope="topic" scope="text" Search topic name (title) or in the text (body) of the topic Topic text (body) order="topic" order="modified" order="editby" order=  "formfield(name)" Sort the results of search by the topic names, last modified time, last editor, or named field of TWikiForms Sort by topic name limit="all" limit="16" Limit the number of results returned All results regex="on" RegularExpression search; also enables ";" as and Literal search reverse="on" Reverse the direction of the search Ascending search casesensitive="on" Case sensitive search Ignore case nosummary="on" Show topic title only Show topic summary bookview="on" BookView search, e.g. show complete topic text Show topic summary nosearch="on" Suppress search string Show search string noheader="on" Suppress search header Topics: Changed: By: Show search header nototal="on" Do not show number of topics found Show number header="..." format="..." Custom format results: see FormattedSearch for usage, variables & examples Results in table Regular example: %SEARCH{"wiki" web="Main" scope="topic"}% Formatted example: %SEARCH{"FAQ" scope="topic" nosearch="on" nototal="on" header="| *Topic: * | *Summary: * |" format="| $topic | $summary |"% (displays results in a table with header - details) 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%" }%
%METASEARCH{...}%	Special search of meta data Parameter: Description: Default: type="topicmoved" What sort of search is required? "topicmoved" if search for a topic that may have been moved "parent" if searching for topics that have a specific parent i.e. its children required web="%WEB%" Wiki web to search: A web, a list of webs separated by whitespace, or all webs. required topic="%TOPIC%" The topic the search relates to required title="Title" Text that is prepended to any search results required Example: %METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%, you may want to use this in WebTopicViewTemplate and WebTopicNonWikiTemplate %METASEARCH{type="parent" web="%WEB%" topic="%TOPIC%" title="Children: "}%
%VAR{"NAME" web="Web"}%	Get a preference value from a web other then the current one. Example: To get %WEBBGCOLOR% of the Main web write %VAR{"WEBBGCOLOR" web="Main"}%, is #FFFFC0

[1] Note: The search form uses identical names for input fields.

[2] Note: A web can be excluded from a web="all" search if you define a NOSEARCHALL=on variable in its WebPreferences.

Preferences Variables

Additional variables are defined in the preferences ( site-level ( SL ) in TWikiPreferences, web-level ( WL ) in WebPreferences of each web, and user level ( UL ) preferences in individual user topics):

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

Setting Preferences

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

Creating Custom Variables

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

Example: Create a custom logo variable the TWiki web

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

-- PeterThoeny - 19 Jan 2003
-- MikeMannix - 12 May 2002

Note: This feature has been replaced by: TWikiForms