Ben Fish TWiki > TWiki > TWikiDocumentation TWiki webs:
Main | TWiki | Sandbox?
TWiki . { Welcome | Register | Changes | Topics | Index | Search | Go }

TWiki Reference Manual (04 Sep 2004 $Rev: 1742 $)

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

Note - if you are reading this at twiki.org, then you are reading about the most recent code under development.
If you want to read about the features on your local TWiki, then you should read the documentation there!

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

Related Topics: TWikiSite, TWikiHistory?, TWikiPlannedFeatures?, TWikiEnhancementRequests?

Note: Included topic TWikiSystemRequirements? does not exist yet

TWiki Installation Guide

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

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

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

Standard Installation

Download the TWiki 01-Sep-2004 distribution in Unix ZIP format from http://TWiki.org/download.html. Please review the AdminSkillsAssumptions before you install TWiki.

Step 1: Create & Configure the Directories

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

Example httpd.conf entries: 
 ScriptAlias /twiki/bin/ "/home/httpd/twiki/bin/"
 Alias /twiki/ "/home/httpd/twiki/"
 <Directory "/home/httpd/twiki/bin">
    Options +ExecCGI
    SetHandler cgi-script
    Allow from all
 </Directory>
 <Directory "/home/httpd/twiki/pub">
    Options FollowSymLinks +Includes
    AllowOverride None
    Allow from all
 </Directory>
 <Directory "/home/httpd/twiki/data">
    deny from all
 </Directory>
 <Directory "/home/httpd/twiki/templates">
    deny from all
 </Directory>

Aletrnative Step 1: Create & Configure the Directories for Non-Root Accounts

To install TWiki on a system where you don't have Unix/Linux root (administrator) privileges, for example, on a hosted Web account or an intranet server administered by someone else:

TWiki dir: What it is: Where to copy: Example:
twiki start-up pages root TWiki dir /home/smith/twiki/
twiki/bin CGI bin CGI-enabled dir /home/smith/twiki/bin
twiki/lib library files same level as twiki/bin /home/smith/twiki/lib
twiki/pub public files htdoc enabled dir /home/smith/twiki/pub
twiki/data topic data dir secure from public access /home/smith/twiki/data
twiki/templates web templates dir secure from public access /home/smith/twiki/templates

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

Step 2: Set File Permissions

Step 3: Edit the Configuration Files

Step 4: Internationalisation Setup (Optional)

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

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

To configure internationalisation suppport:

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

Trouble with I18N?

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

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

Step 5: Configure Site-Wide Email Preferences

Step 6: Finish Up from Your Browser

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

Additional Server-Level Options

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

Enabling Authentication of Users

WYSIWYG Editor

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

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

TWiki File System Info

See Appendix A: TWiki File System for an installed system snapshot and descriptions of all files in the TWiki 01-Sep-2004 distribution.

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

Note: Included topic WindowsInstallCookbook? does not exist yet

Note: Included topic TWikiUpgradeGuide? does not exist yet

TWiki User Authentication

TWiki site access control and user activity tracking options

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

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

Authentication Options

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

  1. No login at all: Forget about authentication to make your site completely public - anyone can browse and edit freely, in classic Wiki mode. All visitors are assigned the TWikiGuest default identity, so you can't track individual user activity.
  2. No login to view; require login to edit: Keeping track of who changed what and when, while keeping view access unrestricted is desirable in most TWiki deployments. This option is not suitable if you need TWikiAccessControl for view restricted content since TWiki does not know who a user is when looking at content.
  3. No login to view unless necessary; require login to edit: You prefer not to bother the user with login for unrestricted content, but you need TWikiAccessControl for view restricted content. There are two ways to accomplish this:
  4. Require login to view and edit: Most restrictive, but TWiki knows who the user is at all times. There are two ways to accomplish this:

Partial Authentication

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

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

TWiki Username vs. Login Username

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

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

TWiki can automatically map an Intranet (Login) Username to a TWiki Username, provided that the username pair exists in the TWikiUsers topic. This is also handled automatically when you register.

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

Changing Passwords

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

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

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

After submitting this form your password will be changed.

If you have questions please contact the TWiki webmaster webmaster@kitchentablemath.net.

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

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

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

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

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

TWiki Access Control

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

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

An Important Control Consideration

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

As a collaboration guideline:

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:

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:
  2. Set Preferences for two Variables in the new group topic:

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.

Deny Editing by Web

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

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

Restricting Rename Access

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

Deny Renaming by Topic

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

Deny Renaming by Web

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

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

Restricting Read Access

You can define who is allowed to see a web.

Deny Viewing by Topic

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

Deny Viewing by Web

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

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:

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

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

Authenticate all Webs and Restrict Selected Webs

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

  1. Restrict view access to selected Users and Groups. Set one or both of these variables in its WebPreferences topic:
  2. Hide the web from an "all webs" search. Enable this restriction with the NOSEARCHALL variable in its WebPreferences topic:
  3. Add view to the list of authenticated scripts in the .htaccess file.

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

Authenticate and Restricting Selected Webs Only

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

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

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

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

Hiding Control Settings

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

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

The SuperAdminGroup

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

$superAdminGroup = "TWikiAdminGroup";

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

TWiki Text Formatting

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

TWiki Editing Shorthand

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

2nd paragraph
1st paragraph

2nd paragraph

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

---+++ Maguro

Sushi

Maguro
Bold Text:
Words get bold by enclosing them in * asterisks. 
*Bold*
Bold
Italic Text:
Words get italic by enclosing them in _ underscores. 
_Italic_
Italic
Bold Italic:
Words get _bold italic by enclosing them in _ double-underscores. 
__Bold italic__
Bold italic
Fixed Font:
Words get shown in fixed font by enclosing them in = equal signs. 
=Fixed font=
Fixed font

Bold Fixed Font:
Words get shown in bold fixed font by enclosing them in double equal signs. 
==Bold fixed==
Bold fixed
Note: Make sure there is no space between the text and the bold, italic, or other indicators (* _ __ = ==). 
_This works_,
_this not _
This works,
_this not _
Verbatim Mode:
Surround code excerpts and other formatted text with <verbatim> and </verbatim> tags.
Note: Use <pre> and </pre> tags instead if you want that HTML code is interpreted.
Note: Each tag must be on a line by itself. 
<verbatim>
class CatAnimal {
  void purr() {
    <code here>
  }
}
</verbatim>

class CatAnimal {
  void purr() {
    <code here>
  }
}
Separator:
At least three dashes at the beginning of a line. 
-------
List Item:
Three spaces, an asterisk, and another space. 
   * bullet item
  • bullet item
Nested List Item:
Six, nine, ... spaces, an asterisk, and another space. 
   * level 1
      * level 2
  • level 1
    • level 2
Ordered List:
Three spaces, a number, a dot, and another space. Several types are available besides a number:
Type Generated Style Sample Sequence
1. Arabic numerals 1, 2, 3, 4...
A. Uppercase letters A, B, C, D...
a. Lowercase letters a, b, c, d...
I. Uppercase Roman Numerals I, II, III, IV...
i. Lowercase Roman Numerals i, ii, iii, iv... 

   1. Sushi
   1. Dim Sum

   A. Sushi
   A. Dim Sum

   i. Sushi
   i. Dim Sum
  1. Sushi
  2. Dim Sum

  1. Sushi
  2. Dim Sum

  1. Sushi
  2. Dim Sum
Definition List:
Three spaces, a dollar sign, the term, a colon, a space, followed by the definition. 
   $ Sushi: Japan
   $ Dim Sum: S.F.
Sushi
Japan
Dim Sum
S.F.
Table:
Any number of lines of text. Each line is one row of the table consisting of one or more cells. Each cell starts and ends with a vertical bar '|'. Any spaces at the beginning of a line are ignored.
Notes:
• | *bold* | cells are displayed as table headers.
• |   center-spaced   | cells are displayed center aligned.
• |     right-spaced | cells are displayed right aligned.
• | 2 colspan || cells are displayed as multi-span columns (i.e., a cell with no text spans a column).
• |^| cells with a caret indicate follow-up rows of multi-span rows (this functionality is provided by TablePlugin).
• If a row contains a large amount of text, and you want it to be more readable while editing the table, split the row into multiple text lines by ending each line with a backslash character '\'.
• Table cells wrap automatically as determined by the browser. 
| *L* | *C* | *R* |
| A2 |  2  |  2 |
| A3 |  3  |  3 |
| multi span |||
| A4-6 | four | four |
|^| five | five |



|^| six | six |
L C R
A2 2 2
A3 3 3
multi span
A4-6 four four
five five
six six
WikiWord Links:
CapitalizedWordsStuckTogether (or WikiWords) will produce a link automatically.
Note: In case you want to link to a topic in a different TWiki web write Otherweb.TopicName. (The link label is the the name of the web in case the is WebHome, else it is the topic name) 
WebNotify

Main.TWikiUsers
WebNotify

TWikiUsers

Forced Links:
You can create a forced internal link by enclosing words in double square brackets.
Note: Text within the brackets may contain optional spaces; the topic name is formed by capitalizing the initial letter and by removing the spaces; for example, [[text formatting FAQ]] links to topic TextFormattingFAQ?. You can also refer to a different web and use anchors.
Note: To "escape" double square brackets that would otherwise be a correct link, prefix the leading left square brackets with an exclamation point, that is, begin with ![[.... 
[[wiki syntax]]

[[Main.TWiki users]]

escaped:
![[wiki syntax]]
wiki syntax

Main.TWiki users

escaped: [[wiki syntax]]

Specific Links:
Create a link where you can specify the link text and the link reference separately, using nested square brackets like [[reference][text]]. Internal link references (e.g. WikiSyntax) and external link references (e.g. http://TWiki.org/) are supported.
Note: The same Forced Links rules apply for internal link references.
Note: For external link references, you can simply use a space instead of ][ to separate the link URL from the descriptive text.
Note: Anchor names can be added as well, like [[WebHome#MyAnchor][go home]] and [[http://gnu.org/#Action][GNU Action]]. 
[[WikiSyntax][syntax]]

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

[[http://xml.org XML]]
syntax

GNU

XML

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

[[#MyAnchor][Jump]]

#MyAnchor To here
WikiWord#NotThere

Jump

To here

Prevent a Link:
Prevent a WikiWord from being linked by prepending it with an exclamation point. 
!SunOS
SunOS
Disable Links:
You can disable automatic linking of WikiWords by surrounding text with <noautolink> and </noautolink> tags.
Note: Each tag must be on a line by itself.
Note: This also works for TWiki tables, but only if you add a blank line between the end of the table and the closing </noautolink> tag (known issue of the TablePlugin). 
 <noautolink>
 RedHat &
 SuSE
 </noautolink>
RedHat & SuSE
Mailto: Links:
To create 'mailto:' links that have more descriptive link text, specify subject lines or message bodies, or omit the email address, you can write [[mailto:user@domain descriptive text]]. 
[[mailto:a@z.com Mail]]

[[mailto:?subject=Hi Hi]]
Mail

Hi

Using HTML

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

HTML and TWiki Usability

TWiki HTML Rendering

TWiki and JavaScript

You can use JavaScript for your TWiki applications. Since TWiki rendering might interfere with JavaScript code you need to escape it with HTML comments and <pre> tags: 

<script type="text/javascript">
<!-- Hide JavaScript and <pre> escape TWiki rendering
... put your JavaScript code here...
// Stop hiding and stop </pre> escaping TWiki rendering -->
</script>

Hyperlinks

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

Internal Links

External Links

TWiki Variables

Variables are names that are enclosed in percent signs % that are expanded on the fly.

TWikiPlugin Formatting Extensions

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

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

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

Common Editing Errors

TWiki formatting rules are fairly simple to use and quick to type. However, there are some things to watch out for, taken from the TextFormattingFAQ?:

-- TWiki:Main.MikeMannix - 02 Dec 2001
-- TWiki:Main.PeterThoeny - 01 Aug 2004

TWiki Variables

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

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

Notes:

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.

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

ATTACHURL -- full URL for attachments in the current topic

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

BASETOPIC -- base topic where an INCLUDE started

BASEWEB -- base web where an INCLUDE started

DISPLAYTIME -- display time

DISPLAYTIME{"format"} -- formatted display time

ENCODE{"string"} -- encodes a string

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

GMTIME -- GM time

GMTIME{"format"} -- formatted GM time

HOMETOPIC -- home topic in each web

HTTP_HOST -- environment variable

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

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

INCLUDINGTOPIC -- name of topic that includes current topic

INCLUDINGWEB -- web that includes current topic

MAINWEB -- name of Main web

METASEARCH -- special search of meta data

NOTIFYTOPIC -- name of the notify topic

PLUGINVERSION -- the version of the TWiki Plugin API

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

PUBURL -- the base URL of attachments

PUBURLPATH -- the base URL path of attachments

REMOTE_ADDR -- environment variable

REMOTE_PORT -- environment variable

REMOTE_USER -- environment variable

REVINFO -- revision information of current topic

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

SCRIPTURL -- script URL of TWiki

SCRIPTURLPATH -- script URL path of TWiki

SCRIPTSUFFIX -- script suffix

SEARCH{"text"} -- search content

SERVERTIME -- server time

SERVERTIME{"format"} -- formatted server time

SPACEDTOPIC -- topic name, spaced and encoded

STARTINCLUDE -- start position of topic text if included

STATISTICSTOPIC -- name of statistics topic

STOPINCLUDE -- end position of topic text if included

TOC -- table of contents of current topic

TOC{"Topic"} -- table of contents

TOPIC -- name of current topic

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

TWIKIWEB -- name of TWiki documentation web

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

USERNAME -- your login username

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

WEB -- name of current web

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

WEBPREFSTOPIC -- name of web preferences topic

WIKIHOMEURL -- site home URL

WIKINAME -- your Wiki username

WIKIPREFSTOPIC -- name of site-wide preferences topic

WIKITOOLNAME -- name of your TWiki site

WIKIUSERNAME -- your Wiki username with web prefix

WIKIUSERSTOPIC -- name of topic listing all registers users

WIKIVERSION -- the version of the installed TWiki engine

Note: Above text is included from TWikiVariablesAtoM and TWikiVariablesNtoZ

Preferences Variables

Additional variables are defined in the preferences topics:

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

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

Setting Preferences

Creating Custom Variables

Example: Create a custom logo variable the TWiki web

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

File Attachments

Each topic can have one or more files of any type attached to it by using the Attach screen to upload (or download) files from your local PC. Attachments are stored under revision control: uploads are automatically backed up; all previous versions of a modified file can be retrieved.

What Are Attachments Good For?

File Attachments can be used to create powerful customized groupware solutions, like file sharing and document management systems, and quick Web page authoring.

Document Management System

File Sharing

Web Authoring

Uploading Files

Downloading Files

Moving Attachment Files

An attachment can be moved between topics.

Deleting Attachments

Move unwanted Attachments to web Trash, topic TrashAttachment.

Linking to Attached Files

File Attachment Contents Table

Files attached to a topic are displayed in a directory table, displayed at the bottom of the page, or optionally, hidden and accessed when you click Attach.

Attachment Action Size Date Who Comment
Sample.txt manage 0.1 K 22 Jul 2000 - 19:37 PeterThoeny Just a sample
Smile.gif manage 0.1 K 22 Jul 2000 - 19:38 PeterThoeny Smiley face

File Attachment Controls

Clicking on a Manage link takes you to a new page that looks like this:

Attachment Action Size Date Who Comment Attribute
Sample.txt manage 0.1 K 22 Jul 2000 - 19:37 PeterThoeny Just a sample  
Smile.gif manage 0.1 K 22 Jul 2000 - 19:38 PeterThoeny Smiley face  

Update attachment Sample.txt

Version Action Date Who Comment
1.1 view 2001.08.30.09.28.56 PeterThoeny  

Previous
upload: 		C:\DATA\Sample.txt (PeterThoeny)
Local file:
Comment:
Link: Create a link to the attached file at the end of the topic.
Hide file: Hide attachment in normal topic view.
Help text ...

Topic FileAttachment . { | | Move attachment | Cancel }

Known Issues

TWiki Forms

Form-based input in topics, with name/value pairs stored as Meta Data variables; choose one of multiple forms per web & topic

Overview

By adding form-based input to freeform content, you can structure topics with unlimited, easily searchable categories. When forms are enabled for a web and selected in a topic, a single form appears in edit mode, and the contents are rendered as a table when viewed on the display page. You can define unlimited forms per web. For each topic, you can select a template if more than one is defined, or remove forms entirely. Form input values are stored as TWikiMetaData; all data is saved.

Form Templates replace TWikiCategoryTables from the 01-Dec-2000 version of TWiki. - see #FormsVsCategoryTables

Defining a Form Template

A Form Template is simply a page containing your form, defined as a table where each row is one form field.

Form Template Elements

Defining a Form in One Topic

  1. Create a new topic with your form name: YourForm, ExpenseReport, InfoCategory, RecordReview, whatever you need.
  2. Create a TWiki table, with each column head representing one element of an entry field: Name, Type, Size, Values, and Tooltip message (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* |
| 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
TopicClassification select 1 NoDisclosure, PublicSupported, PublicFAQ blah blah...
OperatingSystem checkbox 3 OsHPUX, OsLinux, OsSolaris, OsWin blah blah...
OsVersion text 16   blah blah...

Defining a Form with Multiple Topics

Forms can also be defined by using form templates that retrieve field values from one or more separate topics:

Example: WebFormTemplate

Enabling Forms by Web

Forms are enabled on a per web basis. The WEBFORMS variable in WebPreferences is optional and defines a list of possible form templates. Example:

Including Forms in New Topics

Setting Up Multiple Form Options

Form Data Storage

The form topic name, fields and values are stored as TWikiMetaData - the order of the field/value pairs is the same as in the template.

Using Form Data

TWikiForms accept user-input data, stored as TWikiMetaData. Meta data also contains program-generated info about changes, attachments, etc. To find, format and display form and other meta data, see TWikiMetaData, SEARCH and METASEARCH variables in TWikiVariables, and TWiki Formatted Search for various options.

Main Changes from Category Tables

The Form Template system is a more powerful, flexible replacement for the original TWikiCategoryTable. Data from existing category tables can be imported directly.

Form Templates Category Tables
defined in topics defined in templates
many forms per web one table per web
saved as Meta Data saved as HTML
Change & Add Form buttons UseCategory radio button

Importing Category Table 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.

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

Using Forms For Settings

Example process to change your WebPreferences to use forms instead of {3 spaces}* Set statements:

  1. create WebPrefencesForm topic
  2. fill it with a table like this:
    | *Name*|*Type*|*Size*|*Value*|*Tooltip message*|*Attributes*|
    | WEBTOPICLIST |textarea| |     | List of topics of the %WEB% web |S|
    | SITEMAPLIST  |select  |3| on, | list this web in the Site Map  |S|
    | SITEMAPWHAT  |textarea| |     | short web summary             |S|
    | WEBBGCOLOR   |text    |8|     | Web specific background color |S|
    etc...
  3. Edit WebPreferences and:
  4. Edit WebPreferences, jump straight down to the form ignoring all the textarea stuff, and set as you like
  5. if everything works as you like it, you can delete the Set statements (the form overrides set if they are both used).

Notes:

If it isn't working, double check that the S attribute has been specified (S for Setting). If you change the form, the changes will not take affect until you edit and save the preferences' topics again.

Using the TWiki:Plugins.EditTablePlugin on WebPreferencesForm makes adding new prefedrences a breeze.

A possibly unwanted side effect for using forms for the SKINS setting in their personal user topic: because the User Preferences are final you can't have different skins for different webs as the user's setting always wins. A workaround is to simply omit SKIN in the form.

Another example, this one using EditTablePlugin, source:

%EDITTABLE{ header="|*Name*|*Type*|*Size*|*Values*|*Tooltip message*|*Attributes*|" format="|text,20|text,20|text,20|text,20|text,20|text,1|" }%

Result (after some editing):

Name Type Size Values tooltip message Attributes
ALLOWTOPICCHANGE textarea     Users or groups allowed to change or rename this TWikiForms topic: (I.e. TWikiAdminGroup) S
ALLOWWEBCHANGE textarea     Users or groups who are allowed to change topics in the TWiki web: (See TWikiAccessControl) S
ALLOWWEBRENAME textarea   TWikiAdminGroup Users or groups who are allowed to rename topics in the TWiki web: (See TWikiAccessControl) S
ALLOWWEBVIEW textarea     Users or groups who are allowed to view topics in the TWiki web: (See TWikiAccessControl) S
DENYWEBCHANGE textarea     Users or groups who are not allowed to change topics in the TWiki web: (See TWikiAccessControl) S
DENYWEBRENAME textarea     Users or groups who are not allowed to rename topics in the TWiki web: (See TWikiAccessControl) S
DENYWEBVIEW textarea     Users or groups who are not allowed to view topics in the TWiki web: (See TWikiAccessControl) S
FINALPREFERENCES textarea   "NOSEARCHALL, ATTACHFILESIZELIMIT, WIKIWEBMASTER, WEBCOPYRIGHT, WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, DENYWEBRENAME, ALLOWWEBRENAME" Web preferences that are not allowed to be overridden by user preferences S
NOSEARCHALL text   ",on" "Exclude web from a web=""all"" search: (Set to on for hidden webs)" S
SITEMAPLIST select   "on, ," List this web in the SiteMap S
SITEMAPUSETO textarea   ...to do something. ...to do something. S
SITEMAPWHAT textarea   Describe what this web does. Describe what this web does.  
SKIN select   "twiki, free, gnu, koala, pattern, plain, tiger" list of installed skins S
WEBBGCOLOR select   lightpink, pink, crimson, lavenderblush, palevioletred, hotpink, deeppink, mediumvioletred, orchid, thistle, plum, violet, fuchsia, fuchsia, darkmagenta, purple, mediumorchid, darkviolet, darkorchid, indigo, blueviolet, mediumpurple, mediumslateblue, slateblue, darkslateblue, ghostwhite, lavender, blue, mediumblue, darkblue, navy, midnightblue, royalblue, cornflowerblue, lightsteelblue, lightslategray, slategray, dodgerblue, aliceblue, steelblue, lightskyblue, skyblue, deepskyblue, lightblue, powderblue, cadetblue, darkturquoise, azure, lightcyan, paleturquoise, aqua, aqua, darkcyan, teal, darkslategray, mediumturquoise, lightseagreen, turquoise, aquamarine, mediumaquamarine, mediumspringgreen, mintcream, springgreen, mediumseagreen, seagreen, honeydew, darkseagreen, palegreen, lightgreen, limegreen, lime, forestgreen, green, darkgreen, lawngreen, chartreuse, greenyellow, darkolivegreen, yellowgreen, olivedrab, ivory, beige, lightyellow, lightgoldenrodyellow, yellow, olive, darkkhaki, palegoldenrod, lemonchiffon, khaki, gold, cornsilk, goldenrod, darkgoldenrod, floralwhite, oldlace, wheat, orange, moccasin, papayawhip, blanchedalmond, navajowhite, antiquewhite, tan, burlywood, darkorange, bisque, linen, peru, peachpuff, sandybrown, chocolate, saddlebrown, seashell, sienna, lightsalmon, coral, orangered, darksalmon, tomato, salmon, mistyrose, lightcoral, snow, rosybrown, indianred, red, brown, firebrick, darkred, maroon, white, whitesmoke, gainsboro, lightgrey, silver, darkgray, gray, dimgray, black Web specific background color: (Pick a lighter one of the StandardColors) S
WEBFORMS textarea     TWikiForms: How to enable form(s) S
WEBTOPICLIST textarea   WebHome, Changes, Topics, Index, Search, Go the main entry point topics for this web S

-- TWiki:Main.JohnTalintyre - 16 Aug 2001
-- TWiki:Main.MikeMannix - 05 Jan 2002
-- TWiki:Main.PeterThoeny - 25 Apr 2004
-- TWiki:Main.MattWilkie - 27 Jul 2004

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:

How Template Variables Work

Types of Template

There are three types of template:

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 stored either in the twiki/templates directory or in user topics. As an example, twiki/templates/view.tmpl is the template file for the twiki/bin/view script.

HELP Templates can be overloaded by individual webs.

HELP TWikiSkins can overload the standard templates.

TWiki uses the following search order to determine which template to use:

If a skin is specified If no skin is specified
templates/%WEB%/script.skin.tmpl templates/%WEB%/script.tmpl
templates/script.skin.tmpl templates/script.tmpl
data/%WEB%/SkinSkinScriptTemplate.txt data/%WEB%/ScriptTemplate.txt
data/TWiki/SkinSkinScriptTemplate.txt data/TWiki/ScriptTemplate.txt
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 the skin name, e.g dragon, pattern
• Skin refers to the same, but with the first character capitalized, e.g Dragon
• %WEB% refers to the current web

Additionally (and primarily for use in %TMPL:INCLUDE{}%) the template name may be a wiki topic name, specified as Web.Topic, in which case the search is:

If a skin is specified If no skin is specified
templates/web/Web.Topic.skin.tmpl templates/web/Web.Topic.tmpl
templates/Web.Topic.skin.tmpl templates/Web.Topic.tmpl
data/Web/Topic.txt
If Web is not specified in the INCLUDE, it defaults to TWiki, and the search to the first type.

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.
All template topics are located in the TWiki web. The WebTopicEditTemplate can be overloaded. When you create a new topic, TWiki locates a topic to use as a content template according to the following search order:

  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. 23 May 2013
%USERNAME% Login name, e.g. jsmith
%WIKINAME% WikiName of user, e.g. JohnSmith
%WIKIUSERNAME% User name, e.g. Main.JohnSmith
%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:

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="topicparent" value="%TOPIC%" />
     <input type="hidden" name="onlywikiname" value="on" />
     <input type="hidden" name="onlynewtopic" value="on" />
     <input type="submit" value="Create" />
     (date format is <nop>YYYYxMMxDD)
</form>

The edit scipt understands the following parameters, typically supplied by HTML input fields:

Parameter: Description:
topic Name of topic to create. Can be set in a text field, or is set programmatically (e.g. with a sequential number)
onlywikiname If set, TWiki will complain if the topic name is not a WikiWord
onlynewtopic If set, TWiki will complain if a topic of the same name already exists
templatetopic The name of the template topic, e.g. topic used to copy the initial content
topicparent Sets the parent topic
TopicClassification Assuming the template topic has a form with a field called "TopicClassification", it will set the value of the field
contenttype Optional parameter that defines the application type to write into the CGI header. Defaults to text/html. May be used to invoke alternative client applications
anyname Any parameter can passed to the new topic; if the template topic contains %URLPARAM{"anyname"}%, it will be replaced by its value

TIP 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

testscreen.gif

Known Issues

-- TWiki:Main.CrawfordCurrie - 30 Jun 2004
-- TWiki:Main.PeterThoeny - 15 Aug 2004
-- TWiki:Main.MikeMannix - 14 Sep 2001
-- TWiki:Main.DavidLeBlanc - 11 Mar 2002

TWiki Skins

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

Overview

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

Defining Skins

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

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

Variables in Skins

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

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

The "Go" Box and Navigation Box

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

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

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

Using Cascading Style Sheets

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

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

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

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

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

Attachment Tables

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

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

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

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

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

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

Packaging and Publishing Skins

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

Browsing Installed Skins

You can try all installed skins in TWikiSkinBrowser.

Activating Skins

A skin can be activated in two ways:

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

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

TWiki Formatted Search Results

Inline search feature allows flexible formatting of search result

The %SEARCH{...}% variable documented in TWikiVariables has a fixed format for the search result, that is, a table consisting of topic names and topic summaries. Use the format="..." parameter to specify a customized format of the search result. The string of the format parameter is typically a bullet list or table row containing variables (such as %SEARCH{ "food" format="| $topic | $summary |" }%).

Syntax

Two parameters can be used to specify a customized search result:

1. header="..." parameter

Use the header parameter to specify the header of a search result. It should correspond to the format of the format parameter. This parameter is optional.
Example: header="| *Topic:* | *Summary:* |"

2. format="..." parameter

Use the format parameter to specify the format of one search hit.
Example: format="| $topic | $summary |"

Variables that can be used in the format string:

Name: up Expands To:
$wikiusername Wiki user name of last topic update, like Main.JohnSmith
$wikiname Wiki user name of last topic update, e.g. JohnSmith
$web Name of the web
$username Login name of last topic update, e.g. jsmith
$topic Topic name
$topic(40, ...) Topic name, shortended to 40 characters with "..." indication
$topic(30, -<br />) Topic name, hyphenated each 30 characters with separator "-<br />"
$topic(20) Topic name, "- " hyphenated each 20 characters
$text Formatted topic text. In case of a multiple="on" search, it is the line found for each search hit.
$summary Topic summary
$rev Number of last topic revision, e.g. 1.4
$quot Double quote ("). Alternatively write \" to escape it
$percnt Percent sign (%)
$pattern(reg-exp) A regular expression pattern to extract some text from a topic (does not search meta data; use $formfield instead). In case of a multiple="on" search, the pattern is applied to the line found in each search hit.
• Specify a RegularExpression that covers the whole text (topic or line), which typically starts with .*, and must end in .*
• Put text you want to keep in parenthesis, like $pattern(.*?(from here.*?to here).*)
• Example: $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the email address from a bullet of format * Email: ...
• This example has non-greedy .*? patterns to scan for the first occurance of the Email bullet; use greedy .* patterns to scan for the last occurance
• Limitation: Do not use .*) inside the pattern, e.g. $pattern(.*foo(.*)bar.*) does not work, but $pattern(.*foo(.*?)bar.*) does
• Note: Make sure that the integrity of a web page is not compromised; for example, if you include an HTML table make sure to include everything including the table end tag
$parent Name of parent topic; empty if not set
$parent(20) Name of parent topic, same hyphenation/shortening like $topic()
$nop or $nop() Is a "no operation". This variable gets removed; useful for nested search
$n or $n() New line
$locked LOCKED flag (if any)
$isodate Time stamp of last topic update, e.g. 2013-05-23T01:28Z
$formname The name of the form attached to the topic; empty if none
$formfield(name, 30, ...) Form field value, shortended to 30 characters with "..." indication
$formfield(name, 20, -<br />) Form field value, hyphenated each 20 characters with separator "-<br />"
$formfield(name, 10) Form field value, "- " hyphenated each 10 characters
$formfield(name) The field value of a form field; for example, $formfield(TopicClassification) would get expanded to PublicFAQ. This applies only to topics that have a TWikiForm
$dollar Dollar sign ($)
$date Time stamp of last topic update, e.g. 23 May 2013 - 01:28
$createwikiusername Wiki user name of topic revision 1.1, e.g. Main.JohnSmith
$createwikiname Wiki user name of topic revision 1.1, e.g. JohnSmith
$createusername Login name of topic revision 1.1, e.g. jsmith
$createdate Time stamp of topic revision 1.1

Examples

Bullet list showing topic name and summary

Write this:

%SEARCH{ "FAQ" scope="topic" nosearch="on" nototal="on" header="   * *Topic: Summary:*" format="   * [[$topic]]: $summary" }%

To get this:

Table showing form field values of topics with a form

In a web where there is a form that contains a TopicClassification field, an OperatingSystem field and an OsVersion field we could write:

| *Topic:* | *OperatingSystem:* | *OsVersion:* |
%SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" scope="text" regex="on" nosearch="on" nototal="on" format="| [[$topic]] | $formfield(OperatingSystem) | $formfield(OsVersion) |" }%

To get this:

Topic: OperatingSystem: OsVersion:
IncorrectDllVersionW32PTH10DLL OsWin 95/98
WinDoze95Crash OsWin 95

Extract some text from a topic using regular expression

Write this:

%SEARCH{ "__Back to\:__ TWikiFAQ" scope="text" regex="on" nosearch="on" nototal="on" header="TWiki FAQs:" format="   * $pattern(.*?FAQ\:[\n\r]*([^\n\r]+).*) [[$topic][Answer...]]" }%

To get this:

TWiki FAQs:

Nested Search

Search can be nested. For example, search for some topics, then form a new search for each topic found in the first search. The idea is to build the nested search string using a formatted search in the first search.

Here is an example. Let's search for all topics that contain the word "culture" (first search), and let's find out where each topic found is linked from (second search).

Write this:

%SEARCH{ "culture" format="   * $topic is referenced by:$n      * $percntSEARCH{ \"$topic\" format=\"$dollartopic\" nosearch=\"on\" nototal=\"on\" separator=\", \" }$nop%" nosearch="on" nototal="on" }%

To get this:

Note: Nested search can be slow, especially if you nest more then 3 times. Nesting is limited to 16 levels. For each new nesting level you need to "escape the escapes", e.g. write $dollarpercntSEARCH{ for level three, $dollardollarpercntSEARCH{ for level four, etc.

Most recently changed pages

Write this:

%SEARCH{ "\.*" scope="topic" regex="on" nosearch="on" nototal="on" order="modified" reverse="on"  format="| [[$topic]] | $wikiusername  | $date |" limit="7" }%

To get this:

WebStatistics Main.guest 08 Dec 2012 - 04:10
TWikiPreferences CarolynJohnston 24 Dec 2005 - 01:46
CommentsTmpl CarolynJohnston 20 Jul 2005 - 19:28
TWikiRegistration CarolynJohnston 18 Jul 2005 - 03:40
WebSearch CarolynJohnston 19 Jun 2005 - 23:25
NewUserTemplate CarolynJohnston 17 May 2005 - 02:42
WikiNotation Main.guest 01 May 2005 - 00:22

Search with conditional output

A regular expression search is flexible, but there are limitations. For example, you cannot show all topics that are up to exactly one week old, or create a report that shows all records with invalid form fields or fields within a certain range, etc. You need some additional logic to format output based on a condition:

  1. Specify a search which returns more hits then you need
  2. For each search hit apply a spreadsheet formula to determine if the hit is needed
  3. If needed, format and output the result
  4. Else supress the search hit

This requires the TWiki:Plugins.SpreadSheetPlugin. The following example shows all topics that are up to exactly one week old.

Write this:

%CALC{$SET(weekold, $TIMEADD($TIME(), -7, day))}%
%SEARCH{ "." scope="topic" regex="on" nosearch="on" nototal="on" order="modified" reverse="on" format="$percntCALC{$IF($TIME($date) < $GET(weekold), <nop>, | [[$topic]] | $wikiusername | $date | $rev |)}$percnt" limit="100" }%

To get this:

Embedding search forms to return a formatted result

Use an HTML form and an embedded formatted search on the same topic. You can link them together with an %URLPARAM{"..."}% variable. Example:

Write this: 

<form action="%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%">
Find Topics: 
<input type="text" name="q" size="32" value="%URLPARAM{"q"}%" />
<input type="submit" value="Search" />
</form>
Result:
%SEARCH{ search="%URLPARAM{"q"}%" format="   * $web.$topic: %BR% $summary" nosearch="on" }%

To get this:

Find Topics:
Result: Number of topics: 0

-- TWiki:Main.PeterThoeny - 26 Jul 2004

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

Example of Format 
%META:TOPICINFO{version="1.6" date="976762663" author="PeterThoeny" format="1.0"}%
   text of the topic
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
   by="JohnTalintyre" 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

Key Comment
version Same as RCS version
date integer, unix time, seconds since start 1970
author last to change topic, is the REMOTE_USER
format Format of this topic, will be used for automatic format conversion

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

Key Comment
from Full name, i.e., web.topic
to Full name, i.e., web.topic
by Who did it, is the REMOTE_USER, not WikiName
date integer, unix time, seconds since start 1970

Notes:

META:TOPICPARENT

Key Comment
name The topic from which this was created, WebHome if done from Go, othewise topic where ? or form used. Normally just topic, but is full web.topic format if parent is in a different Web. Renaming a Web will then only break a few of these references or they can be scanned and fixed.

META:FILEATTACHMENT

Key Comment
name Name of file, no path. Must be unique within topic
version Same as RCS revision
path Full path file was loaded from
size In bytes
date integer, unix time, seconds since start 1970
user the REMOTE_USER, not WikiName
comment As supplied when file uploaded
attr h if hidden, optional

Extra fields that are added if an attachment is moved:

Key Comment
movedfrom full topic name - web.topic
movedby the REMOTE_USER, not WikiName
movedto full topic name - web.topic
moveddate integer, unix time, seconds since start 1970

META:FORM

Key Comment
name A topic name - the topic represents one of the TWikiForms. Can optionally include the web name (i.e., web.topic), but doesn't normally

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.

Key Name
name Ties to entry in TWikiForms template, is title with all bar alphanumerics and . removed
title Full text from TWikiForms template
value Value user has supplied via form

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:

The recommended sequence is:

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.

Note: Rendering meta data is currently not supported in topic text. As a workaround, use FormattedSearch on the current topic only to render form fields.

Current support covers:

Variable usage: Comment:
%META{"form"}% Show form data, see TWikiForms.
%META{"formfield"}% Show form field value. Parameter: name="field_name". Example:
%META{ "formfield" name="TopicClassification" }%
%META{"attachments"}% Show attachments, except for hidden ones. Options:
all="on": Show all attachments, including hidden ones.
%META{"moved"}% Details of any topic moves.
%META{"parent"}% Show topic parent. Options:
dontrecurse="on": By default recurses up tree, at some cost.
nowebhome="on": Suppress WebHome.
prefix="...": Prefix for parents, only if there are parents, default "".
suffix="...": Suffix, only appears if there are parents, default "".
separator="...": Separator between parents, default is " > ".

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.

-- TWiki:Main.JohnTalintyre - 29 Aug 2001
-- TWiki:Main.MikeMannix - 03 Dec 2001
-- TWiki:Main.PeterThoeny - 15 Aug 2004

TWiki Plugins

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

Overview

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

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

Preinstalled Plugins

TWiki comes with a set of Plugins as part of the standard installation.

Installing Plugins

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

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

  1. Download the zip file containing the Plugin, documentation, and any other required files, from TWiki:Plugins.
  2. Distribute the files to their proper locations - unzip the zip archive in your TWiki installation directory - if have a standard TWiki installation, this will distribute automatically. Otherwise, place the files according to the directory paths listed on the Plugin top in TWiki:Plugins.
  3. Check the demo example on the Plugin topic: if it's working, the installation was fine!

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

Each Plugin has a standard release page, located in the TWiki:Plugins web at TWiki.org. In addition to the documentation topic (SomePlugin), there's a separate development page.

On-Site Pretesting

To test new Plugins on your installation before making them public, you may want to use one of these two approaches:

Checking that Plugins are Working on a Live Server

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

A Note on Plugin Performance

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

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

Managing Plugins

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

Setting Preferences

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

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

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

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

Listing Active Plugins

Plugin status variables let you list all active Plugins wherever needed. There are two list formats:

DEMO: Automatically List Active Plugins Using Variables

Using %ACTIVATEDPLUGINS%:
On this TWiki site, the active Plugins are: DefaultPlugin, SpreadSheetPlugin, CommentPlugin, ContributorsPlugin, EditTablePlugin, InterwikiPlugin, RenderListPlugin, SlideShowPlugin, TablePlugin.

Using %PLUGINDESCRIPTIONS%:
You can use any of these active TWiki Plugins:

The TWiki Plugin API

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

Available Core Functions

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

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

Predefined Hooks

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

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

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

Hints on Writing Fast Plugins

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.

Creating Plugins

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

The DefaultPlugin Alternative

Anatomy of a Plugin

A basic TWiki Plugin consists of two elements:

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

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

Creating the Perl Module

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

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

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

Writing the Documentation Topic

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

  1. Copy the Plugin topic template from TWiki.org. To copy the text, go to TWiki:Plugins/PluginPackage and:
  2. Customize your Plugin topic.
  3. Save your topic, for use in packaging and publishing your Plugin.

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

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

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

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

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

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

Packaging for Distribution

A minimum Plugin release consists of a Perl module with a WikiName that ends in Plugin, ex: MyFirstPlugin.pm, and a documentation page with the same name(MyFirstPlugin.txt).

  1. Distribute the Plugin files in a directory structure that mirrors TWiki. If your Plugin uses additional files, include them ALL:
  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:

Publishing for Public Use

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

  1. Post the Plugin documentation topic in the TWiki:Plugins/PluginPackage:
  2. Attach the distribution zip file to the topic, ex: MyFirstPlugin.zip
  3. Link from the doc page to a new, blank page named after the Plugin, and ending in Dev, ex: MyFirstPluginDev. This is the discussion page for future development. (User support for Plugins is handled in TWiki:Support.)
  4. Put the Plugin into the CVS repository, see TWiki:Plugins/ReadmeFirst (optional)

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

Recommended Storage of Plugin Data

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

Where to store Plugin Internal Data

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

Where to Store Data for Topics using the Plugin

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

Example code to build the file name: 

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

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

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

TWiki::Func Module Documentation

Official list of stable TWiki functions for Plugin developers

Description

This module defines official funtions that Plugins and add-on scripts can use to interact with the TWiki engine and content.

Plugins should only use functions published in this module. If you use functions in other TWiki libraries you might impose a security hole and you will likely need to change your Plugin when you upgrade TWiki.

The version of the TWiki::Func module is defined by the VERSION number of the TWiki::Plugins module, currently 1.025. This can be shown by the %PLUGINVERSION{}% variable. The "Since" field in the function documentation refers to the VERSION number and the date that the function was addded.

Functions: CGI Environment

getSessionValue( $key ) ==> $value

Description: Get a session value from the Session Plugin (if installed)
Parameter: $key Session key
Return: $value Value associated with key; empty string if not set; undef if session plugin is not installed
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

setSessionValue( $key, $value ) ==> $result

Description: Set a session value via the Session Plugin (if installed)
Parameter: $key Session key
Parameter: $value Value associated with key
Return: $result "1" if success; undef if session plugin is not installed
Since: TWiki::Plugins::VERSION 1.000 (17 Aug 2001)

getSkin( ) ==> $skin

Description: Get the name of the skin, set by the SKIN preferences variable or the skin CGI parameter
Return: $skin Name of skin, e.g. "gnu". Empty string if none
Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)

getUrlHost( ) ==> $host

Description: Get protocol, domain and optional port of script URL
Return: $host URL host, e.g. "http://example.com:80"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getScriptUrl( $web, $topic, $script ) ==> $url

Description: Compose fully qualified URL
Parameter: $web Web name, e.g. "Main"
Parameter: $topic Topic name, e.g. "WebNotify"
Parameter: $script Script name, e.g. "view"
Return: $url URL, e.g. "http://example.com:80/cgi-bin/view.pl/Main/WebNotify"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getScriptUrlPath( ) ==> $path

Description: Get script URL path
Return: $path URL path of TWiki scripts, e.g. "/cgi-bin"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getViewUrl( $web, $topic ) ==> $url

Description: Compose fully qualified view URL
Parameter: $web Web name, e.g. "Main". The current web is taken if empty
Parameter: $topic Topic name, e.g. "WebNotify"
Return: $url URL, e.g. "http://example.com:80/cgi-bin/view.pl/Main/WebNotify"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) ==> $url

Description: Compose fully qualified "oops" dialog URL
Parameter: $web Web name, e.g. "Main". The current web is taken if empty
Parameter: $topic Topic name, e.g. "WebNotify"
Parameter: $template Oops template name, e.g. "oopslocked"
Parameter: $param1 ... $param4 Parameter values for %PARAM1% ... %PARAM4% variables in template, optional
Return: $url URL, e.g. "http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked&param1=joe"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getPubUrlPath( ) ==> $path

Description: Get pub URL path
Return: $path URL path of pub directory, e.g. "/pub"
Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)

getCgiQuery( ) ==> $query

Description: Get CGI query object. Important: Plugins cannot assume that scripts run under CGI, Plugins must always test if the CGI query object is set
Return: $query CGI query object; or 0 if script is called as a shell script
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

writeHeader( $query )

Description: Prints a basic content-type HTML header for text/html to standard out
Parameter: $query CGI query object
Return: none
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

redirectCgiQuery( $query, $url )

Description: Redirect to URL
Parameter: $query CGI query object
Parameter: $url URL to redirect to
Return: none, never returns
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

Functions: Preferences

extractParameters( $attr ) ==> %params

Description: Extract all parameters from a variable string and returns a hash of parameters
Parameter: $attr Attribute string
Return: %params Hash containing all parameters. The nameless parameter is stored in key _DEFAULT
Since: TWiki::Plugins::VERSION 1.025 (26 Aug 2004)

extractNameValuePair( $attr, $name ) ==> $value

Description: Extract a named or unnamed value from a variable parameter string
Note: Function TWiki::Func::extractParameters is more efficient for extracting several parameters
Parameter: $attr Attribute string
Parameter: $name Name, optional
Return: $value Extracted value
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getPreferencesValue( $key, $web ) ==> $value

Description: Get a preferences value from TWiki or from a Plugin
Parameter: $key Preferences key
Parameter: $web Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
Return: $value Preferences value; empty string if not set
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getPluginPreferencesValue( $key ) ==> $value

Description: Get a preferences value from your Plugin
Parameter: $key Plugin Preferences key w/o PLUGINNAME_ prefix.
Return: $value Preferences value; empty string if not set
Since: TWiki::Plugins::VERSION 1.021 (27 Mar 2004)

getPreferencesFlag( $key, $web ) ==> $value

Description: Get a preferences flag from TWiki or from a Plugin
Parameter: $key Preferences key
Parameter: $web Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
Return: $value Preferences flag "1" (if set), or "0" (for preferences values "off", "no" and "0")
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getPluginPreferencesFlag( $key ) ==> $flag

Description: Get a preferences flag from your Plugin
Parameter: $key Plugin Preferences key w/o PLUGINNAME_ prefix.
Return: $flag Preferences flag "1" (if set), or "0" (for preferences values "off", "no" and "0", or values not set at all)
Since: TWiki::Plugins::VERSION 1.021 (27 Mar 2004)

getWikiToolName( ) ==> $name

Description: Get toolname as defined in TWiki.cfg
Return: $name Name of tool, e.g. "TWiki"
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

getMainWebname( ) ==> $name

Description: Get name of Main web as defined in TWiki.cfg
Return: $name Name, e.g. "Main"
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

getTwikiWebname( ) ==> $name

Description: Get name of TWiki documentation web as defined in TWiki.cfg
Return: $name Name, e.g. "TWiki"
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

Functions: User Handling and Access Control

getDefaultUserName( ) ==> $loginName

Description: Get default user name as defined in TWiki.cfg's $defaultUserName
Return: $loginName Default user name, e.g. "guest"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getWikiName( ) ==> $wikiName

Description: Get Wiki name of logged in user
Return: $wikiName Wiki Name, e.g. "JohnDoe"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getWikiUserName( $text ) ==> $wikiName

Description: Get Wiki name of logged in user with web prefix
Return: $wikiName Wiki Name, e.g. "Main.JohnDoe"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

wikiToUserName( $wikiName ) ==> $loginName

Description: Translate a Wiki name to a login name based on Main.TWikiUsers topic
Parameter: $wikiName Wiki name, e.g. "Main.JohnDoe" or "JohnDoe"
Return: $loginName Login name of user, e.g. "jdoe"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

userToWikiName( $loginName, $dontAddWeb ) ==> $wikiName

Description: Translate a login name to a Wiki name based on Main.TWikiUsers topic
Parameter: $loginName Login name, e.g. "jdoe"
Parameter: $dontAddWeb Do not add web prefix if "1"
Return: $wikiName Wiki name of user, e.g. "Main.JohnDoe" or "JohnDoe"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

isGuest( ) ==> $flag

Description: Test if logged in user is a guest
Return: $flag "1" if yes, "0" if not
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

permissionsSet( $web ) ==> $flag

Description: Test if any access restrictions are set for this web, ignoring settings on individual pages
Parameter: $web Web name, required, e.g. "Sandbox"
Return: $flag "1" if yes, "0" if no
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

checkAccessPermission( $type, $wikiName, $text, $topic, $web ) ==> $flag

Description: Check access permission for a topic based on the TWiki.TWikiAccessControl rules
Parameter: $type Access type, e.g. "VIEW", "CHANGE", "CREATE"
Parameter: $wikiName WikiName of remote user, i.e. "Main.PeterThoeny"
Parameter: $text Topic text, optional. If empty, topic $web.$topic is consulted
Parameter: $topic Topic name, required, e.g. "PrivateStuff"
Parameter: $web Web name, required, e.g. "Sandbox"
Return: $flag "1" if access may be granted, "0" if not
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

Functions: Content Handling

webExists( $web ) ==> $flag

Description: Test if web exists
Parameter: $web Web name, required, e.g. "Sandbox"
Return: $flag "1" if web exists, "0" if not
Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)

topicExists( $web, $topic ) ==> $flag

Description: Test if topic exists
Parameter: $web Web name, optional, e.g. "Main"
Parameter: $topic Topic name, required, e.g. "TokyoOffice", or "Main.TokyoOffice"
Return: $flag "1" if topic exists, "0" if not
Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)

getRevisionInfo($theWebName, $theTopic, $theRev, $attachment ) ==> ( $date, $user, $rev, $comment )

Description: Get revision info of a topic
Parameter: $theWebName Web name, optional, e.g. "Main"
Parameter: $theTopic Topic name, required, e.g. "TokyoOffice"
Parameter: $theRev revsion number, or tag name (can be in the format 1.2, or just the minor number)
Parameter: $attachment attachment filename
Return: ( $date, $user, $rev, $comment ) List with: ( last update date, login name of last user, minor part of top revision number ), e.g. ( 1234561, "phoeny", "5" )
$date in epochSec
$user  
$rev  
$comment WHAT COMMENT?
Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)

checkTopicEditLock( $web, $topic ) ==> ( $oopsUrl, $loginName, $unlockTime )

Description: Check if topic has an edit lock by a user
Parameter: $web Web name, e.g. "Main", or empty
Parameter: $topic Topic name, e.g. "MyTopic", or "Main.MyTopic"
Return: ( $oopsUrl, $loginName, $unlockTime ) The $oopsUrl for calling redirectCgiQuery(), user's $loginName, and estimated $unlockTime in minutes. The $oopsUrl and $loginName is empty if topic has no edit lock.
Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)

setTopicEditLock( $web, $topic, $lock ) ==> $oopsUrl

Description: Lock topic for editing, or unlock when done
Parameter: $web Web name, e.g. "Main", or empty
Parameter: $topic Topic name, e.g. "MyTopic", or "Main.MyTopic"
Parameter: $lock Set to 1 to lock topic, 0 to unlock
Return: $oopsUrl Empty string if OK; the $oopsUrl for calling redirectCgiQuery() in case lock is already taken when trying to lock topic
Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)

readTopicText( $web, $topic, $rev, $ignorePermissions ) ==> $text

Description: Read topic text, including meta data
Parameter: $web Web name, e.g. "Main", or empty
Parameter: $topic Topic name, e.g. "MyTopic", or "Main.MyTopic"
Parameter: $rev Topic revision to read, optional. Specify the minor part of the revision, e.g. "5", not "1.5"; the top revision is returned if omitted or empty.
Parameter: $ignorePermissions Set to "1" if checkAccessPermission() is already performed and OK; an oops URL is returned if user has no permission
Return: $text Topic text with embedded meta data; an oops URL for calling redirectCgiQuery() is returned in case of an error
Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)

saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) ==> $oopsUrl

Description: Save topic text, typically obtained by readTopicText(). Topic data usually includes meta data; the file attachment meta data is replaced by the meta data from the topic file if it exists.
Parameter: $web Web name, e.g. "Main", or empty
Parameter: $topic Topic name, e.g. "MyTopic", or "Main.MyTopic"
Parameter: $text Topic text to save, assumed to include meta data
Parameter: $ignorePermissions Set to "1" if checkAccessPermission() is already performed and OK
Parameter: $dontNotify Set to "1" if not to notify users of the change
Return: $oopsUrl Empty string if OK; the $oopsUrl for calling redirectCgiQuery() in case of error
Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)

getPublicWebList( ) ==> @webs

Description: Get list of all public webs, e.g. all webs that do not have the NOSEARCHALL flag set in the WebPreferences
Return: @webs List of all public webs, e.g. ( "Main",  "Know", "TWiki" )
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getTopicList( $web ) ==> @topics

Description: Get list of all topics in a web
Parameter: $web Web name, required, e.g. "Sandbox"
Return: @topics Topic list, e.g. ( "WebChanges",  "WebHome", "WebIndex", "WebNotify" )
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

Functions: Rendering

expandCommonVariables( $text, $topic, $web ) ==> $text

Description: Expand all common %VARIABLES%
Parameter: $text Text with variables to expand, e.g. "Current user is %WIKIUSER%"
Parameter: $topic Current topic name, e.g. "WebNotify"
Parameter: $web Web name, optional, e.g. "Main". The current web is taken if missing
Return: $text Expanded text, e.g. "Current user is TWikiGuest"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

renderText( $text, $web ) ==> $text

Description: Render text from TWiki markup into XHTML as defined in TWiki.TextFormattingRules
Parameter: $text Text to render, e.g. "*bold* text and =fixed font="
Parameter: $web Web name, optional, e.g. "Main". The current web is taken if missing
Return: $text XHTML text, e.g. "<b>bold</b> and <code>fixed font</code>"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) ==> $text

Description: Render topic name and link label into an XHTML link. Normally you do not need to call this funtion, it is called internally by renderText()
Parameter: $pre Text occuring before the TWiki link syntax, optional
Parameter: $web Web name, required, e.g. "Main"
Parameter: $topic Topic name to link to, required, e.g. "WebNotify"
Parameter: $label Link label, required. Usually the same as $topic, e.g. "notify"
Parameter: $anchor Anchor, optional, e.g. "#Jump"
Parameter: $createLink Set to "1" to add question linked mark after topic name if topic does not exist;
set to "0" to suppress link for non-existing topics
Return: $text XHTML anchor, e.g. "<a href="/cgi-bin/view/Main/WebNotify#Jump">notify</a>"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

search text( $text ) ==> $text

Description: This is not a function, just a how-to note. Use: expandCommonVariables("%SEARCH{...}%" );
Parameter: $text Search variable
Return: $text Search result in TWiki.FormattedSearch format

formatTime( $time, $format, $timezone ) ==> $text

Description: Format the time in seconds into the desired time string
Parameter: $time Time in epoc seconds
Parameter: $format Format type, optional. Default e.g. " TWiki::Plugins::VERSION 1.010 (31 Dec 2002) - 19:30", can be "iso" (e.g. "2002-12-31T19:30Z"), "rcs" (e.g. "2001/12/31 23:59:59", "http" for HTTP header format (e.g. "Thu, 23 Jul 1998 07:21:56 GMT")
Parameter: $timezone either not defined (uses the displaytime setting), "gmtime", or "servertime"
Return: $text Formatted time string
Note: if you used the removed formatGmTime, add a third parameter "gmtime"
Since: TWiki::Plugins::VERSION 1.020 (26 Feb 2004)

formatGmTime( $time, $format ) ==> $text

NOTE: This function is deprecated and should not be used. Use formatTime() instead
Description: Format the time to GM time
Parameter: $time Time in epoc seconds
Parameter: $format Format type, optional. Default e.g. "31 Dec 2002 - 19:30", can be "iso" (e.g. "2002-12-31T19:30Z"), "rcs" (e.g. "2001/12/31 23:59:59", "http" for HTTP header format (e.g. "Thu, 23 Jul 1998 07:21:56 GMT")
Return: $text Formatted time string
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

Functions: File I/O

getDataDir( ) ==> $dir

Description: Get data directory (topic file root)
Return: $dir Data directory, e.g. "/twiki/data"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getPubDir( ) ==> $dir

Description: Get pub directory (file attachment root). Attachments are in $dir/Web/TopicName
Return: $dir Pub directory, e.g. "/htdocs/twiki/pub"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

readTopic( $web, $topic ) ==> ( $meta, $text )

NOTE: The following function is deprecated and should not be used. Use readTopicText() instead
Description: Read topic text and meta data, regardless of access permissions.
Parameter: $web Web name, required, e.g. "Main"
Parameter: $topic Topic name, required, e.g. "TokyoOffice"
Return: ( $meta, $text ) Meta data object and topic text
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

readTemplate( $name, $skin ) ==> $text

Description: Read a template or skin file. Embedded template directives get expanded
Parameter: $name Template name, e.g. "view"
Parameter: $skin Skin name, optional, e.g. "print"
Return: $text Template text
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

readFile( $filename ) ==> $text

Description: Read text file, low level. NOTE: For topics use readTopicText()
Parameter: $filename Full path name of file
Return: $text Content of file
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

saveFile( $filename, $text )

Description: Save text file, low level. NOTE: For topics use saveTopicText()
Parameter: $filename Full path name of file
Parameter: $text Text to save
Return: none
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
TODO: This should return an error for the different failure modes.

writeWarning( $text )

Description: Log Warning that may require admin intervention to data/warning.txt
Parameter: $text Text to write; timestamp gets added
Return: none
Since: TWiki::Plugins::VERSION 1.020 (16 Feb 2004)

writeDebug( $text )

Description: Log debug message to data/debug.txt
Parameter: $text Text to write; timestamp gets added
Return: none
Since: TWiki::Plugins::VERSION 1.020 (16 Feb 2004)

Functions: System and I18N related

getRegularExpression( $regexName ) ==> $pattern

Description: Retrieves a TWiki predefined regular expression
Parameter: $regexName Name of the regular expression to retrieve. See notes below
Return: String or precompiled regular expression matching as described below
Since: TWiki::Plugins::VERSION 1.020 (9 Feb 2004)

Notes: TWiki internally precompiles several regular expressions to represent various string entities in an I18N-compatible manner. Plugins are encouraged to use these in matching where appropriate. The following are guaranteed to be present; others may exist, but their use is unsupported and they may be removed in future TWiki versions. Those which are marked "CC" are for use within character classes and may not produce the desired results outside of them.

Name Matches CC
upperAlpha Upper case characters Y
lowerAlpha Lower case characters Y
mixedAlpha Alphabetic characters Y
mixedAlphaNum Alphanumeric charactecs Y
wikiWordRegex WikiWords N

Example: 

   my $upper = TWiki::Func::getRegularExpression("upperAlpha");
   my $alpha = TWiki::Func::getRegularExpression("mixedAlpha");
   my $capitalized = qr/[$upper][$alpha]+/;

checkDependencies( $moduleName, $dependenciesRef ) ==> $error

Description: Checks a list of Perl dependencies at runtime
Parameter: $moduleName Context description e.g. name of the module being checked
Parameter: $dependenciesRef Reference of list of hashes containing dependency information; see notes below
Return: $error undef if dependencies are OK, an error message otherwise
Since: TWiki::Plugins::VERSION 1.025 (01 Aug 2004)

The dependencies are expressed as a list of hashes. Each hash contains the name of a package and (optionally) a boolean constraint on the VERSION variable in that package. It is usually used from the initPlugin method like this: 

   if( $TWiki::Plugins::VERSION >= 1.025 ) {
      my @deps = (
            { package => 'TWiki::Plugins::CalendarPlugin', constraint => '>= 5.030' },
            { package => 'Time::ParseDate' },
            { package => 'Apache::VMonitor' }
      );
      my $err = TWiki::Func::checkDependencies( $pluginName, \@deps );
      if( $err ) {
            TWiki::Func::writeWarning( $err );
            print STDERR $err; # print to webserver log file
            return 0; # plugin initialisation failed
      }
   }

Copyright and License

Copyright (C) 2000-2004 Peter Thoeny, Peter@Thoeny.com

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details, published at http://www.gnu.org/copyleft/gpl.html

NOTE: Above text is copied from the TWiki::Plugins/PerlDocPlugin output of TWiki::Func in twiki format. In case you want to get dynamically updated documentation based on the actual Perl module, install the PerlDocPlugin and replace above text with %PERLDOC{"TWiki::Func"}%.

-- PeterThoeny? - 31 Dec 2002

TWiki Site Tools

Utilities for searching, navigation, and monitoring site activity

TWikiSiteTools include utilities for navigating, searching and keeping up with site activity. Preferences can be configured by web or site-wide. You are currently in the TWiki web. In particular, TWiki provides two highly configurable, automated site monitoring tools, WebNotify, to email alerts when topics are edited, and WebStats, to generate detailed activity reports.

WebNotify Recent Changes Alert

Each TWiki web has an automatic email alert service that sends a list of recent changes on a preset schedule, like once a day. Users can subscribe and unsubscribe using WebNotify in each web. The Perl script mailnotify is called by a background process at regular intervals. The script sends an automated email to subscribed users if topics were changed in a web since the script was last run.

Format: TWiki handles entries in bullet list (<space><space><space>*) format containing the WikiName of a user; a WikiName with e-mail address; or a TWikiGroup. Examples:

The first entry is the default form, the notification gets sent to the e-mail address specified in the user's home page. The second entry lists an alternative e-mail address. The third entry specifies a group, the notification gets sent to each member of the group.

You can also use %MAINWEB% instead of Main, but this is not necessary even if you have renamed the main web by configuring $mainWebname in TWiki.cfg.

Configuring Outgoing Mail

TWiki will use the Net::SMTP module if it is installed on your system. Set this with the SMTPMAILHOST variable in TWikiPreferences.

The notify e-mail uses the default changes.tmpl template, or a skin if activated in the TWikiPreferences.

mailnotify also relies on two hidden files in each TWiki/data/[web] directory: .changes and .mailnotify. Make sure both are writable by your web server process. .changes contains a list of changes; go ahead and make this empty. .mailnotify contains a timestamp of the last time notification was done.

You can use an external mail program, like sendmail, if the Net::SMTP module is not installed. Set the program path in $mailProgram in TWiki.cfg.

Setting the Automatic Email Schedule

For Unix platforms: Edit the cron table so that mailnotify is called in an interval of your choice. Please consult man crontab of how to modify the table that schedules program execution at certain intervals. Example: 

% crontab -e
0 2 * * * (cd /path/to/twiki/bin; ./mailnotify -q)
The above line will run mailnotify nightly at 02:00. The -q switch suppresses all normal output.

For ISP installations: Many ISPs don't allow hosted accounts direct cron access, as it's often used for things that can heavily load the server. Workaround scripts are available.

On Windows NT/2000: You can use a scheduled task if you have administrative privileges. Note: AT on an NT machine is pretty limited. Microsoft lists several third-party replacements. TWiki:Codev/CronTabWin is a free scheduler for Windows.

WebStatistics Site Usage Log

You can generate a listing manually, or on an automated schedule, of visits to individual pages, on a per web basis. Compiled as a running total on a monthly basis. Includes totals for Topic Views, Topic Saves, Attachment Uploads, Most Popular Topics with number of views, and Top Contributors showing total of saves and attachment uploads. Previous months are saved.

Configuring for Automatic Operation

Generating Statistics Manually by URL

Log File Details

TWiki generates monthly log files which are used by the statistics

WebSearch

WebSearch is an extremely fast and flexible search facility, part of the core TWiki feature set. Options include:

See also: TWikiVariables for including hard-coded searches in text.

WebChanges

To check for the most recently edited topics while on-site, use the WebChanges link, usually located on the upper toolbar. It lists the most recently modified topics, newest first, along with the first couple of lines of the page content.

This is simply a preset SEARCH. The number of topics listed by the limit parameter.: 

%SEARCH{".*" web="TWiki" regex="on" nosearch="on" order="modified" 
reverse="on" limit="50"}%

WebIndex

WebIndex lists all web topics in alphabetical order, with the first couple of lines of text. This is simply a preset SEARCH: 

%SEARCH{"\.*" scope="topic" regex="on" nosearch="on"}%

-- TWiki:Main.MikeMannix - 01 Dec 2001
-- TWiki:Main.PeterThoeny - 28 Aug 2004

Managing Topics

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

Overview

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

How to Rename/Move/Delete a Topic

  1. Click on [More] (bottom right of page) on the topic to be changed, then, in the new screen, on [Rename/move]. You can now rename and/or move/delete in one operation:
  2. Move/Delete: Select the target web if other than the current web - choose Trash to delete a topic.
  3. Rename: Enter the new topic name - default is current name
    ALERT! NOTE: You'll be warned if any of the topics to be affected are locked (being edited), or if there is a name conflict.
  4. Prevent updates by unchecking individual items on the list of referring links - these topics will NOT to be updated with the new name (by default, all referring links will be updated).
  5. Click on [Rename/Move]: the topic will be renamed and links to the topic updated as requested.

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.

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.
  2. The topic is moved (if locks allow).
  3. References are changed (locks and permissions permitting).
  4. Any referring topics that can't be changed due to locks are listed - user can take note and change them at another time.

How Referring Topics Are Found

Referring topics are found using the %SEARCH% variable - see the template searchrenameview.tmpl. First, matching topics in the current web are listed - matches are to topic. Next, all webs (including the current one) are listed that match web.topic. Because %SEARCH% is used, webs marked in WebPreferences as NOSEARCHALL will not show up in the search for references to the topic being changed.

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

Effect of User Access Settings

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

Special Considerations

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

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

Known Issues

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

The following shows some limitations of square bracket processing. 

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

-- TWiki:Main.MikeMannix - 27 Dec 2001

Managing Webs

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

Overview

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

Choose Web Template

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

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

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

Adding a New Web

Create a new web by filling out this form. Note: It is not recommended to create a new web for each little project. You can organize content within a web using TWikiForms and FormattedSearch. Cross-linking topics and search is easier if there are only a few larger webs.
Name of new web: Enter a short name of up to 10 characters. The name must start with an upper case letters, followed by optional upper or lower case letters or numbers
Based on web: Select a TemplateWeb
Web color: Enter a StandardColors code for the web
Description:
 
 
Enter a short description of the web. Write Web.TopicName instead of just TopicName if you include links. This will list the web in the SiteMap (leave field empty if you prefer not to update the directory.)
Use to...
 
Continue the sentence describing the intended use. This is also for the SiteMap
Exclude web from "search all": No   Yes Specify if you want to exclude the web from a "search all webs" search. Note that the SiteMap will not list the web if you select Yes.
 

Notes:

Renaming or Deleting a Web

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

  1. Prepare your site: Search each web for links to the target web, searching topic text for Oldwebname., including the dot so you'll find references like Oldwebname.SomeTopic
  2. Edit the TWikiPreferences topic: Rename or delete the web from the WIKIWEBLIST variable
  3. Login to the TWiki server, via Telnet or FTP
  4. Go to twiki/data and rename or remove the web directory
  5. Go to twiki/templates and rename or remove the web directory if present
  6. Go to twiki/pub and rename or remove the web directory if present

Renaming the MAINWEB

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

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

Manage Users

Register users on your TWiki site; change/reset/install passwords; remove user accounts

Authentication and Access Control

Register User

Change, Reset and Install Passwords

Removing User Accounts

To remove a user account:

  1. Edit the data/.htpasswd file to delete their entry (only applies if you are using a .htpasswd file)
  2. Remove the FredQuimby line from the Main.TWikiUsers topic
  3. Remove user from all groups and from all the ALLOWWEB/ALLOWTOPIC... declarations, if any.
    Note: Otherwise this is a security hole as the first one to re-register with this name will be granted the permissions of the previous user.
  4. [optional] Remove their topic files: data/Main/FredQuimby.txt and data/Main/FredQuimby.txt,v

Note: Consider leaving the user topic file in place so their past signatures and revision author entries don't end up looking like AnUncreatedTopic?. If you want to make it clear the user is inactive on your site (e.g. PeterThoeny?) or has been banished add a note to that effect and write protect the page (TWikiAccessControl). The existance of the UserName topic prevent that user name from being re-used.

-- TWiki:Main.MattWilkie - 21 Jul 2003
-- TWiki:Main.PeterThoeny - 15 Aug 2004

Appendix A: TWiki Filesystem

Annotated directory and file listings, for the 01-Sep-2004 TWiki production release.

Who and What is This Good For?

Interested Users and Site Administrators can find out in simple terms what each part of TWiki actually does. Adventurous Adminstrators with server access to files (via telnet, ssh or ftp) can also figure out where to look to make minor modifications, like changing hardcode text or color. Software Developers can get an at-a-glance overview of TWiki code architecture.

Directory Structure

You can rename the root TWiki directory - twiki - to whatever you like by changing it in the TWiki.cfg configuration file. However, to keep the current installation and future upgrades simple, you should leave the five main subdirectories intact:

Directory: Files: Used for:
twiki list Start-up info
twiki/bin list Perl scripts
twiki/lib list Configuration file, main library, Perl system modules, Plugins directory
twiki/pub list Public files (eg: images) and FileAttachments and their RCS histories
twiki/data list Individual topics (page content) and their RCS histories
twiki/templates list HTML templates, used by TWiki scripts

File Descriptions

A rundown of the individual files included in the current distribution, organized by TWiki root directories.

Files in twiki

Application info and the current reference documentation. Full file list:

File Used for
index.html Links to launch TWiki after install and for files in this directory
license.txt GNU General Public License and TWiki-specific info
readme.txt General TWiki start-up info with relevant URLs
TWikiDocumentation.html All documentation packaged as a single page
TWikiHistory.html TWiki development timeline: versions, features, developers
TwikiUpgrade TWiki upgrade script (Beta state)

Files in twiki/bin

Perl CGI scripts. Full file list:

File: Used for:
.htaccess.txt Authentication. Rename to .htaccess and customize if used
attach Shows the attach file page (FileAttachment)
changes a simple WebChanges query
edit Edit a topic
geturl Fetch URL data
installpasswd Install new password by admin
mailnotify Script called by cron job to notify users of changes
manage Manage script to create new webs
oops Shows an OK or oops dialog
passwd Reset and change password
preview Preview topic after edit
rdiff See differences of topics
rdiffauth Copy of rdiff script (ideally a link). The .htaccess file sets this as requiring authorisation
register Register new users
rename Rename/move topics and move attachments
save Saves a topic, called by preview
search Displays search results
setlib.cfg Location of the TWiki libraries. Customize if needed
statistics Create statistics topic
testenv Test CGI environment variables
upload Does file upload (FileAttachment)
view View a topic (the script)
viewauth Copy of view script (ideally a link). The .htaccess file sets this as requiring authorisation
viewfile View a file attachment

Files under twiki/lib

The new lib/TWiki/Plugins directories contain configuration, library and function files, and TWikiPlugins. Full file list:

File: Used for:
TWiki.cfg Main configuration, used by TWiki.pm
TWiki.pm Main TWiki library
Algorithm/Diff.pm Diff library
Text/Diff.pm Diff library, used by TwikiUpgrade script
TWiki/Access.pm Access control
TWiki/Attach.pm Attachment handling
TWiki/Form.pm Form handling
TWiki/Func.pm Public functions that Plugins may use
TWiki/Meta.pm Meta data in topics
TWiki/Net.pm SMTP mail handling
TWiki/Plugins.pm Plugin handling
TWiki/Plugins/CommentPlugin.pm Plugin handling a comment box
TWiki/Plugins/CommentPlugin/Attrs.pm Supporting module for Comment Plugin
TWiki/Plugins/CommentPlugin/Comment.pm Supporting module for Comment Plugin
TWiki/Plugins/CommentPlugin/Templates.pm Supporting module for Comment Plugin
TWiki/Plugins/DefaultPlugin.pm Handles some legacy rules
TWiki/Plugins/EditTablePlugin.pm Plugin to edit tables
TWiki/Plugins/EmptyPlugin.pm Empty plugin, use to create your own
TWiki/Plugins/InterwikiPlugin.pm Use aliases as links for predefined URLs
TWiki/Plugins/RenderListPlugin.pm Plugin to render lists as nice trees
TWiki/Plugins/SlideShowPlugin.pm Plugin turning headings into slides
TWiki/Plugins/SmiliesPlugin.pm Plugin rendering smilies like :-)
TWiki/Plugins/SpreadSheetPlugin.pm Plugin resolving spreadsheet formulae
TWiki/Plugins/TablePlugin.pm Plugin to render tables nicely
TWiki/Prefs.pm Preferences handling
TWiki/Render.pm TWiki markup to HTML rendering
TWiki/Search.pm Search engine, used by TWiki.pm
TWiki/Store.pm Back-end storage, *.txt text file and *.txt,v RCS repository file handling
TWiki/Store/RcsFile.pm Generic file handling code, a class
TWiki/Store/RcsWrap.pm Wrappers around RCS executables, a class that inherits from RcsFile
TWiki/Store/RcsLite.pm A Perl RCS implemention, a class that inherits from RcsFile
TWiki/UI.pm User interface handling
TWiki/UI/Changes.pm Functionality of changes script
TWiki/UI/Edit.pm Functionality of edit script
TWiki/UI/Manage.pm Functionality of manage script
TWiki/UI/Oops.pm Functionality of oops script
TWiki/UI/Preview.pm Functionality of preview script
TWiki/UI/RDiff.pm Functionality of rdiff script
TWiki/UI/Save.pm Functionality of save script
TWiki/UI/Search.pm Functionality of search script
TWiki/UI/Statistics.pm Functionality of statistics script
TWiki/UI/Upload.pm Functionality of upload script
TWiki/UI/View.pm Functionality of view script
TWiki/UI/Viewfile.pm Functionality of viewfile script
TWiki/Upgrade/TWikiCfg.pm Supporting module of TwikiUpgrade script
TWiki/Upgrade/UpdateTopics.pm Supporting module of TwikiUpgrade script
TWiki/Upgrade/UpdateTopicsManualSymlinks.pm Supporting module of TwikiUpgrade script
TWiki/User.pm Abstraction package to allow plugable user authentication systems
TWiki/User/HtPasswdUser.pm Apache Htpasswd file implementation (the default)
TWiki/User/NoPasswdUser.pm simple, no users authentication (totally wiki)

Files under twiki/pub

The pub directory stores topic-related files, including images used by TWiki and FileAttachments. Attachments are stored in subdirectories created with the related topic name. You can also upload files directly for and link manually (but not through Attach) Partial file list:

File: Used for:
favicon.ico ICO file
wikiHome.gif GIF file
icn/_filetypes.txt Lookup table to translate file extension to file type
icn/bat.gif GIF file for file type
icn/bmp.gif GIF file for file type
... ...
TWiki/FileAttachment/Sample.txt TEXT file: sample
TWiki/FileAttachment/Smile.gif GIF image: sample
TWiki/FileAttachment/Smile.gif,v RCS repository for GIF file
TWiki/PreviewBackground/blankltgraybg.gif GIF image
TWiki/PreviewBackground/blankwhitebg.gif GIF image
TWiki/PreviewBackground/previewbg.gif GIF image: Preview view background
TWiki/PreviewBackground/preview2bg.gif GIF image: Alternate preview view background
TWiki/TWikiLogos/twikiRobot121x54.gif GIF image: TWiki logo
... ...
TWiki/TWikiTemplates/testscreen.gif GIF image: Screen shot
TWiki/WabiSabi/wabisabi.gif GIF image: illustration

Files under twiki/data

TWiki topics: data stored as individual text files and rendered by TWiki for display as regular Web pages. Each active web has its own subdirectory. The TWiki distribution includes a number of start-up webs - Main, TWiki, and Sandbox - with documentation and demo content, a Trash web for browser-based, recoverable topic deletion, and a _default directory containing a core topic set required to start a new web. Partial file list:

File: Used for:
.htpasswd Basic Authentication (htaccess) users file with username and encrypted password pairs
debug.txt Program-generated messages useful for debugging
mime.types Recognized file formats
warning.txt Diagnostic messages for identifying problems
_default/.changes Per web record of topic changes
_default/.mailnotify Per web timestamp of most recent email notification
_default/WebChanges.txt Display most recent topic changes in web
_default/WebChanges.txt,v Revisions history (RCS)
_default/WebHome.txt Default web home page
_default/WebHome.txt,v Revisions history (RCS)
_default/WebIndex.txt Lists all topics in a web
_default/WebIndex.txt,v Revisions history (RCS)
_default/WebLeftBar.txt Left navigation bar for PatternSkin?
_default/WebLeftBar.txt,v Revisions history (RCS)
_default/WebNotify.txt Subscribe/unsubscribe to web changes email alert
_default/WebNotify.txt,v Revisions history (RCS)
_default/WebPreferences.txt Per web Preference Settings
_default/WebPreferences.txt,v Revisions history (RCS)
_default/WebSearch.txt Per web search options
_default/WebSearch.txt,v Revisions history (RCS)
_default/WebStatistics.txt Generates web usage statistics
_default/WebStatistics.txt,v Revisions history (RCS)
_default/WebTopicList.txt Lists all topics in a web in compact format
_default/WebTopicList.txt,v Revisions history (RCS)
... ...

Files in twiki/templates

Templates and skins used to control appearance of topics rendered as Web pages. Partial file list:

File: Used for:
attach.tmpl Attachment (FileAttachments) control screen
attachagain.tmpl Attachment control screen for updating an existing attachment
attachnew.tmpl Attachment control screen for adding a new attachment
attachtables.tmpl Macros for definition of attachment tables
changeform.tmpl Control screen to change the form in edit mode
changes.tmpl Displays list of recently changed topics
edit.iejs.tmpl Edit window with IE-specific JavaScript
edit.tmpl Main edit window
mailnotify.tmpl Email notification
moveattachment.tmpl Move attachment control screen
oopsaccesschange.tmpl Error message
oopsaccessgroup.tmpl Error message
oopsaccessmanage.tmpl Error message
oopsaccessrename.tmpl Error message
oopsaccessview.tmpl Error message
oopsattachnotopic.tmpl Error message
oopsauth.tmpl Error message
oopsbadcharset.tmpl Error message
oopsbadpwformat.tmpl Error message
oopschangepasswd.tmpl Error message
oopscreatenewtopic.tmpl Error message
oopsempty.tmpl Error message
oopslocked.tmpl Error message
oopslockedrename.tmpl Error message
oopsmanage.tmpl Error message
oopsmissing.tmpl Error message
oopsmngcreateweb.tmpl Error message
oopsmore.tmpl More topic actions message
oopsmoveerr.tmpl Error message
oopsnoformdef.tmpl Error message
oopsnotwikiuser.tmpl Error message
oopsnoweb.tmpl Error message
oopspreview.tmpl Error message
oopsregemail.tmpl Error message
oopsregexist.tmpl Error message
oopsregpasswd.tmpl Error message
oopsregrequ.tmpl Error message
oopsregthanks.tmpl Error message
oopsregwiki.tmpl Error message
oopsremoveuserdone.tmpl Error message
oopsrenameerr.tmpl Error message
oopsrenamenotwikiword.tmpl Error message
oopsresetpasswd.tmpl Error message
oopsrev.tmpl Error message
oopssave.tmpl Error message
oopssaveerr.tmpl Error message
oopssendmailerr.tmpl Error message
oopstopicexists.tmpl Error message
oopsupload.tmpl Error message
oopsuploadlimit.tmpl Error message
oopswrongpassword.tmpl Error message
preview.tmpl Preview Changes screen
rdiff.tmpl Displays text changes before & after Diffs
registernotify.tmpl Registration notification
rename.tmpl Rename/move control screen (choose web & new topic tile
renamebase.tmpl Used by other rename templates
renameconfirm.tmpl Confirms a pre-specified rename, ex: undoing a rename
renamedelete.tmpl Confirms a delete
renamerefs.tmpl Display if rename done, but some references not changed (topics were locked)
search.tmpl Search screen
searchbookview.tmpl Search results with full topic content
searchformat.tmpl Search screen for formatted search
searchmeta.tmpl Search screen
searchrenameview.tmpl Used by rename to list references to topic being renamed
twiki.tmpl Master template: definitions are used by other templates
view.plain.tmpl Skin for bare bone topic view without header/footer but with HTML head and body tags
view.print.tmpl Skin for printable topic view with a simple header/footer
view.rss.tmpl Skin for topic view in RDF XML format
view.text.tmpl Skin for topic text only, without HTML head and body tags, and no form and attachments
view.tmpl Main topic view - the standard regular Web page

TWiki File System Snapshot

The following partial directory listings from a Linux installation show typical file permissions and ownership. This is provided for general debugging use only and isn't an exact representation of the current distribution.

Directory twiki/bin: 

drwxrwxr-x    2 twiki   twiki        4096 May  9 00:08 .
drwxrwxr-x    5 twiki   twiki        4096 Nov 18  2002 ..
-rw-rw-r--    1 twiki   twiki        3145 Jul 25 00:31 .htaccess.txt
-rwxrwxr-x    1 twiki   twiki        1459 May 28 23:51 attach
-rwxrwxr-x    1 twiki   twiki        1721 May 28 23:51 changes
-rwxrwxr-x    1 twiki   twiki        1994 May 28 23:51 edit
-rwxrwxr-x    1 twiki   twiki        1878 May 28 23:51 geturl
-rwxrwxr-x    1 twiki   twiki        6689 May 28 23:51 installpasswd
-rwxrwxr-x    1 twiki   twiki        7313 May 28 23:51 mailnotify
-rwxrwxr-x    1 twiki   twiki        3557 Jul 25 15:00 manage
-rwxrwxr-x    1 twiki   twiki        1448 May 28 23:51 oops
-rwxrwxr-x    1 twiki   twiki        4062 May 28 23:51 passwd
-rwxrwxr-x    1 twiki   twiki        1506 May 28 23:51 preview
-rwxrwxr-x    2 twiki   twiki        1490 May 28 23:51 rdiff
-rwxrwxr-x    2 twiki   twiki        1490 May 28 23:51 rdiffauth
-rwxrwxr-x    1 twiki   twiki        7635 May 28 23:51 register
-rwxrwxr-x    1 twiki   twiki        1774 May 28 23:51 rename
-rwxrwxr-x    1 twiki   twiki        1654 Jul 25 00:31 save
-rwxrwxr-x    1 twiki   twiki        1728 May 28 23:51 search
-rw-rw-r--    1 twiki   twiki        2131 Aug  7 21:13 setlib.cfg
-rwxrwxr-x    1 twiki   twiki        2596 May 28 23:51 statistics
-rwxrwxr-x    1 twiki   twiki       39926 Jul 25 15:00 testenv
-rwxrwxr-x    1 twiki   twiki        1478 May 28 23:51 upload
-rwxrwxr-x    2 twiki   twiki        1689 May 28 23:51 view
-rwxrwxr-x    2 twiki   twiki        1689 May 28 23:51 viewauth
-rwxrwxr-x    1 twiki   twiki        1438 May 28 23:51 viewfile

Directory twiki/templates/: 

drwxrwxr-x    2 twiki   twiki        4096 Aug  7 19:09 .
drwxrwxr-x    4 twiki   twiki        4096 Aug  7 21:13 ..
-rw-rw-r--    1 twiki   users        2077 Aug 13 22:21 attachagain.pattern.tmpl
-rw-rw-r--    1 twiki   users        1650 Aug 13 22:21 attachagain.tmpl
-rw-rw-r--    1 twiki   twiki        2556 Jul 27 10:47 attach.dragon.tmpl
-rw-rw-r--    1 twiki   users         567 Jul 28 19:52 attachnew.pattern.tmpl
-rw-rw-r--    1 twiki   users         470 Jul 28 19:52 attachnew.tmpl
-rw-rw-r--    1 twiki   users        2855 Aug  8 03:40 attach.pattern.tmpl
-rw-rw-r--    1 twiki   users        1991 Aug  3 13:09 attachtables.pattern.tmpl
-rw-rw-r--    1 twiki   users        1869 Jul 27 22:03 attachtables.tmpl
-rw-rw-r--    1 twiki   users        2355 Jul 28 19:52 attach.tmpl
-rw-rw-r--    1 twiki   twiki        1324 Jul 27 10:47 changeform.dragon.tmpl
-rw-rw-r--    1 twiki   twiki        1441 Aug  6 11:47 changeform.pattern.tmpl
-rw-rw-r--    1 twiki   twiki        1032 Jul 28 19:52 changeform.tmpl
-rw-rw-r--    1 twiki   twiki        1870 Jul 27 10:47 changes.dragon.tmpl
-rw-rw-r--    1 twiki   twiki         433 Jul 31 12:39 changes.pattern.tmpl
-rw-rw-r--    1 twiki   twiki        1196 May 28 23:51 changes.tmpl
-rw-rw-r--    1 twiki   twiki          35 May 21 03:56 comments.tmpl
-rw-rw-r--    1 twiki   twiki         526 Jul 27 10:47 dragoncssvars.dragon.tmpl
-rw-rw-r--    1 twiki   twiki        1645 Jul 31 00:57 dragonmenu.dragon.tmpl
-rw-rw-r--    1 twiki   twiki        4207 Jul 27 10:47 edit.dragon.tmpl
-rw-rw-r--    1 twiki   twiki       12608 Jul 28 19:52 edit.iejs.tmpl
-rw-rw-r--    1 twiki   twiki        4904 Aug  7 17:48 edit.pattern.tmpl
-rw-rw-r--    1 twiki   twiki        3975 Aug  8 03:40 edit.tmpl
-rw-rw-r--    1 twiki   twiki         993 May 28 23:51 mailnotify.tmpl
-rw-rw-r--    1 twiki   twiki        1640 Jul 27 10:47 moveattachment.dragon.tmpl
-rw-rw-r--    1 twiki   twiki        1968 Aug  7 17:48 moveattachment.pattern.tmpl
-rw-rw-r--    1 twiki   twiki        1342 Jul 28 19:52 moveattachment.tmpl
-rw-rw-r--    1 twiki   twiki         571 May 28 23:51 oopsaccesschange.tmpl
-rw-rw-r--    1 twiki   twiki         587 May 28 23:51 oopsaccessgroup.tmpl
-rw-rw-r--    1 twiki   twiki         597 Aug  2 11:10 oopsaccessmanage.tmpl
-rw-rw-r--    1 twiki   twiki         572 May 28 23:51 oopsaccessrename.tmpl
-rw-rw-r--    1 twiki   twiki         574 May 28 23:51 oopsaccessview.tmpl
-rw-rw-r--    1 twiki   twiki         571 Aug  2 11:10 oopsattachnotopic.tmpl
-rw-rw-r--    1 twiki   twiki         998 May 28 23:51 oopsauth.tmpl
-rw-rw-r--    1 twiki   twiki         646 May 28 23:51 oopsbadcharset.tmpl
-rw-rw-r--    1 twiki   twiki         406 May 28 23:51 oopsbadpwformat.tmpl
-rw-rw-r--    1 twiki   twiki         345 May 28 23:51 oopschangepasswd.tmpl
-rw-rw-r--    1 twiki   twiki         382 May 28 23:51 oopscreatenewtopic.tmpl
-rw-rw-r--    1 twiki   twiki         627 Jul  7 23:11 oopsempty.tmpl
-rw-rw-r--    1 twiki   twiki         927 Aug  3 13:09 oopslocked.pattern.tmpl
-rw-rw-r--    1 twiki   twiki         612 Aug  2 11:10 oopslockedrename.pattern.tmpl
-rw-rw-r--    1 twiki   twiki         596 Aug  2 11:10 oopslockedrename.tmpl
-rw-rw-r--    1 twiki   twiki         910 Aug  3 13:09 oopslocked.tmpl
-rw-rw-r--    1 twiki   twiki         679 May 28 23:51 oopsmanage.tmpl
-rw-rw-r--    1 twiki   twiki         329 May 28 23:51 oopsmissing.tmpl
-rw-rw-r--    1 twiki   twiki        2353 May 28 23:51 oopsmngcreateweb.tmpl
-rw-rw-r--    1 twiki   twiki        2987 Aug  3 13:09 oopsmore.tmpl
-rw-rw-r--    1 twiki   twiki         418 May 28 23:51 oopsmoveerr.tmpl
-rw-rw-r--    1 twiki   twiki        1133 May 28 23:51 oopsnoformdef.tmpl
-rw-rw-r--    1 twiki   twiki         521 May 28 23:51 oopsnotwikiuser.tmpl
-rw-rw-r--    1 twiki   twiki        1516 Jul 28 19:52 oopsnoweb.tmpl
-rw-rw-r--    1 twiki   twiki         394 May 28 23:51 oopspreview.tmpl
-rw-rw-r--    1 twiki   twiki         341 May 28 23:51 oopsregemail.tmpl
-rw-rw-r--    1 twiki   twiki         411 May 28 23:51 oopsregerr.tmpl
-rw-rw-r--    1 twiki   twiki         476 May 28 23:51 oopsregexist.tmpl
-rw-rw-r--    1 twiki   twiki         346 May 28 23:51 oopsregpasswd.tmpl
-rw-rw-r--    1 twiki   twiki         357 May 28 23:51 oopsregrequ.tmpl
-rw-rw-r--    1 twiki   twiki         541 May 28 23:51 oopsregthanks.tmpl
-rw-rw-r--    1 twiki   twiki         680 May 28 23:51 oopsregwiki.tmpl
-rw-rw-r--    1 twiki   twiki         587 May 28 23:51 oopsremoveuserdone.tmpl
-rw-rw-r--    1 twiki   twiki         503 May 28 23:51 oopsrenameerr.tmpl
-rw-rw-r--    1 twiki   twiki         434 May 28 23:51 oopsrenamenotwikiword.tmpl
-rw-rw-r--    1 twiki   twiki         507 May 28 23:51 oopsresetpasswd.tmpl
-rw-rw-r--    1 twiki   twiki         962 Jul 28 19:52 oopsrev.tmpl
-rw-rw-r--    1 twiki   twiki         483 May 28 23:51 oopssaveerr.tmpl
-rw-rw-r--    1 twiki   twiki         777 Jul  7 23:11 oopssave.tmpl
-rw-rw-r--    1 twiki   twiki         466 May 28 23:51 oopssendmailerr.tmpl
-rw-rw-r--    1 twiki   twiki         385 May 28 23:51 oopstopicexists.tmpl
-rw-rw-r--    1 twiki   twiki         344 May 28 23:51 oopsuploadlimit.tmpl
-rw-rw-r--    1 twiki   twiki         343 May 28 23:51 oopsupload.tmpl
-rw-rw-r--    1 twiki   twiki         365 May 28 23:51 oopswrongpassword.tmpl
-rw-rw-r--    1 twiki   twiki        3590 Jul 27 10:47 preview.dragon.tmpl
-rw-rw-r--    1 twiki   twiki        2855 Aug  6 11:47 preview.pattern.tmpl
-rw-rw-r--    1 twiki   twiki        2253 Aug  8 03:40 preview.tmpl
-rw-rw-r--    1 twiki   twiki        1739 Jul 27 10:47 rdiff.dragon.tmpl
-rw-rw-r--    1 twiki   users        1529 Aug 13 22:21 rdiff.pattern.tmpl
-rw-rw-r--    1 twiki   users        1299 May 28 23:51 rdiff.tmpl
-rw-rw-r--    1 twiki   twiki        1159 Jul 31 12:39 registernotify.pattern.tmpl
-rw-rw-r--    1 twiki   twiki        1160 May 28 23:51 registernotify.tmpl
-rw-rw-r--    1 twiki   twiki        2561 Jul 27 10:47 renamebase.dragon.tmpl
-rw-rw-r--    1 twiki   twiki        3363 Aug  8 03:40 renamebase.pattern.tmpl
-rw-rw-r--    1 twiki   twiki        2279 Jul 28 20:54 renamebase.tmpl
-rw-rw-r--    1 twiki   twiki         718 Jul 31 12:39 renameconfirm.pattern.tmpl
-rw-rw-r--    1 twiki   twiki         570 Jul 28 19:52 renameconfirm.tmpl
-rw-rw-r--    1 twiki   twiki        1046 Jul 31 12:39 renamedelete.pattern.tmpl
-rw-rw-r--    1 twiki   twiki         932 Jul 28 19:52 renamedelete.tmpl
-rw-rw-r--    1 twiki   twiki        1147 Jul 31 12:39 rename.pattern.tmpl
-rw-rw-r--    1 twiki   twiki         766 Jul 28 19:52 renamerefs.pattern.tmpl
-rw-rw-r--    1 twiki   twiki         616 Jul 28 19:52 renamerefs.tmpl
-rw-rw-r--    1 twiki   twiki        1041 Jul 28 19:52 rename.tmpl
-rw-rw-r--    1 twiki   twiki        1397 Jul 27 10:47 searchbookview.dragon.tmpl
-rw-rw-r--    1 twiki   twiki         723 Jul 31 12:39 searchbookview.pattern.tmpl
-rw-rw-r--    1 twiki   twiki        1230 May 28 23:51 searchbookview.tmpl
-rw-rw-r--    1 twiki   twiki        1705 Jul 27 10:47 search.dragon.tmpl
-rw-rw-r--    1 twiki   twiki         722 Jul 27 10:47 searchformat.dragon.tmpl
-rw-rw-r--    1 twiki   twiki         157 Jul 31 12:39 searchformat.pattern.tmpl
-rw-rw-r--    1 twiki   twiki         529 May 28 23:51 searchformat.tmpl
-rw-rw-r--    1 twiki   twiki         149 Jul  7 23:03 searchmeta.pattern.tmpl
-rw-rw-r--    1 twiki   twiki         149 May 28 23:51 searchmeta.tmpl
-rw-rw-r--    1 twiki   twiki        1638 Aug  7 17:48 search.pattern.tmpl
-rw-rw-r--    1 twiki   twiki        1892 Jul 27 10:47 searchrenameview.dragon.tmpl
-rw-rw-r--    1 twiki   twiki        1208 Aug  3 13:09 searchrenameview.pattern.tmpl
-rw-rw-r--    1 twiki   twiki        1615 May 28 23:51 searchrenameview.tmpl
-rw-rw-r--    1 twiki   twiki        1364 May 28 23:51 search.tmpl
-rw-rw-r--    1 twiki   twiki        3836 Jul 27 10:47 twiki.dragon.tmpl
-rw-rw-r--    1 twiki   twiki        3175 Aug  7 17:48 twiki.pattern.tmpl
-rw-rw-r--    1 twiki   twiki        2798 Jul 27 22:57 twiki.tmpl
-rw-rw-r--    1 twiki   twiki        1324 Jul 27 10:47 view.dragon.tmpl
-rw-rw-r--    1 twiki   twiki        3577 Aug  8 03:40 view.pattern.tmpl
-rw-rw-r--    1 twiki   twiki         425 May 28 23:51 view.plain.tmpl
-rw-rw-r--    1 twiki   twiki        1056 Jul 31 12:39 view.print.pattern.tmpl
-rw-rw-r--    1 twiki   twiki         845 May 28 23:51 view.print.tmpl
-rw-rw-r--    1 twiki   twiki         300 May 28 23:51 view.rss.tmpl
-rw-rw-r--    1 twiki   twiki           8 May 28 23:51 view.text.tmpl
-rw-rw-r--    1 twiki   twiki        1281 Jul 31 12:39 view.tmpl

Directory twiki/data/: 

drwxrwxr-x    7 nobody  twiki        4096 Aug  7 21:13 .
drwxrwxr-x    4 twiki   twiki        4096 Aug  7 21:13 ..
-rw-rw-rw-    1 twiki   twiki           0 Feb  1  2003 debug.txt
drwxrwxr-x    2 nobody  twiki        4096 Jul 16 00:36 _default
-rw-rw-r--    1 twiki   twiki          25 Dec 16  2003 .htpasswd.txt
-rw-rw-r--    1 nobody  nobody      11811 Aug 13 23:10 log200408.txt
drwxrwxr-x    2 nobody  twiki        4096 Aug  4 21:03 Main
-rw-rw-r--    1 twiki   twiki        3419 Aug 13  2001 mime.types
drwxrwxr-x    2 nobody  twiki        4096 Aug  7 21:03 Sandbox
drwxrwxr-x    2 nobody  twiki        4096 Jul 20 18:15 Trash
drwxrwxr-x    2 nobody  twiki       12288 Aug 13 23:10 TWiki
-rw-rw-rw-    1 twiki   twiki           0 Aug  7 18:03 warning.txt

Partial file list for twiki/data/Main: 

drwxrwxr-x    2 nobody  twiki        4096 Aug  4 21:03 .
drwxrwxr-x    7 nobody  twiki        4096 Aug  7 21:13 ..
-rw-rw-rw-    1 twiki   twiki        3743 Aug  4 21:03 .changes
-rw-rw-rw-    1 twiki   twiki           9 Oct 25  2001 .mailnotify
-rw-r--r--    1 nobody  nobody        518 Dec 16  2003 TWikiAdminGroup.txt
-r--r--r--    1 nobody  nobody       2453 Dec 16  2003 TWikiAdminGroup.txt,v
-rw-r--r--    1 nobody  nobody       1668 Aug  4 21:03 TWikiGroups.txt
-r--r--r--    1 nobody  nobody       3421 Aug  4 21:03 TWikiGroups.txt,v
-rw-r--r--    1 nobody  nobody        686 Dec 13  2000 TWikiGuest.txt
-rw-r--r--    1 nobody  nobody       1995 Dec 13  2000 TWikiGuest.txt,v
-rw-r--r--    1 nobody  nobody        319 Dec 20  2003 TWikiPreferences.txt
-r--r--r--    1 nobody  nobody        508 Dec 20  2003 TWikiPreferences.txt,v
-rw-r--r--    1 nobody  nobody       1812 Feb 20 13:54 TWikiUsers.txt
-r--r--r--    1 nobody  nobody       9222 Feb 20 13:54 TWikiUsers.txt,v
-rw-r--r--    1 nobody  nobody        119 Jan 11  2003 TWikiVariables.txt
-r--r--r--    1 nobody  nobody        742 Jan 11  2003 TWikiVariables.txt,v
-rw-r--r--    1 nobody  nobody        124 Aug 16  2001 WebChanges.txt
-r--r--r--    1 nobody  nobody        526 Aug 16  2001 WebChanges.txt,v
-rw-r--r--    1 nobody  nobody       1842 Feb  1  2003 WebHome.txt
-r--r--r--    1 nobody  nobody      11862 Feb  1  2003 WebHome.txt,v
-rw-r--r--    1 nobody  nobody        176 Nov 24  2001 WebIndex.txt
-r--r--r--    1 nobody  nobody        483 Nov 24  2001 WebIndex.txt,v
-rw-r--r--    1 nobody  nobody        922 Feb  3  2003 WebNotify.txt
-r--r--r--    1 nobody  nobody       4303 Feb  3  2003 WebNotify.txt,v
-rw-r--r--    1 nobody  nobody       3738 Dec 25  2003 WebPreferences.txt
-r--r--r--    1 nobody  nobody      10697 Dec 25  2003 WebPreferences.txt,v
-rw-r--r--    1 nobody  nobody        416 Jan 30  2003 WebRss.txt
-r--r--r--    1 nobody  nobody        605 Jan 30  2003 WebRss.txt,v
-rw-r--r--    1 nobody  nobody        164 Jan 18  2004 WebSearchAdvanced.txt
-r--r--r--    1 nobody  nobody        353 Jan 18  2004 WebSearchAdvanced.txt,v
-rw-r--r--    1 nobody  nobody        158 Aug  7  2001 WebSearch.txt
-r--r--r--    1 nobody  nobody      18332 Aug  7  2001 WebSearch.txt,v
-rw-r--r--    1 nobody  nobody        825 Jul 16 00:32 WebStatistics.txt
-r--r--r--    1 nobody  nobody       4226 Jul 16 00:32 WebStatistics.txt,v
-rw-r--r--    1 nobody  nobody        182 Nov 24  2001 WebTopicList.txt
-r--r--r--    1 nobody  nobody        371 Nov 24  2001 WebTopicList.txt,v

Directory twiki/pub/: 

drwxrwxr-x    8 nobody  nobody       4096 Nov 18 12:31 .
drwxrwxr-x    3 twiki   twiki        4096 Nov 18 12:31 ..
drwxrwxr-x    2 nobody  nobody       4096 Apr  7  2002 Main
drwxrwxr-x    2 nobody  nobody       4096 Apr 20  2002 Sandbox
drwxrwxr-x    8 nobody  nobody       4096 Nov 18 12:31 TWiki
drwxrwxr-x    2 nobody  nobody       4096 Dec  3  2001 Trash
-rw-rw-r--    1 twiki   twiki        1078 Jan 14  2000 favicon.ico
drwxrwxr-x    2 twiki   twiki        4096 Nov 18 12:31 icn
-rw-rw-r--    1 twiki   twiki        2877 Jun  7  1999 wikiHome.gif

Partial file list for twiki/pub/icn/: 

drwxrwxr-x    2 twiki   twiki        4096 Nov 18 12:31 .
drwxrwxr-x    8 nobody  nobody       4096 Nov 18 12:31 ..
-rw-rw-r--    1 twiki   twiki         801 Mar 26  1999 _filetypes.txt
-rw-rw-r--    1 twiki   twiki         143 Mar  9  1999 bat.gif
-rw-rw-r--    1 twiki   twiki         926 Mar  9  1999 bmp.gif
-rw-rw-r--    1 twiki   twiki         141 Mar 25  1999 c.gif
-rw-rw-r--    1 twiki   twiki         144 Mar  9  1999 dll.gif
-rw-rw-r--    1 twiki   twiki         152 Mar  9  1999 doc.gif

Directory twiki/pub/TWiki: 

drwxrwx--x    8 nobody  nobody       4096 Nov 18 12:31 .
drwxrwxr-x    8 nobody  nobody       4096 Nov 18 12:31 ..
drwxrwxr-x    2 nobody  nobody       4096 Nov 18 12:31 FileAttachment
drwxrwxr-x    2 nobody  nobody       4096 Nov 18 12:31 PreviewBackground
drwxrwxr-x    2 nobody  nobody       4096 Nov 18 12:31 TWikiDocGraphics
drwxrwxr-x    2 nobody  nobody       4096 Nov 18 12:31 TWikiLogos
drwxrwxr-x    2 nobody  nobody       4096 Nov 18 12:31 TWikiTemplates
drwxrwxr-x    2 nobody  nobody       4096 Nov 18 12:31 WabiSabi

Directory twiki/pub/TWiki/FileAttachment: 

drwxrwxr-x    2 nobody  nobody       4096 Nov 18 12:31 .
drwxrwx--x    8 nobody  nobody       4096 Nov 18 12:31 ..
-rw-rw-r--    1 nobody  nobody         30 Jul 22  1999 Sample.txt
-rw-rw-r--    1 nobody  nobody         94 Jun  7  1999 Smile.gif
-r--r--r--    1 nobody  nobody         81 Aug 15 10:14 Smile.gif,v

-- TWiki:Main.PeterThoeny - 29 Aug 2004
-- TWiki:Main.MikeMannix - 16 May 2002
-- TWiki:Main.ArthurClemens - 08 Aug 2004

Appendix B: TWiki CSS

Listing of CSS class names emitted from TWiki core code and standard plugins, for the 01-Aug-2004 TWiki production release.

Who should read this document?

More or less all html elements generated by TWiki core code now have Cascading Style Sheet (CSS) tags. Skin builders and others who want to change the appearance of the default TWiki installation or any of the skins can use this document to see what styles can be created for these html elements.

Naming conventions

  1. All TWiki class names have the prefix twiki. So: twikiEditPage, twikiTopicAction, etcetera. Remember that CSS class names are case sensitive - TWiki CSS uses lowercase tw.
  2. TWiki uses class names only (.twikiViewPage) and no id names (#twikiViewPage), to allow multiple class names. Class names are written using the dot prefix.
  3. If you define your own CSS classes, it is preferable that you do not use the twiki prefix to prevent undesired overriding effects.

CSS classes

Classes from core code

.twikiNew Changes.pm
.twikiChangeFormButtonHolder Edit.pm
.twikiChangeFormButton Form.pm
.twikiForm Form.pm
.twikiEditFormTextField Form.pm
.twikiEditFormLabelField Form.pm
.twikiEditFormTextAreaField Form.pm
.twikiEditFormCheckboxButton Form.pm
.twikiEditFormCheckboxButton Form.pm
.twikiEditFormCheckboxField Form.pm
.twikiEditFormRadioField Form.pm
.twikiEditFormError Form.pm
.twikiRadioButton Form.pm
.twikiCheckbox Form.pm
.twikiEditFormError Form.pm
.twikiDiffTable RDiff.pm
.twikiDiffDeletedHeader RDiff.pm
.twikiDiffDeletedMarker RDiff.pm
.twikiDiffDeletedText RDiff.pm
.twikiDiffAddedHeader RDiff.pm
.twikiDiffAddedMarker RDiff.pm
.twikiDiffAddedText RDiff.pm
.twikiDiffChangedHeader RDiff.pm
.twikiDiffChangedText RDiff.pm
.twikiDiffUnchangedText RDiff.pm
.twikiDiffLineNumberHeader RDiff.pm
.twikiForm Render.pm
.twikiAnchorLink Render.pm
.twikiLink Render.pm
.twikiNewLink Render.pm
.twikiNew Search.pm
.twikiAlert Search.pm
.twikiAlert Statistics.pm
.twikiAlert TWiki.pm
.twikiToc TWiki.pm
.twikiTocTitle TWiki.pm

Classes from Plugins

TablePlugin

.twikiSortedAscendingCol TablePlugin.pm
.twikiSortedDescendingCol TablePlugin.pm
.twikiFirstCol TablePlugin.pm

Going further

PatternSkin makes fully use of CSS in its templates. Read the PatternSkin? topic and PatternSkinCss? to learn more about adjusting PatternSkin, or creating your own CSS-based skin.

See also: DragonSkin.

Practical introduction to CSS: http://www.w3.org/Style/LieBos2e/enter/

-- TWiki:Main.ArthurClemens - 08 Aug 2004

Appendix C: Encode URLs With UTF8

This page addresses implemented UTF-8 support for URLs only. The overall plan for UTF-8 support for TWiki is described in TWiki:Codev.ProposedUTF8SupportForI18N .

Current Status

To simplify use of internationalised characters within WikiWords and attachment names, TWiki now supports UTF-8 URLs, converting on-the-fly to virtually any character set, including ISO-8859-*, KOI8-R, EUC-JP, and so on.

Support for UTF-8 URL encoding avoids having to configure the browser to turn off this encoding in URLs (the default in Internet Explorer, Opera Browser and some Mozilla Browser URLs) and enables support of browsers where only this mode is supported (e.g. Opera Browser for Symbian smartphones). A non-UTF-8 site character set (e.g. ISO-8859-*) is still used within TWiki, and in fact pages are stored and viewed entirely in the site character set - the browser dynamically converts URLs from the site character set into UTF-8, and TWiki converts them back again.

System requirements are updated as follows:

ISO-2022-*, HZ-* and other 'non-ASCII-safe' multi-byte character sets are now specifically excluded from use as the site character set, since they interfere with TWiki ML; however, many multi-byte character sets work fine, e.g. EUC-JP, GB2312, etc.

It's now possible to override the site character set defined in the $siteLocale setting in TWiki.cfg - this enables you to have a slightly different spelling of the character set in the server locale (e.g. 'eucjp') and the HTTP header sent to the browser (e.g. 'euc-jp').

This feature should also support use of Mozilla Browser with TWiki:Codev.TWikiOnMainframe (as long as mainframe web server can convert or pass through UTF-8 URLs) - however, this specific combination is not tested. Other browser-server combinations should not have any problems.

Please note that use of UTF-8 as the site character set is not yet supported - see Phase 2 of TWiki:Codev.ProposedUTF8SupportForI18N for plans and work to date in this area.

This feature is complete in TWiki releases newer than February 2004.

Note for skin developers: %INTURLENCODE% is no longer required (TWiki:Plugins.InternationalisingYourSkin).

Details of Implementation

URLs are not allowed to contain non-ASCII (8th bit set) characters: http://www.w3.org/TR/html4/appendix/notes.html#non-ascii-chars

The overall plan for UTF-8 support for TWiki is described in two phases in TWiki:/Codev.ProposedUTF8SupportForI18N - this page addresses the first phase, in which UTF-8 is supported for URLs only.

UTF-8 URL translation to virtually any character set is supported as of TWiki Release 01 Sep 2004, but full UTF-8 support (e.g. pages in UTF-8) is not supported yet - this will be phase 2.

The code automatically detects whether a URL is UTF-8 or not, taking care to avoid over-long and illegal UTF-8 encodings that could introduce TWiki:Codev.MajorSecurityProblemWithIncludeFileProcessing (tested against a comprehensive UTF-8 test file, which IE 5.5 fails quite dangerously, and Opera Browser passes). Any non-ASCII URLs that are not valid UTF-8 are then assumed to be directly URL-encoded as a single-byte or multi-byte character set (as now), e.g. EUC-JP.

The main point is that you can use TWiki with international characters in WikiWords without changing your browser setup from the default, and you can also still use TWiki using non-UTF-8 URLs. This works on any Perl version from 5.005_03 onwards and corresponds to Phase 1 of TWiki:Codev.ProposedUTF8SupportForI18N. You can have different users using different URL formats transparently on the same server.

UTF-8 URLs are automatically converted to the current $siteCharset (from the TWiki.cfg locale setting), using modules such as CPAN:Encode if needed.

TWiki generates the whole page in the site charset, e.g. ISO-8859-1 or EUC-JP, but the browser dynamically UTF-8 encodes the attachment's URL when it's used. Since Apache serves attachment downloads without TWiki being involved, TWiki's code can't do its UTF-8 decoding trick, so TWiki URL-encodes such URLs in ISO-8859-1 or whatever when generating the page, to bypass this URL encoding, ensuring that the URLs and filenames seen by Apache remain in the site charset.

TWiki:Codev.TWikiOnMainframe uses EBCDIC web servers that typically translate their output to ASCII, UTF-8 or ISO-8859-1 (and URLs in the other direction) since there are so few EBCDIC web browsers. Such web servers don't work with even ISO-8859-1 URLs if they are URL encoded, since the automated translation is bypassed for URL-encoded characters. For TWiki on Mainframe, TWiki assumes that the web server will automatically translate UTF-8 URLs into EBCDIC URLs, as long as URL encoding is turned off in TWiki pages.

Testing and Limitation

It should work with TWiki:Codev.TWikiOnMainframe. Tested with IE 5.5, Opera 7.11 and Mozilla (Firebird 0.7).

Opera Browser on the P800 smartphone is working for page viewing but leads to corrupt page names when editing pages.

For up to date information see TWiki:Codev.EncodeURLsWithUTF8

-- TWiki:Main.RichardDonkin - 7 Jan 2004
-- TWiki:Main.MattWilkie - 10 Aug 2004
-- TWiki:Main.PeterThoeny - 14 Aug 2004

Note: Included topic TWikiHistory? does not exist yet


Topic TWikiDocumentation . { Edit | Attach | Ref-By | Printable | Diffs | r1.46 | > | r1.45 | > | r1.44 | More }
Revision r1.1 - 25 Apr 2005 - 00:49 - Main.carolynj

Copyright © 1999-2013 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback