TWiki Home Tharsis . TWiki . TWikiDocumentation (r1.1 vs. r1.39) Tharsis webs:
Design | Guilds | Combat | Website
TWiki . { Home | Welcome | Register | Changes | Index | Search | Go }
 <<O>>  Difference Topic TWikiDocumentation (r1.39 - 03 Dec 2001 - MikeMannix)
Changed:
<
<

TWiki Formatted Search Results

Inline search feature allows flexible formatting of search result

Overview

By default, the format for displaying a search result is fixed, e.g. a table with rows of topic name and topic summary. 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 (i.e. %SEARCH{ "food" format="| $topic | $summary |" }%).

Syntax

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

1. header="..." parameter

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

2. format="..." parameter

Use the format paramter to specify the format of one search hit. I.e.
format="| $topic | $summary |"

Variables that can be used in the format string:

Name: Expands To:
$n New line
$web Name of the web
$topic Topic name
$locked LOCKED flag (if any)
$date Time stamp of last topic update, i.e. 17 Oct 2019 - 01:20
$isodate Time stamp of last topic update, i.e. 2019-10-17T01:20Z
$rev Number of last topic revision, i.e. 1.4
$wikiusername Wiki user name of last topic update, i.e. Main.JohnSmith
$username User name of last topic update, i.e. JohnSmith
$summary Topic summary
$formfield(name) The field value of a form field, i.e. $formfield(TopicClassification) would get expanded to PublicFAQ. This applies only to topics that have a TWikiForm
$pattern(reg-exp) A regular expression pattern to extract some text from a topic, i.e. $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the email address from a bullet of format * Email: ....

Note: For $pattern(reg-exp), specify a RegularExpression that scans from start to end and contains the text you want to keep in parenthesis, i.e. $pattern(.*?(from here.*?to here).*). You need to make sure that the integrity of a web page is not compromised, i.e. if you include a table make sure to include everything including the table end tag.

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:

  • Topic: Summary:
  • TWikiFAQ: Frequently Asked Questions About Tharsis This is a real FAQ, and also a demo of one easily implemented knowledge base solution. See how it's done, click Edit . SEARCH ...
  • TWikiFaqTemplate: FAQ: Answer: Back to: NOP TWikiFAQ WIKIUSERNAME DATE
  • TextFormattingFAQ: Text Formatting FAQ The most frequently asked questions about text formatting are answered. Also, TextFormattingRules contains the complete TWiki shorthand system ...

Table showing form field values of topics with a form

Write this in the Know web:

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

  • How do I delete or rename a topic? Answer...
  • Why does the topic revision not increase when I edit a topic? Answer...
  • TWiki has a GPL (GNU General Public License). What is GPL? Answer...
  • I've problems with the WebSearch. There is no Search Result on any inquiry. By clicking the Index topic it's the same problem. Answer...
  • What happens if two of us try to edit the same topic simultaneously? Answer...
  • I would like to install TWiki on my server. Can I get the source? Answer...
  • So what is this WikiWiki thing exactly? Answer...
  • Everybody can edit any page, this is scary. Doesn't that lead to chaos? Answer...

-- PeterThoeny - 28 Nov 2001

>
>

File Attachments

Each topic can have files attached to it, similar to an email attachment. Use your browser to upload or download a file. Attachments are stored under revision control, so uploads can never be lost, and files changes can be made with a rollback option that lets you retrieve all previous versions.

What Are Attachments Good For?

File Attachments can be used to create powerful groupware solutions - file sharing, document management - and for speedy Web authoring.

Document Management System

  • You can use Attachments to store and retrieve documents (in any format, with associated graphics, and other media files); attach documents to specific TWiki topics; collaborate on documents with full revision control; distribute documents on a need-to-know basis using; create a central reference library that's easy to access and manage by an entire user group.

File Sharing

  • For file sharing, FileAttachments on a series of topics can be used to quickly create a well-documented, categorized digital download center for all types of files: documents; graphics and other media; drivers and patches; applications; anything you can safely upload!

Web Authoring

  • Through your Web browser, you can easily upload graphics (or sound files, or anything else you want to embed on a page) and place them anywhere in on a single page, or for use across a web, or site-wide.
    • NOTE: You can also add graphics - any files - directly, typically by FTP upload. This requires server access, and may be more convenient if a large number of files, or a particular directory location, is required. These files can't be managed using browser-based Attachment controls.

Uploading Files

  • To upload: Click on the Attach link at the bottom of each page. A form is shown where you can browse for a file and upload it. The uploaded file will show up in the File Attachment table.
    • Files of any type can be uploaded. Some files that might impose a security risk are renamed, ex: *.php files are renamed to *.php.txt.
    • Currently there is no file size limit besides the disk space on the server.
    • The previous upload path is retained for convenience. In case you make some changes to the local file and want to upload it, again you can copy the previous upload path into the Local file field.

Downloading Files

  • NOTE: There is no access control on individual attachments. If you need this type of control, create separate topics and define access restrictions per topic.

Moving Attachment Files

An attachement can be moved between topics. To do this click Action on the attachment to be moved. On the control page, select the new web and topic, the click Move. The attachment and its version history are moved. The original location is stored as topic Meta Data.

Deleting Attachments

It is not possible to delete attached files with the current TWiki implementation. However, they can be moved to another topic. You may care to have a topic Trash.TrashAttachments - move attachments that are no longer wanted here.

Linking to Attached Files

  • To reference an attachment located in another topic, write text:
    • %PUBURL%/%WEB%/OtherTopic/Sample.txt (for the same web)
    • %PUBURL%/Otherweb/OtherTopic/Sample.txt (for adifferent web)

  • Attached HTML files and text files can be inlined in a topic. Example:
    1. Attach file: Sample.txt
    2. Edit topic and write text: %INCLUDE{"%ATTACHURL%/Sample.txt"}%

  • GIF, JPG and PNG images can be attached and shown embedded in a topic. Example:
    1. Attach file: Smile.gif
    2. Edit topic and write text: %ATTACHURL%/Smile.gif
    3. Preview - text appears as Smile.gif, an image.

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 action 30 22 Jul 2000 - 19:37 PeterThoeny Just a sample
Smile.gif action 94 22 Jul 2000 - 19:38 PeterThoeny Smiley face

File Attachment Controls

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

Attachment: Action: Size: Date: Who: Comment: Attribute:
Sample.txt action 30 22 Jul 2000 - 19:37 PeterThoeny Just a sample  
Smile.gif action 94 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 }

  • The first table is a list of all attachments, including their attributes. An h means the attachment is hidden, it isn't listed when viewing a topic.

  • The second table is all the versions of the attachment. Click on View to see that version. If it's the most recent version, you'll be taken to an URL that always displays the latest version, which is usually what you want.
    • To change the comment on an attachment, enter a new comment and then click Change properties. Note that the comment listed against the specific version will not change, however the comment displayed when viewing the topic does change.
    • To hide/unhide an attachment, enable the Hide file checkbox, then click Change properties.

Known Issues

  • Unlike topics, attachments are not locked during editing. As a workaround, you can change the comment to indicate an attachment file is being worked on - the comment on the specific version isn't lost, it's there when you list all versions of the attachment.
Deleted:
<
<

File Attachments

Each topic can have files attached to it, similar to an email attachment. Use your browser to upload or download a file. Attachments are stored under revision control, so uploads can never be lost, and files changes can be made with a rollback option that lets you retrieve all previous versions.

What Are Attachments Good For?

File Attachments can be used to create powerful groupware solutions - file sharing, document management - and for speedy Web authoring.

Document Management System

  • You can use Attachments to store and retrieve documents (in any format, with associated graphics, and other media files); attach documents to specific TWiki topics; collaborate on documents with full revision control; distribute documents on a need-to-know basis using; create a central reference library that's easy to access and manage by an entire user group.

File Sharing

  • For file sharing, FileAttachments on a series of topics can be used to quickly create a well-documented, categorized digital download center for all types of files: documents; graphics and other media; drivers and patches; applications; anything you can safely upload!

Web Authoring

  • Through your Web browser, you can easily upload graphics (or sound files, or anything else you want to embed on a page) and place them anywhere in on a single page, or for use across a web, or site-wide.
    • NOTE: You can also add graphics - any files - directly, typically by FTP upload. This requires server access, and may be more convenient if a large number of files, or a particular directory location, is required. These files can't be managed using browser-based Attachment controls.

Uploading Files

  • To upload: Click on the Attach link at the bottom of each page. A form is shown where you can browse for a file and upload it. The uploaded file will show up in the File Attachment table.
    • Files of any type can be uploaded. Some files that might impose a security risk are renamed, ex: *.php files are renamed to *.php.txt.
    • Currently there is no file size limit besides the disk space on the server.
    • The previous upload path is retained for convenience. In case you make some changes to the local file and want to upload it, again you can copy the previous upload path into the Local file field.

Downloading Files

  • NOTE: There is no access control on individual attachments. If you need this type of control, create separate topics and define access restrictions per topic.

Moving Attachment Files

An attachement can be moved between topics. To do this click Action on the attachment to be moved. On the control page, select the new web and topic, the click Move. The attachment and its version history are moved. The original location is stored as topic Meta Data.

Deleting Attachments

It is not possible to delete attached files with the current TWiki implementation. However, they can be moved to another topic. You may care to have a topic Trash.TrashAttachments - move attachments that are no longer wanted here.

Linking to Attached Files

  • To reference an attachment located in another topic, write text:
    • %PUBURL%/%WEB%/OtherTopic/Sample.txt (for the same web)
    • %PUBURL%/Otherweb/OtherTopic/Sample.txt (for adifferent web)

  • Attached HTML files and text files can be inlined in a topic. Example:
    1. Attach file: Sample.txt
    2. Edit topic and write text: %INCLUDE{"%ATTACHURL%/Sample.txt"}%

  • GIF, JPG and PNG images can be attached and shown embedded in a topic. Example:
    1. Attach file: Smile.gif
    2. Edit topic and write text: %ATTACHURL%/Smile.gif
    3. Preview - text appears as Smile.gif, an image.

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 action 30 22 Jul 2000 - 19:37 PeterThoeny Just a sample
Smile.gif action 94 22 Jul 2000 - 19:38 PeterThoeny Smiley face

File Attachment Controls

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

Attachment: Action: Size: Date: Who: Comment: Attribute:
Sample.txt action 30 22 Jul 2000 - 19:37 PeterThoeny Just a sample  
Smile.gif action 94 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 }

  • The first table is a list of all attachments, including their attributes. An h means the attachment is hidden, it isn't listed when viewing a topic.

  • The second table is all the versions of the attachment. Click on View to see that version. If it's the most recent version, you'll be taken to an URL that always displays the latest version, which is usually what you want.
    • To change the comment on an attachment, enter a new comment and then click Change properties. Note that the comment listed against the specific version will not change, however the comment displayed when viewing the topic does change.
    • To hide/unhide an attachment, enable the Hide file checkbox, then click Change properties.

Known Issues

  • Unlike topics, attachments are not locked during editing. As a workaround, you can change the comment to indicate an attachment file is being worked on - the comment on the specific version isn't lost, it's there when you list all versions of the attachment.


Added:
>
>

TWiki Formatted Search Results

Inline search feature allows flexible formatting of search result

Overview

By default, the format for displaying a search result is fixed, e.g. a table with rows of topic name and topic summary. 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 (i.e. %SEARCH{ "food" format="| $topic | $summary |" }%).

Syntax

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

1. header="..." parameter

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

2. format="..." parameter

Use the format paramter to specify the format of one search hit. I.e.
format="| $topic | $summary |"

Variables that can be used in the format string:

Name: Expands To:
$n New line
$web Name of the web
$topic Topic name
$locked LOCKED flag (if any)
$date Time stamp of last topic update, i.e. 17 Oct 2019 - 01:20
$isodate Time stamp of last topic update, i.e. 2019-10-17T01:20Z
$rev Number of last topic revision, i.e. 1.4
$wikiusername Wiki user name of last topic update, i.e. Main.JohnSmith
$username User name of last topic update, i.e. JohnSmith
$summary Topic summary
$formfield(name) The field value of a form field, i.e. $formfield(TopicClassification) would get expanded to PublicFAQ. This applies only to topics that have a TWikiForm
$pattern(reg-exp) A regular expression pattern to extract some text from a topic, i.e. $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the email address from a bullet of format * Email: ....

Note: For $pattern(reg-exp), specify a RegularExpression that scans from start to end and contains the text you want to keep in parenthesis, i.e. $pattern(.*?(from here.*?to here).*). You need to make sure that the integrity of a web page is not compromised, i.e. if you include a table make sure to include everything including the table end tag.

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:

  • Topic: Summary:
  • TWikiFAQ: Frequently Asked Questions About Tharsis This is a real FAQ, and also a demo of one easily implemented knowledge base solution. See how it's done, click Edit . SEARCH ...
  • TWikiFaqTemplate: FAQ: Answer: Back to: NOP TWikiFAQ WIKIUSERNAME DATE
  • TextFormattingFAQ: Text Formatting FAQ The most frequently asked questions about text formatting are answered. Also, TextFormattingRules contains the complete TWiki shorthand system ...

Table showing form field values of topics with a form

Write this in the Know web:

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

  • How do I delete or rename a topic? Answer...
  • Why does the topic revision not increase when I edit a topic? Answer...
  • TWiki has a GPL (GNU General Public License). What is GPL? Answer...
  • I've problems with the WebSearch. There is no Search Result on any inquiry. By clicking the Index topic it's the same problem. Answer...
  • What happens if two of us try to edit the same topic simultaneously? Answer...
  • I would like to install TWiki on my server. Can I get the source? Answer...
  • So what is this WikiWiki thing exactly? Answer...
  • Everybody can edit any page, this is scary. Doesn't that lead to chaos? Answer...

-- PeterThoeny - 28 Nov 2001


TWiki Meta Data

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

Overview

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

Meta Data Syntax

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

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

  • Each meta variable is on one line.

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

Example of Format
%META:TOPICINFO{version="1.6" date="976762663" author="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, unx 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, unx time, seconds since start 1970

Notes:

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

META:TOPICPARENT

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, unx 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, unx 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:

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

The recommended sequence is:

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

Viewing Meta Data in Page Source

When viewing a topic the Raw Text link can be clicked to show the text of a topic (ie: 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.

Current support covers:

Variable usage: Comment:
%META{"form"}% Show form data, see TWikiForms
%META{"attachments"}% Show attachments, exclude hidden
Options for Attachments:  
all="on" Show ALL attachments (including hidden)
%META{"moved"}% Details of any topic moves
%META{"parent [options]"}% Show topic parent
Options for parent:  
dontrecurse="on" By default recurses up tree, at some cost
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.

-- JohnTalintyre - 29 Aug 2001
-- MikeMannix - 03 Dec 2001


Deleted:
<
<

TWiki Meta Data

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

Overview

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

Meta Data Syntax

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

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

  • Each meta variable is on one line.

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

Example of Format
%META:TOPICINFO{version="1.6" date="976762663" author="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, unx 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, unx time, seconds since start 1970

Notes:

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

META:TOPICPARENT

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, unx 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, unx 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:

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

The recommended sequence is:

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

Viewing Meta Data in Page Source

When viewing a topic the Raw Text link can be clicked to show the text of a topic (ie: 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.

Current support covers:

Variable usage: Comment:
%META{"form"}% Show form data, see TWikiForms
%META{"attachments"}% Show attachments, exclude hidden
Options for Attachments:  
all="on" Show ALL attachments (including hidden)
%META{"moved"}% Details of any topic moves
%META{"parent [options]"}% Show topic parent
Options for parent:  
dontrecurse="on" By default recurses up tree, at some cost
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.

-- JohnTalintyre - 29 Aug 2001
-- MikeMannix - 03 Dec 2001



 <<O>>  Difference Topic TWikiDocumentation (r1.38 - 03 Dec 2001 - MikeMannix)
Changed:
<
<

TWiki Reference Manual (01-Sep-2001)

>
>

TWiki Reference Manual (01-Dec-2001)

Changed:
<
<


>
>


Changed:
<
<


>
>


Changed:
<
<


>
>


Changed:
<
<


>
>


Changed:
<
<


>
>


Changed:
<
<


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 mark-up for template-specific content. Templates are used to define page layout, and also to supplydefault content for new pages.

Major changes from the previous template system

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

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

Functional Specifications

  • Special template directives (or preprocessor commands) are embedded in normal templates.
  • Use of template directives is optional, templates work without them.
  • All template preprocessing is done in &TWiki::Store::readTemplate() so that the caller simply gets an expanded template file (the same as before).
  • Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
  • Directives:
    • %TMPL:INCLUDE{"file"}%: Includes a template file. The template directory of the current web is searched first, then the templates root (twiki/templates).
    • %TMPL:DEF{"var"}%: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
    • %TMPL:END%: Ends variable definition.
    • %TMPL:P{"var"}%: Prints a previously defined variable.
  • Variables are live in a global name space, there is no parameter passing.
  • Two-pass processing, so that you can use a variable before declaring it or after.
  • Templates and TWikiSkins work transparently and interchangeably. For example, you can create a skin that overloads just the twiki.tmpl, like twiki.print.tmpl, that redefines the header and footer.
  • NOTE: The template directives work only for templates, they do not get processed in topic text.

TWiki Master Template

All common parts are defined in a master template, twiki.tmpl, that all other templates use.

Template variable: Defines:
%TMPL:DEF{"sep"}% "|" separator
%TMPL:DEF{"htmldoctype"}% Start of all HTML pages
%TMPL:DEF{"standardheader"}% Standard header (ex: view, index, seach)
%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

Types of Template

There are two types of templates:

  • HTML Page Templates: Defines layout of Tharsis pages
  • Template Topics: Defines default text when you create a new topic

HTML Page Templates

Tharsis uses HTML template files for all actions like topic view, edit, preview and so on. This allows you to change the look and feel of all pages by editing just some template files.

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

  1. twiki/templates/$webName/$scriptName.tmpl
  2. twiki/templates/$scriptName.tmpl

Note: $webName is the name of the web (ex: Main), and $scriptName is the script (ex: view).

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

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

Template Topics

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

Topic Name: What it is:
WebTopicViewTemplate Help text shown when you view a non existing topic.
WebTopicNonWikiTemplate Help text shown when you view a non existing topic that has not a 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. The following search order applies when you create a new topic:

  1. The topic name specified by the templatetopic CGI parameter.
  2. WebTopicEditTemplate in the current web.
  3. WebTopicEditTemplate in the TWiki web.

Template Topics in Action

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

  • New example topic: (date format is YYYYxMMxDD)

Above form asks for a topic name. A hidden input tag of name "templatetopic" specifies the ExampleTopicTemplate as the template topic. Here is the HTML source of the form:

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

The "onlywikiname" parameter enforces WikiWords for topic names.

Note: Use can use the %WIKIUSERNAME% and %DATE% variables in your topic templates as the signature; those variables are expanded when a new topic is created. The standard topic signature is:
-- %WIKIUSERNAME% - %DATE%

Templates by Example

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

Base template oopsbase.tmpl

The first line declares the 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/Test/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify

testscreen.gif

Known Issues

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

-- PeterThoeny - 23 Jul 2001
-- MikeMannix - 14 Sep 2001


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

Activating Skins

A skin can be activated in two ways:

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

-- PeterThoeny - 14 Jul 2001

>
>


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 layed 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.
---++ 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 to "stick" the * _ = == signs to the words, e.g. take away spaces.
_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 and an asterisk.
   * bullet item
  • bullet item
Nested List Item:
Six, nine, ... spaces and an asterisk.
      * nested stuff
    • nested stuff
Ordered List:
Three spaces and a number.
   1 Sushi
   1 Dim Sum
  1. Sushi
  2. Dim Sum
Definition List:
Three spaces, the term, a colon, a space, followed by the definition.
Note: Terms with spaces are not supported. In case you do have a term with more then one word, separate the words with dashes or with the &nbsp; non-breaking-space entity.
   Sushi: Japan
   Dim&nbsp;Sum: S.F.
Sushi
Japan
Dim Sum
S.F.
Table:
Optional spaces followed by the cells enclosed in vertical bars.
Note: | *bold* | cells are rendered as table headers.
Note: |   spaced   | cells are rendered center aligned.
Note: |     spaced | cells are rendered right aligned.
Note: | 2 colspan || cells are rendered as multi-span columns.
Note: In case you have a long row and you want it to be more readable when you edit the table you can split the row into lines that end with a '\' backslash character.
| *L* | *C* | *R* |
| A2 |  2  |  2 |
| A3 |  3  |  3 |
| multi span |||
| A4 \  | next \  | next |
L C R
A2 2 2
A3 3 3
multi span
A4 next next
WikiWord Links:
CapitalizedWordsStuckTogether (or WikiWords) will produce a link automatically.
Note: In case you want to link to a topic in a different Tharsis web write Webname.TopicName.
WebNotify

Know.ReadmeFirst
WebNotify

ReadmeFirst?

#SquareBrackets 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; i.e. [[text formatting FAQ]] links to topic TextFormattingFAQ. You can also refer to a different web and use anchors.
[[wiki syntax]]

[[Main.TWiki users]]
wiki syntax

Main.TWiki users

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 (i.e. WikiSyntax) and external link references (i.e. http://TWiki.org/) are supported. The same Forced Links rules apply for internal link references. Anchor names can be added as well, like [[WebHome#MyAnchor][go home]] and [[http://www.yahoo.com/#somewhere][Yahoo!]].
[[WikiSyntax][syntax]]

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

GNU

Anchors:
You can define a link reference inside a Tharsis 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.
[[WebHome#NotThere]]

[[#MyAnchor][Jump]]

#MyAnchor To here
WebHome#NotThere

Jump

To here

Prevent a Link:
Prevent a WikiWord from being linked by prepending it with the <nop> tag.
<nop>SunOS
SunOS

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

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

TWikiPlugin Formatting Extensions

Plugins provide additional text formatting capabilities and can extend the functionality of Tharsis 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.

-- MikeMannix - 02 Dec 2001 Changed: <
<


>
>


Changed: <
<


>
>


TWiki Formatted Search Results

Inline search feature allows flexible formatting of search result

Overview

By default, the format for displaying a search result is fixed, e.g. a table with rows of topic name and topic summary. 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 (i.e. %SEARCH{ "food" format="| $topic | $summary |" }%).

Syntax

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

1. header="..." parameter

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

2. format="..." parameter

Use the format paramter to specify the format of one search hit. I.e.
format="| $topic | $summary |"

Variables that can be used in the format string:

Name: Expands To:
$n New line
$web Name of the web
$topic Topic name
$locked LOCKED flag (if any)
$date Time stamp of last topic update, i.e. 17 Oct 2019 - 01:20
$isodate Time stamp of last topic update, i.e. 2019-10-17T01:20Z
$rev Number of last topic revision, i.e. 1.4
$wikiusername Wiki user name of last topic update, i.e. Main.JohnSmith
$username User name of last topic update, i.e. JohnSmith
$summary Topic summary
$formfield(name) The field value of a form field, i.e. $formfield(TopicClassification) would get expanded to PublicFAQ. This applies only to topics that have a TWikiForm
$pattern(reg-exp) A regular expression pattern to extract some text from a topic, i.e. $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the email address from a bullet of format * Email: ....

Note: For $pattern(reg-exp), specify a RegularExpression that scans from start to end and contains the text you want to keep in parenthesis, i.e. $pattern(.*?(from here.*?to here).*). You need to make sure that the integrity of a web page is not compromised, i.e. if you include a table make sure to include everything including the table end tag.

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

Write this in the Know web:

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

-- PeterThoeny - 28 Nov 2001


Changed: <
<


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

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, InterwikiPlugin, TWikiDrawPlugin, UpdateInfoPlugin.

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

Plugin Version Detection

To eliminate the incompatibility problems bound to arise from active open Plugin development, a Plugin versioning system and an API GetVersion detection routine are 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. EmptyPlugin.pm contains no executable code, so it does nothing, but it's ready to be used. Customize it. Refer to the Plugin API specs for more information.

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 EmptyPlugin. To copy the text, go to the page and:
  2. Customize the template for your Plugin; you'll probably want to post a working version on your local TWiki site.
  3. Save your topic as a text file, for use in packaging and publishing your Plugin.

OUTLINE: Doc Topic Contents
Check EmptyPlugin 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.>"

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

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

Test Example: <Include an example of the Plugin in action: if it works, the installation was a success!>"

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. Publish your Plugin in three steps:

  1. Post the Plugin documentation topic in the TWiki:Plugins web:
  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.)

-- AndreaSterbini - 29 May 2001
-- PeterThoeny - 14 Sep 2001
-- MikeMannix - 03 Dec 2001 >
>


File Attachments

Each topic can have files attached to it, similar to an email attachment. Use your browser to upload or download a file. Attachments are stored under revision control, so uploads can never be lost, and files changes can be made with a rollback option that lets you retrieve all previous versions.

What Are Attachments Good For?

File Attachments can be used to create powerful groupware solutions - file sharing, document management - and for speedy Web authoring.

Document Management System

File Sharing

Web Authoring

Uploading Files

Downloading Files

Moving Attachment Files

An attachement can be moved between topics. To do this click Action on the attachment to be moved. On the control page, select the new web and topic, the click Move. The attachment and its version history are moved. The original location is stored as topic Meta Data.

Deleting Attachments

It is not possible to delete attached files with the current TWiki implementation. However, they can be moved to another topic. You may care to have a topic Trash.TrashAttachments - move attachments that are no longer wanted here.

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 action 30 22 Jul 2000 - 19:37 PeterThoeny Just a sample
Smile.gif action 94 22 Jul 2000 - 19:38 PeterThoeny Smiley face

File Attachment Controls

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

Attachment: Action: Size: Date: Who: Comment: Attribute:
Sample.txt action 30 22 Jul 2000 - 19:37 PeterThoeny Just a sample  
Smile.gif action 94 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

Changed: <
<


>
>


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 mark-up for template-specific content. Templates are used to define page layout, and also to supplydefault 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:

Functional Specifications

TWiki Master Template

All common parts are defined in a master template, twiki.tmpl, that all other templates use.

Template variable: Defines:
%TMPL:DEF{"sep"}% "|" separator
%TMPL:DEF{"htmldoctype"}% Start of all HTML pages
%TMPL:DEF{"standardheader"}% Standard header (ex: view, index, seach)
%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

Types of Template

There are two types of templates:

HTML Page Templates

Tharsis uses HTML template files for all actions like topic view, edit, preview and so on. This allows you to change the look and feel of all pages by editing just some template files.

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

  1. twiki/templates/$webName/$scriptName.tmpl
  2. twiki/templates/$scriptName.tmpl

Note: $webName is the name of the web (ex: Main), and $scriptName is the script (ex: view).

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

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

Template Topics

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

Topic Name: What it is:
WebTopicViewTemplate Help text shown when you view a non existing topic.
WebTopicNonWikiTemplate Help text shown when you view a non existing topic that has not a 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. The following search order applies when you create a new topic:

  1. The topic name specified by the templatetopic CGI parameter.
  2. WebTopicEditTemplate in the current web.
  3. WebTopicEditTemplate in the TWiki web.

Template Topics in Action

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

Above form asks for a topic name. A hidden input tag of name "templatetopic" specifies the ExampleTopicTemplate as the template topic. Here is the HTML source of the form:

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

The "onlywikiname" parameter enforces WikiWords for topic names.

Note: Use can use the %WIKIUSERNAME% and %DATE% variables in your topic templates as the signature; those variables are expanded when a new topic is created. The standard topic signature is:
-- %WIKIUSERNAME% - %DATE%

Templates by Example

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

Base template oopsbase.tmpl

The first line declares the 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/Test/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify

testscreen.gif

Known Issues

-- PeterThoeny - 23 Jul 2001
-- MikeMannix - 14 Sep 2001
Changed: <
<


File Attachments

Each topic can have files attached to it, similar to an email attachment. Use your browser to upload or download a file. Attachments are stored under revision control, so uploads can never be lost, and files changes can be made with a rollback option that lets you retrieve all previous versions.

What Are Attachments Good For?

File Attachments can be used to create powerful groupware solutions - file sharing, document management - and for speedy Web authoring.

Document Management System

File Sharing

Web Authoring

Uploading Files

Downloading Files

Moving Attachment Files

An attachement can be moved between topics. To do this click Action on the attachment to be moved. On the control page, select the new web and topic, the click Move. The attachment and its version history are moved. The original location is stored as topic Meta Data.

Deleting Attachments

It is not possible to delete attached files with the current TWiki implementation. However, they can be moved to another topic. You may care to have a topic Trash.TrashAttachments - move attachments that are no longer wanted here.

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 action 30 22 Jul 2000 - 19:37 PeterThoeny Just a sample
Smile.gif action 94 22 Jul 2000 - 19:38 PeterThoeny Smiley face

File Attachment Controls

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

Attachment: Action: Size: Date: Who: Comment: Attribute:
Sample.txt action 30 22 Jul 2000 - 19:37 PeterThoeny Just a sample  
Smile.gif action 94 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 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 Tharsis 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.

Activating Skins

A skin can be activated in two ways:

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

-- PeterThoeny - 14 Jul 2001


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

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, InterwikiPlugin, TWikiDrawPlugin, UpdateInfoPlugin.

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

Plugin Version Detection

To eliminate the incompatibility problems bound to arise from active open Plugin development, a Plugin versioning system and an API GetVersion detection routine are 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. EmptyPlugin.pm contains no executable code, so it does nothing, but it's ready to be used. Customize it. Refer to the Plugin API specs for more information.

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 EmptyPlugin. To copy the text, go to the page and:
  2. Customize the template for your Plugin; you'll probably want to post a working version on your local TWiki site.
  3. Save your topic as a text file, for use in packaging and publishing your Plugin.

OUTLINE: Doc Topic Contents
Check EmptyPlugin 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.>"

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

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

Test Example: <Include an example of the Plugin in action: if it works, the installation was a success!>"

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. Publish your Plugin in three steps:

  1. Post the Plugin documentation topic in the TWiki:Plugins web:
  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.)

-- AndreaSterbini - 29 May 2001
-- PeterThoeny - 14 Sep 2001
-- MikeMannix - 03 Dec 2001


TWikiSiteTools

Utilities for searching, navigation, and monitoring site activity

Overview

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 deamon in regular intervals. The script sends an automated email to subscribed users if topics were changed in a web within last interval.

Configuring Outgoing Mail

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

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
15,45 * * * * (cd ~twiki/public_html/bin; ./mailnotify -q)
The above line will call mailnotify at 15 minutes and 45 minutes past every hour. 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 (as of 2001-11-20, none of them free).

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

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

-- MikeMannix - 01 Dec 2001 Changed: <
<


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 layed 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.
---++ 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 to "stick" the * _ = == signs to the words, e.g. take away spaces.
_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 and an asterisk.
   * bullet item
  • bullet item
Nested List Item:
Six, nine, ... spaces and an asterisk.
      * nested stuff
    • nested stuff
Ordered List:
Three spaces and a number.
   1 Sushi
   1 Dim Sum
  1. Sushi
  2. Dim Sum
Definition List:
Three spaces, the term, a colon, a space, followed by the definition.
Note: Terms with spaces are not supported. In case you do have a term with more then one word, separate the words with dashes or with the &nbsp; non-breaking-space entity.
   Sushi: Japan
   Dim&nbsp;Sum: S.F.
Sushi
Japan
Dim Sum
S.F.
Table:
Optional spaces followed by the cells enclosed in vertical bars.
Note: | *bold* | cells are rendered as table headers.
Note: |   spaced   | cells are rendered center aligned.
Note: |     spaced | cells are rendered right aligned.
Note: | 2 colspan || cells are rendered as multi-span columns.
Note: In case you have a long row and you want it to be more readable when you edit the table you can split the row into lines that end with a '\' backslash character.
| *L* | *C* | *R* |
| A2 |  2  |  2 |
| A3 |  3  |  3 |
| multi span |||
| A4 \  | next \  | next |
L C R
A2 2 2
A3 3 3
multi span
A4 next next
WikiWord Links:
CapitalizedWordsStuckTogether (or WikiWords) will produce a link automatically.
Note: In case you want to link to a topic in a different Tharsis web write Webname.TopicName.
WebNotify

Know.ReadmeFirst
WebNotify

ReadmeFirst?

#SquareBrackets 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; i.e. [[text formatting FAQ]] links to topic TextFormattingFAQ. You can also refer to a different web and use anchors.
[[wiki syntax]]

[[Main.TWiki users]]
wiki syntax

Main.TWiki users

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 (i.e. WikiSyntax) and external link references (i.e. http://TWiki.org/) are supported. The same Forced Links rules apply for internal link references. Anchor names can be added as well, like [[WebHome#MyAnchor][go home]] and [[http://www.yahoo.com/#somewhere][Yahoo!]].
[[WikiSyntax][syntax]]

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

GNU

Anchors:
You can define a link reference inside a Tharsis 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.
[[WebHome#NotThere]]

[[#MyAnchor][Jump]]

#MyAnchor To here
WebHome#NotThere

Jump

To here

Prevent a Link:
Prevent a WikiWord from being linked by prepending it with the <nop> tag.
<nop>SunOS
SunOS

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

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

TWikiPlugin Formatting Extensions

Plugins provide additional text formatting capabilities and can extend the functionality of Tharsis 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.

-- MikeMannix - 02 Dec 2001 >
>


Appendix B: TWiki Development Timeline

01-Dec-2001 Release (Athens)

01-Sep-2001 Release

01-Dec-2000 Release

01-May-2000 Release

01-Sep-1999 Release

01-Jul-1999 Release

1998 Releases

Dev Flow

The typical TWiki development flow...


 <<O>>  Difference Topic TWikiDocumentation (r1.37 - 01 Oct 2001 - MikeMannix)
Changed:
<
<

document.ondblclick=dblclick; //-->

>
>

document.ondblclick=dblclick; //-->

Deleted:
<
<


TWiki Meta Data

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

Overview

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

Meta Data Syntax

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

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

  • Each meta variable is on one line.

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

Example of Format
%META:TOPICINFO{version="1.6" date="976762663" author="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, unx 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, unx time, seconds since start 1970

Notes:

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

META:TOPICPARENT

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, unx 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, unx 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:

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

The recommended sequence is:

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

Viewing Meta Data in Page Source

When viewing a topic the Raw Text link can be clicked to show the text of a topic (ie: 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.

Current support covers:

Variable usage: Comment:
%META{"form"}% Show form data, see TWikiForms
%META{"attachments"}% Show attachments, exclude hidden
Options for Attachments:  
all="on" Show ALL attachments (including hidden)
%META{"moved"}% Details of any topic moves
%META{"parent [options]"}% Show topic parent
Options for parent:  
dontrecurse="on" By default recurses up tree, at some cost
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.

-- JohnTalintyre - 29 Aug 2001
-- MikeMannix - 03 Dec 2001

Added:
>
>


File Attachments

Each topic can have files attached to it, similar to an email attachment. Use your browser to upload or download a file. Attachments are stored under revision control, so uploads can never be lost, and files changes can be made with a rollback option that lets you retrieve all previous versions.

What Are Attachments Good For?

File Attachments can be used to create powerful groupware solutions - file sharing, document management - and for speedy Web authoring.

Document Management System

  • You can use Attachments to store and retrieve documents (in any format, with associated graphics, and other media files); attach documents to specific TWiki topics; collaborate on documents with full revision control; distribute documents on a need-to-know basis using; create a central reference library that's easy to access and manage by an entire user group.

File Sharing

  • For file sharing, FileAttachments on a series of topics can be used to quickly create a well-documented, categorized digital download center for all types of files: documents; graphics and other media; drivers and patches; applications; anything you can safely upload!

Web Authoring

  • Through your Web browser, you can easily upload graphics (or sound files, or anything else you want to embed on a page) and place them anywhere in on a single page, or for use across a web, or site-wide.
    • NOTE: You can also add graphics - any files - directly, typically by FTP upload. This requires server access, and may be more convenient if a large number of files, or a particular directory location, is required. These files can't be managed using browser-based Attachment controls.

Uploading Files

  • To upload: Click on the Attach link at the bottom of each page. A form is shown where you can browse for a file and upload it. The uploaded file will show up in the File Attachment table.
    • Files of any type can be uploaded. Some files that might impose a security risk are renamed, ex: *.php files are renamed to *.php.txt.
    • Currently there is no file size limit besides the disk space on the server.
    • The previous upload path is retained for convenience. In case you make some changes to the local file and want to upload it, again you can copy the previous upload path into the Local file field.

Downloading Files

  • NOTE: There is no access control on individual attachments. If you need this type of control, create separate topics and define access restrictions per topic.

Moving Attachment Files

An attachement can be moved between topics. To do this click Action on the attachment to be moved. On the control page, select the new web and topic, the click Move. The attachment and its version history are moved. The original location is stored as topic Meta Data.

Deleting Attachments

It is not possible to delete attached files with the current TWiki implementation. However, they can be moved to another topic. You may care to have a topic Trash.TrashAttachments - move attachments that are no longer wanted here.

Linking to Attached Files

  • To reference an attachment located in another topic, write text:
    • %PUBURL%/%WEB%/OtherTopic/Sample.txt (for the same web)
    • %PUBURL%/Otherweb/OtherTopic/Sample.txt (for adifferent web)

  • Attached HTML files and text files can be inlined in a topic. Example:
    1. Attach file: Sample.txt
    2. Edit topic and write text: %INCLUDE{"%ATTACHURL%/Sample.txt"}%

  • GIF, JPG and PNG images can be attached and shown embedded in a topic. Example:
    1. Attach file: Smile.gif
    2. Edit topic and write text: %ATTACHURL%/Smile.gif
    3. Preview - text appears as Smile.gif, an image.

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 action 30 22 Jul 2000 - 19:37 PeterThoeny Just a sample
Smile.gif action 94 22 Jul 2000 - 19:38 PeterThoeny Smiley face

File Attachment Controls

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

Attachment: Action: Size: Date: Who: Comment: Attribute:
Sample.txt action 30 22 Jul 2000 - 19:37 PeterThoeny Just a sample  
Smile.gif action 94 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 }

  • The first table is a list of all attachments, including their attributes. An h means the attachment is hidden, it isn't listed when viewing a topic.

  • The second table is all the versions of the attachment. Click on View to see that version. If it's the most recent version, you'll be taken to an URL that always displays the latest version, which is usually what you want.
    • To change the comment on an attachment, enter a new comment and then click Change properties. Note that the comment listed against the specific version will not change, however the comment displayed when viewing the topic does change.
    • To hide/unhide an attachment, enable the Hide file checkbox, then click Change properties.

Known Issues

  • Unlike topics, attachments are not locked during editing. As a workaround, you can change the comment to indicate an attachment file is being worked on - the comment on the specific version isn't lost, it's there when you list all versions of the attachment.
Added:
>
>


TWiki Meta Data

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

Overview

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

Meta Data Syntax

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

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

  • Each meta variable is on one line.

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

Example of Format
%META:TOPICINFO{version="1.6" date="976762663" author="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, unx 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, unx time, seconds since start 1970

Notes:

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

META:TOPICPARENT

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, unx 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, unx 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:

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

The recommended sequence is:

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

Viewing Meta Data in Page Source

When viewing a topic the Raw Text link can be clicked to show the text of a topic (ie: 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.

Current support covers:

Variable usage: Comment:
%META{"form"}% Show form data, see TWikiForms
%META{"attachments"}% Show attachments, exclude hidden
Options for Attachments:  
all="on" Show ALL attachments (including hidden)
%META{"moved"}% Details of any topic moves
%META{"parent [options]"}% Show topic parent
Options for parent:  
dontrecurse="on" By default recurses up tree, at some cost
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.

-- JohnTalintyre - 29 Aug 2001
-- MikeMannix - 03 Dec 2001


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 layed 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.
---++ 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 to "stick" the * _ = == signs to the words, e.g. take away spaces.
_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 and an asterisk.
   * bullet item
  • bullet item
Nested List Item:
Six, nine, ... spaces and an asterisk.
      * nested stuff
    • nested stuff
Ordered List:
Three spaces and a number.
   1 Sushi
   1 Dim Sum
  1. Sushi
  2. Dim Sum
Definition List:
Three spaces, the term, a colon, a space, followed by the definition.
Note: Terms with spaces are not supported. In case you do have a term with more then one word, separate the words with dashes or with the &nbsp; non-breaking-space entity.
   Sushi: Japan
   Dim&nbsp;Sum: S.F.
Sushi
Japan
Dim Sum
S.F.
Table:
Optional spaces followed by the cells enclosed in vertical bars.
Note: | *bold* | cells are rendered as table headers.
Note: |   spaced   | cells are rendered center aligned.
Note: |     spaced | cells are rendered right aligned.
Note: | 2 colspan || cells are rendered as multi-span columns.
Note: In case you have a long row and you want it to be more readable when you edit the table you can split the row into lines that end with a '\' backslash character.
| *L* | *C* | *R* |
| A2 |  2  |  2 |
| A3 |  3  |  3 |
| multi span |||
| A4 \  | next \  | next |
L C R
A2 2 2
A3 3 3
multi span
A4 next next
WikiWord Links:
CapitalizedWordsStuckTogether (or WikiWords) will produce a link automatically.
Note: In case you want to link to a topic in a different Tharsis web write Webname.TopicName.
WebNotify

Know.ReadmeFirst
WebNotify

ReadmeFirst?

#SquareBrackets 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; i.e. [[text formatting FAQ]] links to topic TextFormattingFAQ. You can also refer to a different web and use anchors.
[[wiki syntax]]

[[Main.TWiki users]]
wiki syntax

Main.TWiki users

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 (i.e. WikiSyntax) and external link references (i.e. http://TWiki.org/) are supported. The same Forced Links rules apply for internal link references. Anchor names can be added as well, like [[WebHome#MyAnchor][go home]] and [[http://www.yahoo.com/#somewhere][Yahoo!]].
[[WikiSyntax][syntax]]

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

GNU

Anchors:
You can define a link reference inside a Tharsis 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.
[[WebHome#NotThere]]

[[#MyAnchor][Jump]]

#MyAnchor To here
WebHome#NotThere

Jump

To here

Prevent a Link:
Prevent a WikiWord from being linked by prepending it with the <nop> tag.
<nop>SunOS
SunOS

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

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

TWikiPlugin Formatting Extensions

Plugins provide additional text formatting capabilities and can extend the functionality of Tharsis 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.

-- MikeMannix - 02 Dec 2001

 <<O>>  Difference Topic TWikiDocumentation (r1.36 - 15 Sep 2001 - MikeMannix)
Changed:
<
<

>
>

Appendix A: TWiki File System

Annotated listings of files included in the 01-Sep-2001 TWiki distribution

Overview

This Appendix contains directory and file listings, and individual file descriptions, for the full 01-Sep-2001 TWiki distribution package.

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 subdirectory structure 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
twiki/pub list Public files (e.g. images) and FileAttachments and their RCS histories
twiki/data list Topic text (page content) and RCS histories
twiki/templates list HTML templates, used by TWiki scripts

File Descriptions

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

Files in twiki

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

File: Used for:
index.html A page with a link to first launch TWiki after install
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

Files in twiki/bin

Perl CGI scripts. Full file list:

File: Used for:
.htaccess.txt Authentication. Rename to .htaccess and customize if used
attach Script that shows the attach file page (FileAttachment)
edit Script to edit a topic
geturl Script to fetch URL data
installpasswd Script to install new password by admin
mailnotify Script called by cron job to notify users of changes
oops Script that shows an OK or oops dialog
passwd Script to reset and change password
preview Script to preview topic after edit
rdiff Script to see differences of topics
register Script to register new users
rename Script to rename/move topics and move attachments
save Script that saves a topic, called by preview
search Script that displays search results
statistics Script to create statistics topic
testenv Script to test CGI environment variables
upload Script that does file upload (FileAttachment)
view Script to view a topic ( the script )
viewfile Script to 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 For configuration, used by TWiki.pm
TWiki.pm Main TWiki library
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/Prefs.pm Preferences handling
TWiki/Search.pm Search engine, used by wiki.pm
TWiki/Store.pm Back-end storage, *.txt text file and *.txt,v RCS repository file handling
TWiki/Plugins/DefaultPlugin.pm Handles some legacy rules
TWiki/Plugins/EmptyPlugin.pm Empty plugin, use to create your own
TWiki/Plugins/InterwikiPlugin.pm Use aliases as links for predefined URLs

Files under twiki/pub

The pub directory stores data-related files, including images used by TWiki and FileAttachments. Attachments are stored in sub-directories created with the related topic name. Partial file list:

File: Used for:
favicon.ico ICO file
twikilogo.gif GIF file
twikilogo1.gif GIF file
twikilogo2.gif GIF file
twikilogo3.gif GIF file
twikilogo4.gif GIF file
twikilogo88x31 GIF file
wikiHome.gif GIF file
icn/_filetypes.txt GIF file
icn/bat.gif GIF file
icn/bmp.gif GIF file
... ...
TWiki/FileAttachment/Sample.txt TEXT file
TWiki/FileAttachment/Smile.gif GIF file
TWiki/PreviewBackground/blankltgraybg.gif GIF file
TWiki/PreviewBackground/blankwhitebg.gif GIF file
TWiki/PreviewBackground/previewbg.gif GIF file
TWiki/WabiSabi/wabisabi.gif GIF file
Know/IncorrectDllVersionW32PTH10DLL/W32PTH10.DLL DLL file

Files under twiki/data

TWiki page data stored as individual text files. Each active web has its own subdirectory. The TWiki distribution includes four start-up webs - Main, TWiki, Know, Test - with documentation and demo content, a Trash web, and a _default directory containing all topics required to start a new web. Partial file list:

File: Used for:
.htpasswd Basic Authentication (htaccess) password file
debug.txt Program messages useful for debugging
mime.types Recognized file formats
warning.txt Diagnostic messages for identifying problems
_default directory can be copied to empty directory when creating new Webs
_default/.changes Web-level record of topic changes
_default/.mailnotify Web-level timstamp of last e-mail 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/WebNotify.txt Subscribe/unsubscribe to web changes email alert
_default/WebNotify.txt,v Revisions history (RCS)
_default/WebPreferences.txt Web-level preference settings
_default/WebPreferences.txt,v Revisions history (RCS)
_default/WebSearch.txt Web-level search options
_default/WebSearch.txt,v Revisions history (RCS)
_default/WebStatistics.txt Generates web usage statistics
_default/WebStatistics.txt,v Revisions history (RCS)
... ...

Files in twiki/templates

Templates used to control appearance of all rendered pages. Full file list:

File: Used for:
attach.tmpl Attach file control screen
attachagain.tmpl Control screen
attachnew.tmpl Control screen
changeform.tmpl Control screen
changes.tmpl Displays WebChanges 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 Control screen
oopsaccesschange.tmpl Error message
oopsaccessgroup.tmpl Error message
oopsaccessrename.tmpl Error message
oopsaccessview.tmpl Error message
oopsauth.tmpl Error message
oopsbadpwformat.tmpl Error message
oopschangepasswd.tmpl Error message
oopsempty.tmpl Error message
oopslocked.tmpl Error message
oopslockedrename.tmpl Error message
oopsmissing.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
oopsregexist.tmpl Error message
oopsregpasswd.tmpl Error message
oopsregrequ.tmpl Error message
oopsregthanks.tmpl Error message
oopsregwiki.tmpl Error message
oopsrenameerr.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
oopswrongpassword.tmpl Error message
preview.tmpl Preview Changes screen
rdiff.tmpl Displays text changes before & after (Diffs)
register.tmpl Registration page
registernotify.tmpl Registration notification
rename.tmpl Doing a new topic rename, user chooses web & topic
renamebase.tmpl Used by other rename templates
renameconfirm.tmpl Confirms a pre-specified rename, ex: undoing a rename
renamerefs.tmpl Rename done, but some references not changed (topics were locked)
search.tmpl Search screen
searchbookview.tmpl Search results with full topic content
searchmeta.tmpl Search screen
searchrenameview.tmpl Used by rename to list references to topic being renamed
twiki.tmpl Base template definitions used by other templates
view.plain.tmpl Printable topic view with reduced header/footer
view.print.tmpl Topic view without header/footer
view.tmpl Main topic view

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 Sep 14 22:45 .
drwxrwxr-x    5 twiki twiki    4096 Aug  3 01:57 ..
-rw-rw-r--    1 twiki twiki     895 Aug 25 01:32 .htaccess
-rw-rw-r--    1 twiki twiki     782 Aug 25 01:32 .htaccess.txt
-rw-rwxr-x    1 twiki twiki    4819 Sep  7 01:44 attach
-rwxrwxr-x    1 twiki twiki    3381 Jul 21 18:41 changes
-rw-rwxr-x    1 twiki twiki    8056 Sep  3 22:44 edit
-rwxrwxr-x    1 twiki twiki    1736 Nov 17  2000 geturl
-rwxrwxr-x    1 twiki twiki    4481 Aug 21 19:10 installpasswd
-rwxrwxr-x    1 twiki twiki    5829 Aug 21 22:03 mailnotify
-rwxrwxr-x    1 twiki twiki    4512 Aug 25 22:10 makedistrib
-rw-rwxr-x    1 twiki twiki    2254 Aug 21 19:25 oops
-rwxrwxr-x    1 twiki twiki    6399 Aug 22 18:31 passwd
-rw-rwxr-x    1 twiki twiki    5315 Sep  3 22:45 preview
-rwxrwxr-x    1 twiki twiki    8946 Sep  8 18:35 rdiff
-rw-rwxr-x    1 twiki twiki    9199 Aug 25 21:02 register
-rwxrwxr-x    1 twiki twiki   13481 Sep  7 21:17 rename
-rw-rwxr-x    1 twiki twiki    4645 Sep  7 01:44 save
-rwxrwxr-x    1 twiki twiki    4166 Jul 21 18:45 search
-rw-rwxr-x    1 twiki twiki   10006 Sep  7 01:42 statistics
-rwxrwxr-x    1 twiki twiki    9356 Aug 31 10:04 testenv
-rw-rwxr-x    1 twiki twiki   13782 Aug 21 22:17 upload
-rwxrwxr-x    1 twiki twiki   10164 Sep  8 18:24 view
-rw-rwxr-x    1 twiki twiki    2773 Sep 13 17:21 viewfile

Directory twiki/templates/:

drwxrwxr-x    2 twiki twiki    4096 Sep  8 00:47 .
drwxrwxr-x    4 twiki twiki    4096 Sep 10 23:21 ..
-rw-rw-r--    1 twiki twiki    2573 Aug 31 13:06 attach.tmpl
-rw-rw-r--    1 twiki twiki    1604 Aug  3 14:52 attachagain.tmpl
-rw-rw-r--    1 twiki twiki     449 Aug  3 14:47 attachnew.tmpl
-rw-rw-r--    1 twiki twiki    1309 Sep  3 22:47 changeform.tmpl
-rw-rw-r--    1 twiki twiki    1619 Aug 31 13:16 changes.tmpl
-rw-rw-r--    1 twiki twiki   11842 Sep 10 19:00 edit.iejs.tmpl
-rw-rw-r--    1 twiki twiki    2603 Sep  3 22:48 edit.tmpl
-rw-rw-r--    1 twiki twiki     981 May 28 20:14 mailnotify.tmpl
-rw-rw-r--    1 twiki twiki    1499 Aug 31 13:16 moveattachment.tmpl
-rw-rw-r--    1 twiki twiki     570 Aug  1 01:24 oopsaccesschange.tmpl
-rw-rw-r--    1 twiki twiki     586 Aug  1 01:24 oopsaccessgroup.tmpl
-rw-rw-r--    1 twiki twiki     573 Aug  1 01:47 oopsaccessrename.tmpl
-rw-rw-r--    1 twiki twiki     573 Aug  1 01:24 oopsaccessview.tmpl
-rw-rw-r--    1 twiki twiki    1014 Aug  1 01:25 oopsauth.tmpl
-rw-rw-r--    1 twiki twiki     405 Aug  1 01:49 oopsbadpwformat.tmpl
-rw-rw-r--    1 twiki twiki     344 Jul 31 10:16 oopschangepasswd.tmpl
-rw-rw-r--    1 twiki twiki     624 Jul 31 02:09 oopsempty.tmpl
-rw-rw-r--    1 twiki twiki     918 Jul 31 02:20 oopslocked.tmpl
-rw-rw-r--    1 twiki twiki     590 Jul 31 10:25 oopslockedrename.tmpl
-rw-rw-r--    1 twiki twiki     328 Jul 31 10:26 oopsmissing.tmpl
-rw-rw-r--    1 twiki twiki    2158 Sep 13 02:03 oopsmore.tmpl
-rw-rw-r--    1 twiki twiki     407 Aug  1 10:22 oopsmoveerr.tmpl
-rw-rw-r--    1 twiki twiki    1136 Aug  1 01:30 oopsnoformdef.tmpl
-rw-rw-r--    1 twiki twiki     522 Aug  1 01:31 oopsnotwikiuser.tmpl
-rw-rw-r--    1 twiki twiki     413 Jul 31 02:07 oopsnoweb.tmpl
-rw-rw-r--    1 twiki twiki     393 Aug  1 01:32 oopspreview.tmpl
-rw-rw-r--    1 twiki twiki     462 Aug  1 01:32 oopsregexist.tmpl
-rw-rw-r--    1 twiki twiki     345 Aug  1 00:52 oopsregpasswd.tmpl
-rw-rw-r--    1 twiki twiki     356 Aug  1 00:53 oopsregrequ.tmpl
-rw-rw-r--    1 twiki twiki     540 Aug  1 01:57 oopsregthanks.tmpl
-rw-rw-r--    1 twiki twiki     679 Aug  1 01:02 oopsregwiki.tmpl
-rw-rw-r--    1 twiki twiki     411 Aug  1 10:23 oopsrenameerr.tmpl
-rw-rw-r--    1 twiki twiki     483 Aug  1 01:59 oopsresetpasswd.tmpl
-rw-rw-r--    1 twiki twiki     921 Sep  7 23:47 oopsrev.tmpl
-rw-rw-r--    1 twiki twiki     774 Aug  1 01:35 oopssave.tmpl
-rw-rw-r--    1 twiki twiki     477 Aug  1 02:01 oopssaveerr.tmpl
-rw-rw-r--    1 twiki twiki     452 Aug  1 01:37 oopssendmailerr.tmpl
-rw-rw-r--    1 twiki twiki     379 Aug  1 10:23 oopstopicexists.tmpl
-rw-rw-r--    1 twiki twiki     342 Jul 31 10:09 oopsupload.tmpl
-rw-rw-r--    1 twiki twiki     364 Aug  1 02:05 oopswrongpassword.tmpl
-rw-rw-r--    1 twiki twiki    2584 Sep  3 22:49 preview.tmpl
-rw-rw-r--    1 twiki twiki    1539 Sep  8 18:29 rdiff.tmpl
-rw-rw-r--    1 twiki twiki     552 Jul 14 19:23 register.tmpl
-rw-rw-r--    1 twiki twiki    1151 Aug 23 16:38 registernotify.tmpl
-rw-rw-r--    1 twiki twiki     789 Aug  8 23:32 rename.tmpl
-rw-rw-r--    1 twiki twiki    2310 Sep 10 14:56 renamebase.tmpl
-rw-rw-r--    1 twiki twiki     475 Aug  3 16:53 renameconfirm.tmpl
-rw-rw-r--    1 twiki twiki     589 Aug  8 23:32 renamerefs.tmpl
-rw-rw-r--    1 twiki twiki    1792 Aug 31 18:38 search.tmpl
-rw-rw-r--    1 twiki twiki    1650 Aug 31 18:38 searchbookview.tmpl
-rw-rw-r--    1 twiki twiki     149 Sep 13 02:00 searchmeta.tmpl
-rw-rw-r--    1 twiki twiki    2044 Aug 31 18:38 searchrenameview.tmpl
-rw-rw-r--    1 twiki twiki    2246 Aug 31 13:08 twiki.tmpl
-rw-rw-r--    1 twiki twiki     418 Aug 31 13:07 view.plain.tmpl
-rw-rw-r--    1 twiki twiki     826 Aug 31 13:08 view.print.tmpl
-rw-rw-r--    1 twiki twiki    1770 Sep  8 00:32 view.tmpl

Directory twiki/data/:

drwxrwxr-x    8 nobody nobody  4096 Sep  7 01:04 .
drwxrwxr-x    4 nobody nobody  4096 Sep 10 23:21 ..
-rw-rw-rw-    1 twiki  twiki    159 Aug 24 19:49 .htpasswd
drwxrwxr-x    2 nobody nobody  4096 Sep  9 02:45 Know
drwxrwxr-x    2 nobody nobody  4096 Sep  9 02:45 Main
drwxrwxr-x    2 nobody nobody  8192 Sep 14 23:22 TWiki
drwxrwxr-x    2 nobody nobody  4096 Sep  9 02:45 Test
drwxrwxr-x    2 nobody nobody  4096 Sep 14 12:04 Trash
drwxrwxr-x    2 nobody nobody  4096 Sep  9 02:45 _default
-rw-rw-rw--   1 twiki  twiki      0 Jul  1 02:20 debug.txt
-rw-rw-r--    1 twiki  twiki    3419 Aug 13 00:15 mime.types
-rw-rw-rw--   1 twiki  twiki      0 Jul  1 02:19 warning.txt

Partial file list for twiki/data/Main:

drwxrwxrwx   2 nobody  nobody  4096 Aug 19 04:15 .
drwxrwxrwx   6 nobody  nobody  4096 Aug  3 01:09 ..
-rw-rw-rw-   1 twiki twiki     3716 Aug 19 02:19 .changes
-rw-rw-rw-   1 twiki twiki        9 Aug 19 02:45 .mailnotify
-rw-r--r--   1 nobody  nobody   358 Aug 18 17:22 OfficeLocations.txt
-r--r--r--   1 nobody  nobody   878 Aug 18 17:22 OfficeLocations.txt,v
-rw-r--r--   1 nobody  nobody   680 Aug 18 17:36 TWikiGuest.txt
-r--r--r--   1 nobody  nobody  1989 Aug 18 17:36 TWikiGuest.txt,v
-rw-r--r--   1 nobody  nobody   459 Aug 18 17:19 TWikiUsers.txt
-r--r--r--   1 nobody  nobody  3840 Aug 18 17:19 TWikiUsers.txt,v
-rw-r--r--   1 nobody  nobody    95 Aug 19 03:06 WebChanges.txt
-r--r--r--   1 nobody  nobody   284 Aug 19 03:06 WebChanges.txt,v
-rw-r--r--   1 nobody  nobody  1853 Aug 18 18:08 WebHome.txt
-r--r--r--   1 nobody  nobody  6523 Aug 18 18:08 WebHome.txt,v

Directory twiki/pub/:

drwxrwxrwx   6 nobody  nobody  4096 Aug  3 01:21 .
drwxrwxr-x   3 twiki   twiki   4096 Jun 17 16:35 ..
drwxrwxrwx   3 nobody  nobody  4096 Jun 17 16:35 Know
drwxrwxrwx   3 nobody  nobody  4096 Aug  3 01:21 TWiki
-rw-rw-r--   1 twiki   twiki   1078 Jan 14  2000 favicon.ico
drwxrwxr-x   2 twiki   twiki   4096 Jun 17 16:35 icn
-rw-rw-r--   1 twiki   twiki   3016 Oct  5  1999 twikilogo.gif
-rw-rw-r--   1 twiki   twiki   5320 Oct  5  1999 twikilogo1.gif
-rw-rw-r--   1 twiki   twiki   6125 Oct  5  1999 twikilogo2.gif
-rw-rw-r--   1 twiki   twiki   7218 Oct  5  1999 twikilogo3.gif
-rw-rw-r--   1 twiki   twiki   6710 Oct  5  1999 twikilogo4.gif
-rw-rw-r--   1 twiki   twiki   3501 Sep 14 11:57 twikilogo88x31.gif
-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 Jun 17 16:35 .
drwxrwxrwx   6 nobody  nobody  4096 Aug  3 01:21 ..
-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

-- MikeMannix - 14 Sep 2001
-- PeterThoeny - 14 Sep 2001


 <<O>>  Difference Topic TWikiDocumentation (r1.35 - 12 Sep 2001 - MikeMannix)
Changed:
<
<

>
>

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 mark-up for template-specific content. Templates are used to define page layout, and also to supplydefault content for new pages.

Major changes from the previous template system

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

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

Functional Specifications

  • Special template directives (or preprocessor commands) are embedded in normal templates.
  • Use of template directives is optional, templates work without them.
  • All template preprocessing is done in &TWiki::Store::readTemplate() so that the caller simply gets an expanded template file (the same as before).
  • Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
  • Directives:
    • %TMPL:INCLUDE{"file"}%: Includes a template file. The template directory of the current web is searched first, then the templates root (twiki/templates).
    • %TMPL:DEF{"var"}%: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
    • %TMPL:END%: Ends variable definition.
    • %TMPL:P{"var"}%: Prints a previously defined variable.
  • Variables are live in a global name space, there is no parameter passing.
  • Two-pass processing, so that you can use a variable before declaring it or after.
  • Templates and TWikiSkins work transparently and interchangeably. For example, you can create a skin that overloads just the twiki.tmpl, like twiki.print.tmpl, that redefines the header and footer.
  • NOTE: The template directives work only for templates, they do not get processed in topic text.

TWiki Master Template

All common parts are defined in a master template, twiki.tmpl, that all other templates use.

Template variable: Defines:
%TMPL:DEF{"sep"}% "|" separator
%TMPL:DEF{"htmldoctype"}% Start of all HTML pages
%TMPL:DEF{"standardheader"}% Standard header (ex: view, index, seach)
%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

Types of Template

There are two types of templates:

  • HTML Page Templates: Defines layout of Tharsis pages
  • Template Topics: Defines default text when you create a new topic

HTML Page Templates

Tharsis uses HTML template files for all actions like topic view, edit, preview and so on. This allows you to change the look and feel of all pages by editing just some template files.

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

  1. twiki/templates/$webName/$scriptName.tmpl
  2. twiki/templates/$scriptName.tmpl

Note: $webName is the name of the web (ex: Main), and $scriptName is the script (ex: view).

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

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

Template Topics

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

Topic Name: What it is:
WebTopicViewTemplate Help text shown when you view a non existing topic.
WebTopicNonWikiTemplate Help text shown when you view a non existing topic that has not a 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. The following search order applies when you create a new topic:

  1. The topic name specified by the templatetopic CGI parameter.
  2. WebTopicEditTemplate in the current web.
  3. WebTopicEditTemplate in the TWiki web.

Template Topics in Action

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

  • New example topic: (date format is YYYYxMMxDD)

Above form asks for a topic name. A hidden input tag of name "templatetopic" specifies the ExampleTopicTemplate as the template topic. Here is the HTML source of the form:

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

The "onlywikiname" parameter enforces WikiWords for topic names.

Note: Use can use the %WIKIUSERNAME% and %DATE% variables in your topic templates as the signature; those variables are expanded when a new topic is created. The standard topic signature is:
-- %WIKIUSERNAME% - %DATE%

Templates by Example

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

Base template oopsbase.tmpl

The first line declares the 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/Test/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify

testscreen.gif

Known Issues

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

-- PeterThoeny - 23 Jul 2001
-- MikeMannix - 14 Sep 2001

Changed:
<
<

>
>

TWiki Forms

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

Overview

By adding form-based input to free-form content, you can structure topics with unlimited, easily searchable categories. When forms are enabled for a web and selected in a topic, the form appears in edit mode, and the contents are rendered as a table when viewing the actual page. When editing, can switch forms, if more than one is defined, or remove forms entirely. Form input values are stored as TWikiMetaData; all data is saved.

Form Templates replace TWikiCategory Tables from the 01-Dec-2000 version of TWiki.

Main Changes from Category Tables

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

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

Defining a Form Template

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

Form Template Elements

  • form template - a set of fields defining a form (replaces category table definition)
    • A web can use one or more form templates.
  • form - A topic containing additional meta-data (besides the free form TEXTAREA) which categorizes the content. (replaces category table)
    • A topic has zero or one of the defined forms. So there are topics with a form or without.
  • form field - a named item in a form (replaces category item name)
  • field type - selects the INPUT type:
    • select - drop-down menu or scrollable box
    • checkbox - one or more checkboxes
    • checkbox+buttons - one or more checkboxes, plus Set and Clear buttons
    • radio - one or more radio buttons
    • text - a one-line text field
    • textarea - a text box; size is 40x10 (columns x rows)
  • field value - one or more values from a fixed set (select, checkbox, radio type) or free-form (text). (replaces category item value)

Defining a Form in One Topic

  1. Create a new topic with your Form name: MyForm, ExpenseReport, InfoCategory, RecordReview, whatever you need.
  2. Create a TWiki table, with each column representing one element of an entry field: Name, Type, Size, Values, and Tooltip msessage (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.

Example: WebForm from the TWiki.Know web
| *Name* | *Type* | *Size* | *Values* | *Tooltip message* |
| Know.TopicClassification | select | 1 | Know.NoDisclosure, 
  Know.PublicSupported, Know.PublicFAQ | blah blah... |
| Know.OperatingSystem | checkbox | 3 | Know.OsHPUX, Know.OsLinux,
  Know.OsSolaris, Know.OsWin | blah blah... |
| Know.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

The Form Template can also be defined in an alternative way by using more then one topic:

  • A Form Template topic defines the Form.
  • Fields that have more then one value - radio, select, checkbox - can be defined in individual field value topics.

Example: WebFormTemplate

  • Know.WebFormTemplate Form main definition:
     
    Name Type Size Values Tooltip message
    TopicClassification? select 1 ... blah blah...
    OperatingSystem? checkbox 3 ... blah blah...
    OsVersion? text 16 ... blah blah...

  • Know.TopicClassification field value definition:
     
    Name Type Tooltip message
    NoDisclosure? option blah blah...
    PublicSupported? option blah blah...
    PublicFAQ? option blah blah...

  • Implementation Notes: This format allows you to define field items with or without WikiNames, depending on your needs.
    • The topic can be protected in the usual manner so that not everybody can change the form template - see TWikiAccessControl
    • [[...]] links can be used for force a link, at present [[...][...]] format is not supported.
    • The "Tooltip message" column is used as a tool tip for the field name (only if field name is a WikiName) - you only see the tooltip on edit.
    • The first item in the list is the default item. Alternative initial values can be given in a topic template such as WebTopicEditTemplate or using field=value or for checkboxes field=1.
    • The topic definition is not read when a topic is viewed.

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:

  • Set WEBFORMS = BugForm, FeatureForm, BookLoanForm

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

  • A default Form Template (new topics get this default form) can be provided by creating the WebTopicEditTemplate topic in a web and adding a form to it. Initial Form values can be set there.

  • Additionally a new topic can be given a Form using the formtemplate parameter in the URL. Initial values can then be provided in the URLs or as form values:
    • other than checkboxes: name, ex: ?BugPriority=1
    • checkbox: namevalue=1, ex: ?ColourRed=1.
      Boxes with a tick must be specified.

Including Forms in New Topics

When you create a new topic in a web that has the WEBFORMS Preferences variable set, an Add Form button appears at the bottom of the page. You can start all new topics with forms enabled, and pre-select a form if there's more than one available:

  1. Edit the WebTopicEditTemplate topic, adding the name of an available Form.
  2. Create a new topic to check - the Form should appear with values set.
    • Click Change to switch or remove Forms.

A form embedded in a topic also appears in a new topic. This is done by specifying the formtemplate parameter in the URL.

Setting Up Multiple Form Options

  • The optional WEBFORMS variable defines alternative Form Templates that can be selected by pressing Change in edit mode.

  • A Template topic can use any Form Template.

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

Form Template Data Storage

The Form Template topic name, fields and values are stored as TWikiMetaData. The order of field/value pairs in the Meta Data is the same as in the Template.

-- JohnTalintyre - 16 Aug 2001
-- MikeMannix - 03 Dec 2001


 <<O>>  Difference Topic TWikiDocumentation (r1.34 - 09 Sep 2001 - MikeMannix)
Added:
>
>



 <<O>>  Difference Topic TWikiDocumentation (r1.33 - 08 Sep 2001 - MikeMannix)
Changed:
<
<

>
>


 <<O>>  Difference Topic TWikiDocumentation (r1.32 - 07 Sep 2001 - MikeMannix)
Changed:
<
<

Merged into TWikiMetaData - this topic to be rolled back.

>
>

TWiki Meta Data

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

Overview

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

Meta Data Syntax

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

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

  • Each meta variable is on one line.

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

Example of Format
%META:TOPICINFO{version="1.6" date="976762663" author="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, unx 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, unx time, seconds since start 1970

Notes:

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

META:TOPICPARENT

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, unx 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, unx 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:

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

The recommended sequence is:

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

Viewing Meta Data in Page Source

When viewing a topic the Raw Text link can be clicked to show the text of a topic (ie: 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.

Current support covers:

Variable usage: Comment:
%META{"form"}% Show form data, see TWikiForms
%META{"attachments"}% Show attachments, exclude hidden
Options for Attachments:  
all="on" Show ALL attachments (including hidden)
%META{"moved"}% Details of any topic moves
%META{"parent [options]"}% Show topic parent
Options for parent:  
dontrecurse="on" By default recurses up tree, at some cost
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.

-- JohnTalintyre - 29 Aug 2001
-- MikeMannix - 03 Dec 2001


 <<O>>  Difference Topic TWikiDocumentation (r1.31 - 07 Sep 2001 - MikeMannix)
Changed:
<
<

TWiki Reference Manual (01-Sep-2001)

>
>

TWiki Reference Manual (01-Sep-2001)

Changed:
<
<

>
>


 <<O>>  Difference Topic TWikiDocumentation (r1.30 - 07 Sep 2001 - MikeMannix)
Changed:
<
<

TWiki Webmaster Reference (ver. 01 Sep 2001)

>
>

TWiki Reference Manual (01-Sep-2001)

Changed:
<
<

This page contains all documentation topics as one long and complete reference sheet. Use the extended menu below to jump directly to sections. Doubleclick anywhere on-screen to return to the top of the page.

>
>

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

Changed:
<
<

(You can also browse the TWiki reference as individual pages from the full topics menu.) CHECK

TOC: No TOC in "TWiki.TWikiDocumentation"

>
>

TOC: No TOC in "TWiki.TWikiDocumentation"


 <<O>>  Difference Topic TWikiDocumentation (r1.29 - 01 Sep 2001 - MikeMannix)
Changed:
<
<

>
>

Changed:
<
<

>
>

Managing Topics

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

Overview

Use browser controls while viewing a topic, to change its 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].
  2. Select target web if other than the current web - chose Trash to delete a topic
  3. Enter the new topic name - default is current name
    NOTE: You will be warned if there are locks or if there is a name conflict.
  4. Select from the list of referring links any topics NOT to be updated with the new name (by default, all referring links will be updated).
  5. Click on [Rename/Move]: the topic will be renamed and links to the topic updated as requested.
    • If any of the referring pages are locked then they will be listed.
    • You can correct these later by again pressing [Rename/Move].

Referring Topics

Referring topics are found using the 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 refernces to the topic being changed.

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

About Deleting a Topic

Deleted topics are moved to the Trash web - 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.

Clearing the Trash

The Trash web should be be cleared periodically, by archiving the contents if required (recommended), then deleting the files from the Trash directory.

Redirecting from an Old Topic

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

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

Effect of Access Settings

Permissions affect the rename function in various ways. To rename a topic, you need both change and rename permissions. To alter refer4ing topics, you need change permission. See TWikiAccessControl for information on setting up access permissions.

How Rename/move Works

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

Known Limitations

Rename/move in 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 because of case differences. Other mismatches to 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]]

-- MikeMannix - 15 Sep 2001

Changed:
<
<

>
>

Managing Webs

Adding, renaming and deleting webs are manual operations done directly on the server

Overview

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

Adding a New Web

Adding new webs is quick and easy - you can have a basic web up and running in a couple of minutes:

  1. Create a new directory under twiki/data/, ex: twiki/data/Newweb
    • the name has to start with a capital and cannot be a WikiWord
  2. Copy in the contents of twiki/data/_default.

For detailed instructions, see TWiki Installation Guide: Adding a New Web.

Renaming or Deleting a Web

NOTE: If you plan to rename the Tharsis.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).

  1. Prepare your site: Search each web for links to the target web, searching topic text for Oldwebname., including the dot so you'll find references like Oldwebname.SomeTopic.
    • Make changes as required, to Newwebname.SomeTopic or better yet, to %MAINWEB%.SomeTopic.
  2. Edit the TWikiPreferences topic: Rename or delete the web from the WIKIWEBLIST variable.
  3. Edit the TWikiWebsTable topic: Rename or delete the web from the table.
  4. Login to the Tharsis server, via Telnet or FTP.
  5. Go to twiki/data and rename or remove the web directory.
  6. Go to twiki/templates and rename or remove the web directory if present.
  7. Go to twiki/pub and rename or remove the web directory if present.

-- MikeMannix - 14 Sep 2001


 <<O>>  Difference Topic TWikiDocumentation (r1.28 - 01 Sep 2001 - MikeMannix)
Changed:
<
<

(You can also browse the TWiki reference as individual pages from the full topics menu.)

>
>

(You can also browse the TWiki reference as individual pages from the full topics menu.) CHECK

Deleted:
<
<

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 mark-up for template-specific content. Templates are used to define page layout, and also to supplydefault content for new pages.

Major changes from the previous template system

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

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

Functional Specifications

  • Special template directives (or preprocessor commands) are embedded in normal templates.
  • Use of template directives is optional, templates work without them.
  • All template preprocessing is done in &TWiki::Store::readTemplate() so that the caller simply gets an expanded template file (the same as before).
  • Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
  • Directives:
    • %TMPL:INCLUDE{"file"}%: Includes a template file. The template directory of the current web is searched first, then the templates root (twiki/templates).
    • %TMPL:DEF{"var"}%: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
    • %TMPL:END%: Ends variable definition.
    • %TMPL:P{"var"}%: Prints a previously defined variable.
  • Variables are live in a global name space, there is no parameter passing.
  • Two-pass processing, so that you can use a variable before declaring it or after.
  • Templates and TWikiSkins work transparently and interchangeably. For example, you can create a skin that overloads just the twiki.tmpl, like twiki.print.tmpl, that redefines the header and footer.
  • NOTE: The template directives work only for templates, they do not get processed in topic text.

TWiki Master Template

All common parts are defined in a master template, twiki.tmpl, that all other templates use.

Template variable: Defines:
%TMPL:DEF{"sep"}% "|" separator
%TMPL:DEF{"htmldoctype"}% Start of all HTML pages
%TMPL:DEF{"standardheader"}% Standard header (ex: view, index, seach)
%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

Types of Template

There are two types of templates:

  • HTML Page Templates: Defines layout of Tharsis pages
  • Template Topics: Defines default text when you create a new topic

HTML Page Templates

Tharsis uses HTML template files for all actions like topic view, edit, preview and so on. This allows you to change the look and feel of all pages by editing just some template files.

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

  1. twiki/templates/$webName/$scriptName.tmpl
  2. twiki/templates/$scriptName.tmpl

Note: $webName is the name of the web (ex: Main), and $scriptName is the script (ex: view).

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

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

Template Topics

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

Topic Name: What it is:
WebTopicViewTemplate Help text shown when you view a non existing topic.
WebTopicNonWikiTemplate Help text shown when you view a non existing topic that has not a 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. The following search order applies when you create a new topic:

  1. The topic name specified by the templatetopic CGI parameter.
  2. WebTopicEditTemplate in the current web.
  3. WebTopicEditTemplate in the TWiki web.

Template Topics in Action

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

  • New example topic: (date format is YYYYxMMxDD)

Above form asks for a topic name. A hidden input tag of name "templatetopic" specifies the ExampleTopicTemplate as the template topic. Here is the HTML source of the form:

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

The "onlywikiname" parameter enforces WikiWords for topic names.

Note: Use can use the %WIKIUSERNAME% and %DATE% variables in your topic templates as the signature; those variables are expanded when a new topic is created. The standard topic signature is:
-- %WIKIUSERNAME% - %DATE%

Templates by Example

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

Base template oopsbase.tmpl

The first line declares the 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/Test/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify

testscreen.gif

Known Issues

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

-- PeterThoeny - 23 Jul 2001
-- MikeMannix - 14 Sep 2001



 <<O>>  Difference Topic TWikiDocumentation (r1.27 - 01 Sep 2001 - MikeMannix)
Changed:
<
<

>
>

TWiki Installation Guide

Installation instructions for the TWiki 01-Sep-2001 production release

Overview

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 OS and server that meet the system requirements. Documentation for other platforms is currently limited. For Windows, check TWiki:Codev/TWikiOnWindows. Search the TWiki:Codev web for other intallation notes.

Standard Installation

Request and download the TWiki 01-Sep-2001 distribution in Unix ZIP format from http://TWiki.org/download.html. (To install TWiki on SourceForge, for use on a software development project, read TWiki:Codev/SourceForgeHowTo.)

Step 1: Create & Configure the Directories

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

  • Create directory /home/httpd/twiki and unzip the TWiki distribution into this directory.
  • The twiki/bin directory of TWiki must be set as a cgi-bin directory. Add /home/httpd/twiki/bin to file /etc/httpd/httpd.conf with only ExecCGI option.
  • The twiki/pub directory of TWiki must be set so that it is visible as a URL. Add /home/httpd/twiki to file httpd.conf with normal access options (copy from /home/httpd/html ).
  • Now add ScriptAlias for /twiki/bin and Alias for /twiki to file httpd.conf .
    NOTE: The ScriptAlias must come before the Alias, otherwise, Apache will fail to correctly set up /twiki/bin/, by treating it as just another subdirectory of the /twiki/ alias.

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
    AllowOverride all
    Allow from all
 </Directory>
 <Directory "/home/httpd/twiki/pub">
    Options FollowSymLinks +Includes
    AllowOverride None
    Allow from all
 </Directory>

  • Restart Apache by /etc/rc.d/rc5.d/S85httpd restart .
  • Test that the twiki/bin directory is CGI-enabled by trying visiting it in your browser:
    • Enter the URL for the bin directory, http://yourdomain.com/twiki/bin/.
    • Your settings are OK if you get a message like "Forbidden. You don't have permission to access /twiki/bin/ on this server".
    • Settings are NOT correct if you get something like "Index of /twiki/bin" - recheck your httpd.conf file.

Step 1 for Non-Root Accounts

To install TWiki on a system where you don't have server administrator privileges, for example, on a hosted Web account:

  • Download and unzip TWiki on your local PC
  • Using the table below, create a directory structure on your host server
  • Upload the TWiki files by FTP (transfer as text except for the image files in pub)
TWiki dir: What it is: Where to copy: Example:
twiki/bin CGI bin cgi-enabled dir /home/smith/public_html/cgi-bin
twiki/lib library files same level as twiki/bin /home/smith/public_html/lib
twiki/pub public files htdoc enabled dir /home/smith/public_html/pub
twiki/data topic data outside of htdoc tree (for security) /home/smith/twiki/data
twiki/templates web templates outside of htdoc tree (for security) /home/smith/twiki/templates

Step 2: Set File Permissions

  • Make sure Perl 5 and the Perl CGI library are installed on your system. The default location of Perl is /usr/bin/perl. If it's elsewhere, change the path to Perl in the first line of each script in the twiki/bin directory, or create a symbolic link from /usr/bin/perl.
    • IMPORTANT: On ISP-hosted accounts, Perl CGI scripts usually require a .cgi extension to run. Some systems need .pl, the regular Perl extension. Modify all twiki/bin script filenames if necessary.
  • Set the file permission of all Perl scripts in the twiki/bin directory as executable to -rwxr-xr-x (755).
  • To be able to edit the Perl scripts and .tmpl files it is necessary to chown and chgrp -R twiki so all the files have the owner you want.
  • NOTE: This Guide assumes user nobody ownership for all files manipulated by the CGI scripts (executed by the Web server), and user twiki for all other files. You can:
    • replace nobody with another user if your server executes scripts under a different name (ex: default for Debian is www-data).
      • HINT: Run the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. It will show you the user name of the CGI scripts, a table listing all CGI environment variables, and a test of your twiki/lib/TWiki.cfg configuration file (you'll configure that in a minute).
    • replace user twiki with your own username
  • Set the permission of all files below twiki/data so that they are writable by user nobody. A simple way is to chmod them to -rw-rw-r-- (664) and to chown them to nobody.
  • Set the permission of the twiki/data directory and its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.
  • Set the permission of the twiki/pub directory and all its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.
  • NOTE: The twiki/data/*/*.txt,v RCS repository files in the installation package are locked by user nobody. If your CGI scripts are not running as user nobody, it's not possible to check in files (you'll see that the revision number won't increase after saving a topic). In this case, you need to unlock all repository files (check the RCS man pages) and lock them with a different user, ex www-data, or delete them all - new files will be automatically created the first time each topic is edited. A simple way to change ownership is with a search-and-replace in all files; for example, using sed:
    for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done

Step 3: Set the Main Configuration File

  • Edit the file twiki/lib/TWiki.cfg, setting the variables to your needs.
    • Set the file extension in the $scriptSuffix variable to cgi or pl if required.
    • Make sure RCS is installed. Set $rcsDir in twiki/lib/TWiki.cfg to mach the location of your RCS binaries.
  • Security issue: Directories twiki/data , twiki/templates and all its subdirectories should be set so that they are not visible as a URL. (Alternatively, move the directories to a place where they are not visible, and change the variables in twiki/lib/TWiki.cfg accordingly)
  • Test your settings by running the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. Check if your twiki/lib/TWiki.cfg configuration file settings are correct.

Step 4: Finish Up from Your Browser

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

Additional Server-Level Options

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

Enabling Authentication of Users

  • If TWiki is installed on a non-authenticated server - not using SSL - and you'd like to authenticate users:
    1. Rename file .htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. For details, consult the HTTP server documentation (for Apache server: [1], [2]). In particular, the following red part needs to be configured correctly:
      Redirect /urlpath/to/TWiki/index.html http://your.domain.com/urlpath/to/TWiki/bin/view
      AuthUserFile /filepath/to/TWiki/data/.htpasswd
      ErrorDocument 401 /urlpath/to/TWiki/bin/oops/TWiki/TWikiRegistration?template=oopsauth
      • NOTE: In case you renamed the CGI script files to have a file extension you need to reflect that in the edit, view, preview, etc entries in .htaccess.
      • NOTE: The browser should ask for login name and password when you click on the Edit link. In case .htaccess does not have the desired effect you need to enable it: Add "AllowOverride All" to the Directory section of access.conf for your twiki/bin directory.
    2. Copy the TWikiRegistrationPub topic to TWikiRegistration. Do that by either editing the topics in theTWiki web, or by renaming the .txt and .txt,v files in the twiki/data/TWiki directory.
      • HINT: You can customize the registration form by deleting or adding input tags. The name="" parameter of the input tags must start with: "Twk0..." (if this is an optional entry), or "Twk1..." (if this is a required entry). This ensures that the fields are processed correctly.
  • Register yourself in the TWikiRegistration topic.
    • NOTE: When a user registers, a new line with the username and encrypted password is added to the data/.htpasswd file. The .htpasswd file that comes with the TWiki installation includes user accounts for TWiki core team members that are used for testing on TWiki.org. You can edit the file and delete those lines.
  • Create a new topic to check if authentication works.
  • Edit the TWikiAdminGroup topic in the TWiki:Main web to include users with system administrator status.
  • Edit the TWikiPreferences topic in the TWiki:TWiki web to set access privileges.
  • Edit the WebPreferences topic in each web, if necessary: set access priviliges.

Adding a New Web

To create a new web:

  1. Create a new web data directory under twiki/data and check the file permission of the directory.
    • Use a name starting with characters A..Z, followed by a..z and/or 0..9 characters, but not a WikiWord.
  2. Copy all files from the twiki/data/_default directory to the new data directory, preserving the original files' owner, group and permissions (on Unix, use cp -p). The data files must be writable by the owner the CGI scripts are running on (usually, nobody).
    • HINT: You can set permissions of .txt and .txt,v files to -rw-rw-rw- (666) and then edit the topic using your browser; RCS will restore the file permissions correctly when saving the topic.
  3. Add the new web to the web list (visible in the upper right corner of each topic) by editing the site-level preferences, TWikiPreferences:
    • Add the new web to the %WIKIWEBLIST% variable.
  4. Update the web settings by editing the WebPreferences topic of the new web:
    • Customize the %WEBTOPICLIST% variable to contain the web-specific links you prefer.
    • Set the WEBBGCOLOR variable to a color. The number represents the unique color for the web.
    • Set Plugins, access privileges, custom variables, other web-level options (ex: %WEBCOPYRIGHT% can be set for an individual web).
  5. Add the new web to the color-coded web directory table by editing the TWikiWebsTable topic.
  6. Test the new web: view pages, create a new page.

That's it for a basic new web set-up!

Optionally, you can also:

  • Create custom web-specific templates in a new twiki/templates/Someweb directory (otherwise, templates are inherited from twiki/templates).
  • Add TWikiForms for form-based page input that's stored separately from the main free-form topic text.

NOTE: User home topics are located in the Tharsis.Main web - don't try to move them or create them in other webs. From any other web, user signatures have to point to Tharsis.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-2001 distribution.

-- PeterThoeny - 13 Sep 2001
-- MikeMannix - 03 Dec 2001

Changed:
<
<

>
>

TWiki Upgrade Guide

Upgrade from TWiki 01-Dec-2000 or TWiki 01-Sep-2001 to TWiki 01-Dec-2001 (previous to new full release)

Overview

This guide describes how to upgrade either from TWiki 01-Dec-2000 or TWiki 01-Sep-2001 to TWiki 01-Dec-2001.

  • The latest version of TWiki (01-Dec-2001) is a small incremental release over the 01-Sep-2001 version.
  • The 01-Sep-2001 version involves several major new features and numerous enhancements to the last full version (01-Dec-2000). The file system set-up is almost identical, but much of the underlying data structure and processes is new. With all the changes, the upgrade procedure is straightforward, and your existing page data is imported directly.

Upgrade Requirements

  • To upgrade from a 01-Dec-2000 or 01-Sep-2001 standard installation to the latest 01-Dec-2001 TWiki Production Release, follow the instructions below.

  • To upgrade from a Beta of the new release, or if you made custom modifications to the application, read through all new reference documentation, then use the procedure below as a guideline.

Major Changes from TWiki 01-Sep-2001

The latest 01-Dec-2001 release includes the following new features and enhancements compared to the 01-Sep-2001 release:

  • FormattedSearch - New format="" parameter in %SEARCH{}% variable for database like reporting.
  • Various bug fixes

Major Changes from TWiki 01-Dec-2000

The 01-Sep-2001 release includes the following new features and enhancements compared to the 01-Dec-2000 release:

  • TWikiPlugins - Easily install program enhancements using external plug-in modules. Developers can create plug-ins in Perl, with the TWiki Plugin API.
  • TWikiTemplates - New, more flexible template system.
  • TWikiSkins - Overwrite template headers and footers; page content is unaffected.
  • TWikiMetaData - New data format
  • TWiki.TWikiForms - Create multiple input forms per web; data is rendered in HTML tables.
  • ManagingTopics - Individual topics can be renamed, moved and deleted through the browser. Deleted topics are stored in a common Trash web.
  • Change passwords - Change and reset passwords using forms.
  • TOC (Table of Contents) - %TOC% variable generates a hierarchical table of contents from topic headings: <h1>...<h6>.
  • Arbitrary Text for WikiWord Links - Text formatting rules to generate automatic links from any combination of words and spaces.
  • Attachments Under Revision Control - Changes made to files attached to topics are now saved under revision control (RCS).
  • SuperAdministrator Group - Lets you to make the members of one user group - by default, TWikiAdminGroup - into TWiki superusers, with the ability to overwrite locked topics from the browser interface. (This gets around the problem of topic lockouts, caused by typos in access privilege definitions.)
  • HierarchicalNavigation uses new Meta Data variables to link hierarchically.
  • Convert to XHTML - Pages are rendered for display in XHTML 1.0, as far as possible without breaking HTML 3.2 compliance.

TWiki Directory Structure and File Names

The TWiki directory structure remains the same, with one exception, the TWiki configuration file and Perl modules have been moved from the twiki/bin directory into it's own twiki/lib directory tree. The following files have been renamed and moved:

From TWiki 01-Dec-2000: To TWiki 01-Dec-2001:
twiki/bin/wikicfg.pm twiki/lib/TWiki.cfg
twiki/bin/wiki.pm twiki/lib/TWiki.pm
twiki/bin/wikiaccess.pm twiki/lib/TWiki/Access.pm
twiki/bin/wikiprefs.pm twiki/lib/TWiki/Prefs.pm
twiki/bin/wikisearch.pm twiki/lib/TWiki/Search.pm
twiki/bin/wikistore.pm twiki/lib/TWiki/Store.pm

A new twiki/lib/TWiki/Plugins directory contains the new Plugin modules.

Standard Upgrade Procedure from 01-Sep-2001 to 01-Dec-2001 Release

This incremental update can be performed easily.

The following steps describe the upgrade assuming that $TWIKIROOT is the root of your current 01-Sep-2001 release.

  1. Back up and prepare:
    • Back up all existing TWiki directories $TWIKIROOT/bin, $TWIKIROOT/pub, $TWIKIROOT/data, $TWIKIROOT/templates.
    • Create a temporary directory and unpack the ZIP file there.
  2. Update files in TWiki root:
    • Overwrite all *.html and *.txt files in $TWIKIROOT with the new ones.
  3. Update template files:
    • Overwrite all template files in $TWIKIROOT/templates with the new ones.
  4. Update script files:
    • Overwrite all script files in $TWIKIROOT/bin with the new ones.
  5. Update library files:
    • Overwrite the TWiki.pm library in $TWIKIROOT/lib with the new one.
    • Overwrite all *.pm library files in $TWIKIROOT/lib/TWiki and $TWIKIROOT/lib/TWiki/Plugins with the new ones.
  6. Update data/TWiki files: (in case you want the updated docs)
    • Using your browser, merge the new TWiki.TWikiRegistration topic (or TWiki.TWikiRegistrationPub in case you used that one) into your existing TWiki.TWikiRegistration topic.
    • In the temporary twiki/data/TWiki directory where you unzipped the installation package:
      • Remove the files you do not want to upgrade: TWikiPreferences.*, TWikiWebsTable.*, WebNotify.*, WebPreferences.*, WebStatistics.* and all WebTopic* files.
      • In case the cgi-scripts are not running as user nobody: The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed the user of your cgi-scripts, i.e. www-data. A simple way to switch the locker of the RCS files is to use sed:
        for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done
    • Move all remaining *.txt and *.txt,v files from the temporary data/TWiki directory to your $TWIKIROOT/data/TWiki directory.
  7. Update pub/TWiki files:
    • Move the new pub/TWiki/TWikiDocGraphics directory into your $TWIKIROOT/pub/TWiki directory.

Standard Upgrade Procedure from 01-Dec-2000 to 01-Dec-2001 Release

The idea is to have the new and old installation work in parallel so that you can test the new installation before switching over. That way you can make the switch on your live TWiki installation within one minute without affecting the users.

Before Switch: After Switch:
Current 01-Dec-2000: New 01-Dec-2001: Obsolete 01-Dec-2000: New 01-Dec-2001:
twiki/templates/ twiki/templates2/ twiki/templates1/ twiki/templates/
twiki/bin/ twiki/bin/2/ (overwritten) twiki/bin/
(N/A) twiki/bin/lib/ (N/A) twiki/lib/
twiki/data/TWiki twiki/data/TWiki2 twiki/data/TWiki1 twiki/data/TWiki
(other directories do not change)

Alternatively you could move the existing installation away, install the 01-Dec-2001 release into it's place and move your webs and pub files back.

Follow this step-by-step guide to upgrade from the 01-Dec-2000 TWiki to the 01-Dec-2001 release, importing your original page data and related files:

Pre-Upgrade Preparation

Two major areas of TWiki functionality - TWikiTemplates and TWikiForms (input forms associated with a topic)- are entirely different in the new TWiki. If you've customized your templates or use Category Tables, read those sections before starting your upgrade.

The following steps describe the upgrade on Unix. Windows setup is very similar. It's assumed that $TWIKIROOT is the root of your current 01-Dec-2000 release, ex: export TWIKIROOT=/some/dir/

Step 1: Backup & Unpack

  1. Back up all existing TWiki directories twiki/bin, twiki/pub, twiki/data, twiki/templates.
  2. Create a temporary directory and unpack the ZIP file there:
    mkdir -p ~/tmp/
    cp -p ~/downloads/TWiki20011201.zip ~/tmp/
    cd ~/tmp/
    unzip ~/tmp/TWiki20011201.zip

Step 2: Upgrade TWiki document files

  1. Move the document files to your TWiki root ( twiki ):
    mv ~/tmp/TWiki*.html $TWIKIROOT
    mv ~/tmp/index.html $TWIKIROOT
    mv ~/tmp/readme.txt $TWIKIROOT
    mv ~/tmp/license.txt $TWIKIROOT

Step 3: Install new template files

  1. Move & rename the template directory to a temporary twiki/templates2 directory, ex:
    mv ~/tmp/templates $TWIKIROOT/templates2
  2. Pay attention to the file and directory permissions (security issue). Set file permissions, ex:
    chmod 644 *.cgi

Step 4: Install new data and pub files

  1. Move the TWiki web to a temporary TWiki2 twiki/data/TWiki2 directory. Do the same to files attached to this web, ex:
    mv ~/tmp/data/TWiki $TWIKIROOT/data/TWiki2
    mv ~/tmp/pub/TWiki $TWIKIROOT/pub/TWiki2
  2. Move & rename the Know web to a temporary twiki/data/Know2 directory, ex:
    mv ~/tmp/data/Know $TWIKIROOT/data/Know2
    mv ~/tmp/pub/Know $TWIKIROOT/pub/Know2
  3. Move the _default and Trash web, ex:
    mv ~/tmp/data/_default $TWIKIROOT/data
    mv ~/tmp/data/Trash $TWIKIROOT/data
  4. Move the MIME types file, ex:
    mv ~/tmp/data/mime.types $TWIKIROOT/data
  5. Move the TWiki logo files, ex:
    mv ~/tmp/pub/*.gif $TWIKIROOT/pub
  6. Pay attention to the file permissions of the TWiki2 and Know2 directories and its files. The files must be writable by the cgi-scripts (usually user nobody).
  7. In case the cgi-scripts are not running as user nobody: The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed the user of your cgi-scripts, i.e. www-data. A simple way to switch the locker of the RCS files is to use sed:
    for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done

Step 5: Install new CGI scripts

  1. Move & rename the CGI script directory to a temporary twiki/bin/2 directory, ex:
    mv ~/tmp/bin $TWIKIROOT/bin/2
  2. If necessary, change the script names to include the required extension, ex: .cgi
  3. Copy any additional scripts you might have from the 01-Dec-2000 release, ex:
    cp -p $TWIKIROOT/bin/somescript $TWIKIROOT/bin/2
  4. In case you use basic authentication, rename .htaccess.txt to .htaccess and customize it, ex:
    cd $TWIKIROOT/bin/2
    mv .htaccess.txt .htaccess
    diff ../.htaccess .
    and merge the content
  5. Pay attention to the file and directory permissions (security issue). Set permissions, ex:
    chmod 755 *.cgi

Step 6: Install new Perl library files

  1. Move the lib directory to a temporary twiki/bin/lib directory, ex:
    mv ~/tmp/lib $TWIKIROOT/bin
  2. Pay attention to the file and directory permissions (security issue). Set permissions, ex:
    chmod 644 *.pm

Step 7: Set configurations and test installation

  1. Merge the content of the old twiki/bin/wikicfg.pm into the new twiki/lib/TWiki.cfg configuration file. Use the diff command to find out the differences, ex:
    cd $TWIKIROOT/bin/lib
    diff ../wikicfg.pm TWiki.cfg
  2. Make sure to set the correct temporary location of templates and scripts, ex:
    $scriptUrlPath    = "/twiki/bin/2";
    $templateDir      = "/home/httpd/twiki/templates2";
  3. Do not merge the functions extendHandleCommonTags, extendGetRenderedVersionOutsidePRE, extendGetRenderedVersionInsidePRE from the old twiki/bin/wikicfg.pm. This is now handled by the Default plugin twiki/lib/TWiki/Plugins/Default.pm
  4. Test your new TWiki installation to see if you can view topics. Point your browser to the old installation and fix the URL to see the new installation, ex:
    • Old URL: http://localhost/cgi-bin/view
    • New URL: http://localhost/cgi-bin/2/view

Step 8: Update topics

You can do the following changes using your old TWiki 01-Dec-2000 or new TWiki 01-Dec-2001 installation. Pointing your browser to the old installation for edit-copy-edit-paste operations is recommended, so that users don't get surprised by meta data content showing up in topics.

  1. Remember that you now have two TWiki webs:
    • The original TWiki web.
    • The new TWiki2 web, which gets renamed to TWiki when you switch over the installation.
  2. In case you customized TWiki.TWikiRegistration, merge your changes back into TWiki2.TWikiRegistration.
  3. Copy TWiki.TWikiWebsTable to TWiki2.TWikiWebsTable.
    • Do the same for any other topics you might have created in the TWiki web.
  4. In TWiki2.TWikiPreferences, merge the old TWiki.TWikiPreferences settings and customize it.
    • Add your webs to WIKIWEBLIST
    • Set the WIKIWEBMASTER
    • Set the SMTPMAILHOST
  5. In WebPreferences of all webs, add or change the following web preferences: (see TWiki.WebPreferences)
    • Add a NOSEARCHALL in case you want to exclude the web from a web="all" search:
      * Set NOSEARCHALL = on
    • In WEBTOPICLIST, remove the %WEB% . {} decoration from the list (it is now in the templates), ex:
      * Set WEBTOPICLIST = <a href="WebHome">Home</a>
        | <a href="WebChanges">Changes</a>
        | <a href="WebIndex">Index</a>
        | <a href="WebSearch">Search</a>
        | Go <input type="text" name="topic" size="16" />
    • Add a these new preferences:
      * Set DENYWEBVIEW =
      * Set ALLOWWEBVIEW =
      * Set DENYWEBRENAME =
      * Set ALLOWWEBRENAME =
    • Set the FINALPREFERENCES:
      * Set FINALPREFERENCES = WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, DENYWEBRENAME, ALLOWWEBRENAME
  6. Optional: In WebSearch of all webs, replace content with this one line:
    %INCLUDE{"%TWIKIWEB%.WebSearch"}%
  7. Optional: In WebChanges of all webs, replace content with this one line:
    %INCLUDE{"%TWIKIWEB%.WebChanges"}%

Step 9: Customize template files

NOTE: Skip this step if you did not customize your template files.

  1. Remember that you have now two template directories:
    • The original twiki/templates.
    • The new twiki/templates2, which gets renamed to twiki/templates when you switch over the installation.
  2. Customized templates and skins need to be upgraded to the new TWikiTemplates. This isn't difficult, but you have be familiar with the new template set-up before starting the conversion. The safest way is to use the new templates as a base and to merge your changes back. Changes in new templates:
    • Templates are now rendered by TWiki. You can use all TextFormattingRules, but you have to escape unwanted ones. Also, remove empty lines unless you want a =<p /> tag added.
    • Added TWikiMetaData rendering.
  3. Form Templates replace the TWikiCategoryTables:
    • Create a replacement WebForm topic based on twikicatitems.tmpl in each web that uses a Category Table. See details in TWikiForms and compare with the settings in the Know2.WebPreferences topic.
      NOTE: Do not remove the twikicatitems.tmpl file, it is still used for topics that are of the old format.
    • Searches need to be adjusted to deal with format change. It is possible to define a regular expression search that can deal at the same time with topics in the old format and new format.
      • Example: List all topics in the Know web that have a TopicClassification? of PublicFAQ?:
        %SEARCH{ "[T]opicClassification.*?(td..td|value\=).*?[P]ublicFAQ" casesensitive="on" regex="on" nosearch="on" web="Know"}%
        (The [T] and [P] is done so that search does not find the topic where this search string is located in!)
      • Example: Create a link that lists all topics in the Know web with a TopicClassification? of PublicFAQ?:
        [[%SCRIPTURL%/search%SCRIPTSUFFIX%/Know/?scope=text
        &search=%5BT%5DopicClassification.*%3F%28td..td%7C
        value%5C%3D%29.*%3F%5BP%5DublicFAQ&regex=on][All Public FAQ]]

        All Public FAQ
  4. For each web that has a custom notedited.tmpl template, create an equivalent WebTopicEditTemplate to conform with the new TemplateTopics. The new format replaces the notedited.tmpl, notext.tmpl and notwiki.tmpl templates.

Step 10: Switch over to new installation

In this step, you move the working 01-Dec-2001 installation to the old 01-Dec-2000 installation, so that users don't have to change the URL.

  1. Test your new 01-Dec-2001 installation under twiki/bin/2/view to make sure everything works as expected.
    • NOTE: Don't worry about the Plugins, they'll work after the switch.
  2. Edit $TWIKIROOT/bin/2/TWiki.cfg and remove the /2 from $scriptUrlPath and $templateDir, ex:
    $scriptUrlPath    = "/twiki/bin";
    $templateDir      = "/home/httpd/twiki/templates";
  3. Rename the TWiki2 web to TWiki, including attachments, ex:
    cd $TWIKIROOT/data
    mv TWiki TWiki1
    mv TWiki2 TWiki
    cd $TWIKIROOT/pub
    mv TWiki TWiki1
    mv TWiki2 TWiki
  4. Rename the templates2 directory to templates, ex:
    cd $TWIKIROOT
    mv templates templates1
    mv templates2 templates
  5. Move the lib directory one level up from $TWIKIROOT/bin/lib to $TWIKIROOT/lib, ex:
    cd $TWIKIROOT
    mv bin/lib .
  6. Copy content of bin/2 to bin, ex:
    cd $TWIKIROOT/bin
    cp -p bin/2/* .
    cp -p bin/2/.htaccess .
  7. Point your browser to the original URL and make sure the relocated 01-Dec-2001 installation works as expected: check browsing, searching and user registration.
  8. Clean up and remove obsolete directories:
    • Remove directory $TWIKIROOT/bin/2
    • Remove directory $TWIKIROOT/templates1
    • Remove directory $TWIKIROOT/data/TWiki1
    • Remove directory $TWIKIROOT/pub/TWiki1
    • Remove temporary directory, ex: ~/tmp

Step 11: Test the TWiki Plugins

  1. Test the new TWikiPlugins by checking the Plugins settings in TWikiPreferences.
    • The EmptyPlugin, DefaultPlugin, and InterwikiPlugin should be preinstalled. To check the InterwikiPlugin, go to its page.
  2. If you have customized the functions extendHandleCommonTags, extendGetRenderedVersionOutsidePRE and extendGetRenderedVersionInsidePRE in twiki/bin/wikicfg.pm:
    • Merge those changes back into twiki/lib/TWiki/Plugins/Default.pm

General Format Changes

  • The format of the %GMTIME{"..."}% and %SERVERTIME{"..."}% variables is now "$hour:$min" instead of "hour:min". More in TWikiVariables.

  • ExtendingTableSyntax: Enhanced table syntax might have unwanted side effect: | *bold* | cells, |  center aligned  | and |   right aligned | cells, span multiple columns using | empty cells |||. More in TextFormattingRules.

  • Use Net::SMTP module instead of sendmail if installed.

  • Use <verbatim> ... </verbatim> tags instead of <pre> ... </pre> tags where appropriate. More in TextFormattingRules.

  • New variable %STARTINCLUDE% and %STOPINCLUDE% variables to control what gets included of a topic. More in TWikiVariables.

  • FileAttachment info is now stored as TWiki Meta Data.
    • Upgrading of imported pagess is done automatically after first edit, on save. "In memory" upgrade is done on topic view.
    • Attachments are now under revision control: $attachAsciiPath in TWiki.cfg defines which file types are stored in ASCII, otherwise, binary format is used. This means that the RCS version used should support binary files.

  • Handling for topic-specific templates like edit.new.tmpl has been removed and replaced by template topics in the new TWikiTemplates.

  • A new file warning.txt file can appear in the data directory. It may contain diagnostic info identifying problems that need fixing. This file could get fairly large if you have a lot of problems your site - you can delete it at any time.

Known Issues

-- JohnTalintyre - 18 Jul 2001
-- MikeMannix - 12 Sep 2001
-- PeterThoeny - 03 Dec 2001

Changed:
<
<

>
>

TWiki User Authentication

TWiki site access control and user activity tracking

Overview

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 three standard options for controlling user access:

  1. 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. Use SSL (Secure Sockets Layer; HTTPS) to authenticate and secure the whole server.
  3. Use Basic Authentication (.htaccess) to control access by protecting key scripts: attach, edit=, installpasswd, preview, rename, save, upload using the .htaccess file. The TWikiInstallationGuide has step-by-step instructions.

Partial Authentication

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

  • Normally, the REMOTE_USER environment variable is set for the scripts that are under authentication. If, for example, the edit, save and preview scripts are authenticated, but not view, you would get your WikiName in preview for the %WIKIUSERNAME% variable, but view will show TWikiGuest instead of your WikiName.

  • TWiki can be configured to remember the IP address/username pair whenever an authentication happens (edit topic, attach file). Once remembered, the non-authenticated scripts, like view, will show the correct username instead of TWikiGuest.

  • Enable this feature by setting the $doRememberRemoteUser flag in TWiki.cfg. TWiki then persistently stores the IP address/username pairs in the file, $remoteUserFilename, which is "$dataDir/remoteusers.txt" by default.

  • NOTE: This approach can fail if the IP address changes due to dynamically assigned IP addresses or proxy servers.

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

  • You are Main.guest

TWiki Username vs. Login Username

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

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

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

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

Tharsis can automatically map an intranet 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 Tharsis.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.

Change password

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.

Request for reset of password

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 receive a page with your new password appearing encrypted.

-- MikeMannix - 29 Aug 2001


 <<O>>  Difference Topic TWikiDocumentation (r1.26 - 30 Aug 2001 - MikeMannix)
Added:
>
>


Changed:
<
<

TWiki Meta Data

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

Overview

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

Meta Data Syntax

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

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

  • Each meta variable is on one line.

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

Example of Format
%META:TOPICINFO{version="1.6" date="976762663" author="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, unx 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, unx time, seconds since start 1970

Notes:

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

META:TOPICPARENT

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, unx 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, unx 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:

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

The recommended sequence is:

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

Viewing Meta Data in Page Source

When viewing a topic the Raw Text link can be clicked to show the text of a topic (ie: 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.

Current support covers:

Variable usage: Comment:
%META{"form"}% Show form data, see TWikiForms
%META{"attachments"}% Show attachments, exclude hidden
Options for Attachments:  
all="on" Show ALL attachments (including hidden)
%META{"moved"}% Details of any topic moves
%META{"parent [options]"}% Show topic parent
Options for parent:  
dontrecurse="on" By default recurses up tree, at some cost
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.

-- JohnTalintyre - 29 Aug 2001
-- MikeMannix - 03 Dec 2001

>
>

Merged into TWikiMetaData - this topic to be rolled back.


 <<O>>  Difference Topic TWikiDocumentation (r1.25 - 30 Aug 2001 - MikeMannix)
Deleted:
<
<

TWiki Username vs. Login Username

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

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

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

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

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

-- PeterThoeny - 16 May 2001


Changed:
<
<


>
>


TWiki Meta Data

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

Overview

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

Meta Data Syntax

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

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

  • Each meta variable is on one line.

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

Example of Format
%META:TOPICINFO{version="1.6" date="976762663" author="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, unx 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, unx time, seconds since start 1970

Notes:

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

META:TOPICPARENT

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, unx 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, unx 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:

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

The recommended sequence is:

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

Viewing Meta Data in Page Source

When viewing a topic the Raw Text link can be clicked to show the text of a topic (ie: 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.

Current support covers:

Variable usage: Comment:
%META{"form"}% Show form data, see TWikiForms
%META{"attachments"}% Show attachments, exclude hidden
Options for Attachments:  
all="on" Show ALL attachments (including hidden)
%META{"moved"}% Details of any topic moves
%META{"parent [options]"}% Show topic parent
Options for parent:  
dontrecurse="on" By default recurses up tree, at some cost
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.

-- JohnTalintyre - 29 Aug 2001
-- MikeMannix - 03 Dec 2001

Deleted:
<
<


Merged into TWikiMetaData - this topic to be rolled back.


Meta Data Rendering

Various meta data can be stored in topics - MetaDataDefinition

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

At present support is fairly basic:

Variable usage: Comment:
%META{"form"}% Show form data, see Form Templates
%META{"attachments"}% Show attachments, excluding hidden ones
options for attachments:
all="on" Show all attachments i.e. including hidden ones
%META{"moved"}% Details of any topic moves
%META{"parent [options]"}% Show topic parent
options for parent:
dontrecurse="on" By default recurses up tree, this has some cost
prefix="..." Prefix that goes before parents, but only if there are parents, default ""
suffix="..." Suffix, only appears if there are parents, default ""
seperator="..." Seperator between parents, default is " > "

Possible future additions:

  • Rendering of form data to alternate formats e.g. bullet lists
  • Specify a template to be used for rendering
Added:
>
>



 <<O>>  Difference Topic TWikiDocumentation (r1.24 - 30 Aug 2001 - MikeMannix)
Changed:
<
<

Related Topics: TWikiWeb?, TWikiHistory, TWikiPlannedFeatures, TWikiEnhancementRequests

>
>

Related Topics: TWikiSite, TWikiHistory, TWikiPlannedFeatures, TWikiEnhancementRequests


 <<O>>  Difference Topic TWikiDocumentation (r1.23 - 30 Aug 2001 - MikeMannix)
Changed:
<
<

TWiki Webmaster Documentation (ver. 01 Sep 2001)

>
>

TWiki Webmaster Reference (ver. 01 Sep 2001)

Changed:
<
<

All support topics are loaded here to create one long and complete documentation page. Use the extended menu below to jump directly to sections. Doubleclick anywhere on-screen to return to the top of the page.

>
>

This page contains all documentation topics as one long and complete reference sheet. Use the extended menu below to jump directly to sections. Doubleclick anywhere on-screen to return to the top of the page.

Changed:
<
<

(You can browse the TWiki guide by individual page from the full topics menu.)

>
>

(You can also browse the TWiki reference as individual pages from the full topics menu.)


 <<O>>  Difference Topic TWikiDocumentation (r1.22 - 29 Aug 2001 - JohnTalintyre)
Changed:
<
<

Note: This feature has been replaced by: TWikiForms

>
>


Merged into TWikiMetaData - this topic to be rolled back.


Meta Data Rendering

Various meta data can be stored in topics - MetaDataDefinition

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

At present support is fairly basic:

Variable usage: Comment:
%META{"form"}% Show form data, see Form Templates
%META{"attachments"}% Show attachments, excluding hidden ones
options for attachments:
all="on" Show all attachments i.e. including hidden ones
%META{"moved"}% Details of any topic moves
%META{"parent [options]"}% Show topic parent
options for parent:
dontrecurse="on" By default recurses up tree, this has some cost
prefix="..." Prefix that goes before parents, but only if there are parents, default ""
suffix="..." Suffix, only appears if there are parents, default ""
seperator="..." Seperator between parents, default is " > "

Possible future additions:

  • Rendering of form data to alternate formats e.g. bullet lists
  • Specify a template to be used for rendering
Added:
>
>


Added:
>
>


 <<O>>  Difference Topic TWikiDocumentation (r1.21 - 29 Aug 2001 - MikeMannix)
Changed:
<
<

Documentation of the TWiki Implementation (version 01 Dec 2001)

>
>

TWiki Webmaster Documentation (ver. 01 Sep 2001)

All support topics are loaded here to create one long and complete documentation page. Use the extended menu below to jump directly to sections. Doubleclick anywhere on-screen to return to the top of the page.

(You can browse the TWiki guide by individual page from the full topics menu.)

Changed:
<
<

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

>
>

Related Topics: TWikiWeb?, TWikiHistory, TWikiPlannedFeatures, TWikiEnhancementRequests


 <<O>>  Difference Topic TWikiDocumentation (r1.20 - 05 Mar 2001 - PeterThoeny)
Changed:
<
<

Documentation of the TWiki Implementation (version 01 Dec 2001)

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

Documentation of the TWiki Implementation (version 01 Dec 2001)

TOC: No TOC in "TWiki.TWikiDocumentation"

Deleted:
<
<

Deleted:
<
<

(1) Implementation Notes

Deleted:
<
<

Deleted:
<
<

(2) Installation Notes

Deleted:
<
<

Deleted:
<
<

(3) Upgrading Earlier Versions of TWiki

Deleted:
<
<

Deleted:
<
<

(4) TWiki Authentication

Deleted:
<
<

Deleted:
<
<

(5) TWiki Username vs. Login Username

Deleted:
<
<

Deleted:
<
<

(6) TWiki Access Control

Deleted:
<
<

Deleted:
<
<

(7) TWiki Templates

Deleted:
<
<

Deleted:
<
<

(8) TWiki Skins

Deleted:
<
<

Deleted:
<
<

(9) TWiki Variables

Deleted:
<
<

Deleted:
<
<

(10) Notification of Changes by Email

Deleted:
<
<

Deleted:
<
<

(11) TWiki Category Table

Deleted:
<
<

Deleted:
<
<

(12) TWiki Plugins

Deleted:
<
<

Deleted:
<
<

(13) TWiki Administration


 <<O>>  Difference Topic TWikiDocumentation (r1.19 - 17 Feb 2001 - PeterThoeny)
Changed:
<
<

  • (12) TWiki Administration
>
>

  • (12) TWiki Plugins
  • (13) TWiki Administration
Added:
>
>


(12) TWiki Plugins

TWiki Plugins

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

Overview

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

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

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

Preinstalled Plugins

TWiki comes with three Plugins as part of the standard installation.

  • DefaultPlugin optionally handles some legacy variables from older versions of TWiki. You can control this option from TWikiPreferences. (Perl programmers can also add rules for simple custom processing.)

  • EmptyPlugin is a fully functional module, minus active code; it does nothing and serves as a template for new Plugin development.

  • InterwikiPlugin is preinstalled but can be disabled or removed. Use it for shorthand linking to remote sites, ex: TWiki:Plugins expands to TWiki:Plugins on TWiki.org. You can edit the predefined set of of Wiki-related sites, and add your own.

Installing Plugins

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

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

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

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

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

  • Doc page: Read all available info about the Plugin; download the attached distribution files.
  • Dev page: Post feature requests, bug reports and general dev comments; topic title ends in Dev (SomePluginDev).
  • User support: Post installation, how to use type questions (and answers, if you have them) in the TWiki:Support web.

On-Site Pretesting

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

  • Method 1: Safely test on-the-fly by creating separate Production and Test branches in your live TWiki installation.
    • Duplicate the twiki/bin and twiki/lib directories for the Test version, adjusting the paths in the new lib/TWiki.cfg, the twiki/data; the twiki/templates and twiki/pub directories are shared.
    • Test Plugins and other new features in the Test installation until you're satisfied.
      • ALERT! If you modify topics using the new features, live users will likely see unfamiliar new META tags showing up on their pages - to avoid this, create and edit test-only topics to try out new features.
    • Copy the modified files to the Production installation. You can update a TWiki installation live and users won't even notice.

  • Method 2: List the Plugin under Test in the DISABLEDPLUGINS variable in TWikiPreferences. Redefine the DISABLEDPLUGINS variable in the Test web and do the testing there.

Managing Plugins

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

Setting Preferences

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

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

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

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

  1. One line description, used to form the bullets describing the Plugins in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Blah blah woof woof.
  2. Debug Plugin, output can be seen in data/debug.txt. Set to 0=off or 1=on:
    • Set DEBUG = 0
  • The settings can be retrieved as Preferences variables like %<pluginname>_<var>%, ex: %DEFAULTPLUGIN_SHORTDESCRIPTION% shows the description of the DefaultPlugin.

Listing Active Plugins

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

  • The %ACTIVATEDPLUGINS% variable lists activated Plugins by name. (This variable is displayed in TWikiPreferences for debugging use.)
  • The %PLUGINDESCRIPTIONS% variable displays a bullet list with a one-line description of each active Plugins. This variable is based on the %<plugin>_SHORTDESCRIPTION% Preferences variables of individual topics and is shown in TextFormattingRules.

DEMO: Automatically List Active Plugins Using Variables

Using %ACTIVATEDPLUGINS%:
On this TWiki site, the active Plugins are: DefaultPlugin, InterwikiPlugin, TWikiDrawPlugin, UpdateInfoPlugin.

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

  • DefaultPlugin: This plugin can be used to specify some simple custom rendering rules. It also renders deprecated *_text_* as bold italic text.
  • InterwikiPlugin: Link ExternalSite:Page text to external sites based on aliases defined in the InterWikis topic.
  • TWikiDrawPlugin: Drawing editor

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

  • For best performance, enable only the functions you really need. NOTE: outsidePREHandler and insidePREHandler are particularly expensive.

Predefined Hooks

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

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

Plugin Version Detection

To eliminate the incompatibility problems bound to arise from active open Plugin development, a Plugin versioning system and an API GetVersion detection routine are provided for automatic compatibility checking.

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

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

Creating Plugins

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

The DefaultPlugin Alternative

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

Anatomy of a Plugin

A basic TWiki Plugin consists of two elements:

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

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

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

Creating the Perl Module

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

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 EmptyPlugin. To copy the text, go to the page and:
    • click Edit
    • select all in the Edit box & copy
    • Cancel the edit
    • paste & save as a text file or new topic on your site
  2. Customize the template for your Plugin; you'll probably want to post a working version on your local TWiki site.
  3. Save your topic as a text file, for use in packaging and publishing your Plugin.

OUTLINE: Doc Topic Contents
Check EmptyPlugin 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.>"

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

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

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

Test Example: <Include an example of the Plugin in action: if it works, the installation was a success!>"

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

Packaging for Distribution

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

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

Publishing for Public Use

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

  1. Post the Plugin documentation topic in the TWiki:Plugins web:
  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.)

-- AndreaSterbini - 29 May 2001
-- PeterThoeny - 14 Sep 2001
-- MikeMannix - 03 Dec 2001

Changed:
<
<

(12) TWiki Administration

>
>

(13) TWiki Administration


 <<O>>  Difference Topic TWikiDocumentation (r1.18 - 20 Jan 2001 - PeterThoeny)
Changed:
<
<

  • (5) Wiki Username vs. Login Username
>
>

  • (5) TWiki Username vs. Login Username
Changed:
<
<

  • (7) Wiki Templates
  • (8) Wiki Variables
  • (9) Notification of Changes by Email
  • (10) TWiki Category Table
  • (11) TWiki Administration
>
>

  • (7) TWiki Templates
  • (8) TWiki Skins
  • (9) TWiki Variables
  • (10) Notification of Changes by Email
  • (11) TWiki Category Table
  • (12) TWiki Administration
Changed:
<
<

(5) Wiki Username vs. Login Username

>
>

(5) TWiki Username vs. Login Username

Changed:
<
<

(7) Wiki Templates

>
>

(7) TWiki Templates

Added:
>
>


(8) TWiki Skins

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

Activating Skins

A skin can be activated in two ways:

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

-- PeterThoeny - 14 Jul 2001

Changed:
<
<

(8) Wiki Variables

>
>

(9) TWiki Variables

Changed:
<
<

(9) Notification of Changes by Email

>
>

(10) Notification of Changes by Email

Changed:
<
<

(10) TWiki Category Table

>
>

(11) TWiki Category Table

Changed:
<
<

(11) TWiki Administration

>
>

(12) TWiki Administration


 <<O>>  Difference Topic TWikiDocumentation (r1.17 - 13 Nov 2000 - PeterThoeny)
Changed:
<
<

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

>
>

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

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


 <<O>>  Difference Topic TWikiDocumentation (r1.16 - 02 Nov 2000 - PeterThoeny)
Changed:
<
<

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

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


(1) Implementation Notes

TWiki System Requirements

Server and client system requirements for TWiki 01-Sep-2001

Overview

Maintaining minimum client and server requirements is necessary to keep TWiki deployment as broad as possible.

Server Requirements

TWiki is written in Perl 5, uses a number of shell commands, and requires RCS (Revision Control System), a GNU Free Software package. TWiki is developed in a basic Linux/Apache environment. It also works with Microsoft Windows, and should have no problem on any other platform that meets the requirements:

Required Server Environment
Resource Unix Windows
Perl 5.005_03 or higher
Non standard Perl modules Net::SMTP (or sendmail) Net::SMTP, MIME::Base64, Digest::SHA1
RCS 5.7 or higher
Other external programs ls, fgrep, egrep
Web server Apache; others (with support for CGI, authentication, extended path) *

Current documentation covers Linux only. A TWikiOnWindows installation guide is next.

Client Requirements

The TWiki standard installation has extremely low browser requirements:

  • HTML 3.2 compliant
  • generates XHTML 1.0 pages that are compatible with HTML 3.2
  • minimal use of JavaScript in the user interface (degrades gracefully)
  • no cookies
  • no CSS

You can easily add capabilities, through customizing the templates, for one, while tailoring the browser requirements to your situation.

Known Issues

  • The new TWikiPlugins feature currently does not have compatibility guidelines for developers. Plugins can require just about anything: browser-specific functions, stylesheets (CSS), DHTML, Java applets, cookies.

-- MikeMannix - 15 Sep 2001


(2) Installation Notes


(3) Upgrading Earlier Versions of TWiki


(4) TWiki Authentication

Changed:
<
<

(1) Wiki Username vs. Login Username

>
>

(5) Wiki Username vs. Login Username

Changed:
<
<

(2) TWiki Access Control

>
>

(6) TWiki Access Control

Changed:
<
<

(3) Wiki Templates

>
>

(7) Wiki Templates

Changed:
<
<

(4) Wiki Variables

>
>

(8) Wiki Variables

Changed:
<
<

(5) Notification of Changes by Email

>
>

(9) Notification of Changes by Email

Changed:
<
<

(6) TWiki Category Table

>
>

(10) TWiki Category Table

Changed:
<
<

>
>

Changed:
<
<

(7) Implementation Notes

>
>

(11) TWiki Administration

Changed:
<
<


(8) Installation Notes


(9) Upgrading Earlier Versions of TWiki
>
>


 <<O>>  Difference Topic TWikiDocumentation (r1.15 - 24 Oct 2000 - PeterThoeny)
Changed:
<
<

  • (2) Wiki Templates
  • (3) Wiki Variables
  • (4) Notification of Changes by Email
  • (5) TWiki Category Table
  • (6) Implementation Notes
  • (7) Installation Notes
  • (8) Upgrading Earlier Versions of TWiki
>
>

  • (2) TWiki Access Control
  • (3) Wiki Templates
  • (4) Wiki Variables
  • (5) Notification of Changes by Email
  • (6) TWiki Category Table
  • (7) Implementation Notes
  • (8) Installation Notes
  • (9) Upgrading Earlier Versions of TWiki
Added:
>
>


(2) TWiki Access Control

TWiki Access Control

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

Overview

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

An Important Control Consideration

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

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

  • Peer editing - the ability to rearrange anything on a page - keeps topics focussed.

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

As a collaboration guideline:

  • Create broad groups (more and varied input), and...
  • Avoid creating view-only users (if you can read it, you can contribute to it).

Users and Groups

Access control is based on users and groups. Users are defined by their WikiNames, an then organized into unlimited combinations under different user groups.

Managing Users

A user is created by with the TWikiRegistration form. The process generates a topic in the Main web in the new user's WikiName. The default visitor name is TWikiGuest.

  • Users can be authenticated using Basic Authentication or SSL. TWikiUserAuthentication is required in order to track user identities.

Managing Groups

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

  1. Create a new topic with A name that ends in Group, SomeGroup
  2. Define two variables:
    • Set GROUP = < list of users and groups >
    • Set ALLOWTOPICCHANGE = < list of users and groups >

  • GROUP is a comma-separated list of users and of other groups:
        Set GROUP = Main.SomeUser, Main.OtherUser, Main.SomeOtherGroup

  • ALLOWTOPICCHANGE defines who is allowed to change the group topic; it is a comma delimited list of users and groups. You typically want to restrict that to the members of the group itself, so it should contain the name of the topic,
        Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup
    for the TWikiAdminGroup topic. (This prevents users not in the group from editing the topic and from gaining unauthorized membership to the group.)

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 attaching files to it; both privileges are assigned together.

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

  • DENYTOPICCHANGE defines users or groups that are not allowed to make changes to the topic. It is a comma delimited list of users and groups. Example:
        * Set DENYTOPICCHANGE = Main.SomeBadBoy, Main.SomeBadGirl, Main.SomeHackerGroup

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

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

Deny Editing by Web

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

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

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

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

Restricting Rename Access

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

Deny Renaming by Topic

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

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

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

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

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

Deny Renaming by Web

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

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

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

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

Restricting Read Access

You can define restrictions of who is allowed to view a Tharsis web.

  • Define one or both of these variable in the WebPreferences topic:
    • Set DENYWEBVIEW = < list of users and groups >
    • Set ALLOWWEBVIEW = < list of users and groups >

Known Issues

  • The view restriction is not suitable for very sensitive content since there is a way to circumvent the read access restriction.
  • Read access restriction only works if the view script is authenticated, that means that users need to log on also just to read topics. TWikiInstallationGuide has more on Basic Authentication based on the .htaccess file.

Selective Unrestricted Web Access

  • There is a workaround if you prefer to have unrestricted access to view topics located in normal webs, and to authenticate users only for webs where view restriction is enabled:
    1. Omit the view script from the .htaccess file.
    2. Enable the $doRememberRemoteUser flag in lib/TWiki.cfg as described in TWikiUserAuthentication. Tharsis will now remember the IP address of an authenticated user.
    3. Copy the view script to viewauth (or better, create a symbolic link)
    4. Add viewauth to the list of authenticated scripts in the .htaccess file.
      • When a user accesses a web where you enabled view restriction, Tharsis 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.
      • If you enable view restriction for a web, it is recommended to restrict search "all webs" from searching this web. Enable this restriction with the NOSEARCHALL variable in its WebPreferences, like:
        • Set NOSEARCHALL = on
      • It is not recommended to restrict view access to individual topics since all content is searchable within a web.

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 it no-one can edit it from a browser. To avoid this:

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

-- MikeMannix - 02 Dec 2001

Changed:
<
<

(2) Wiki Templates

>
>

(3) Wiki Templates

Changed:
<
<

(3) Wiki Variables

>
>

(4) Wiki Variables

Changed:
<
<

(4) Notification of Changes by Email

>
>

(5) Notification of Changes by Email

Changed:
<
<

(5) TWiki Category Table

>
>

(6) TWiki Category Table

Changed:
<
<

(6) Implementation Notes

>
>

(7) Implementation Notes

Changed:
<
<

(7) Installation Notes

>
>

(8) Installation Notes

Changed:
<
<

(8) Upgrading Earlier Versions of TWiki

>
>

(9) Upgrading Earlier Versions of TWiki


 <<O>>  Difference Topic TWikiDocumentation (r1.14 - 21 Aug 2000 - PeterThoeny)
Changed:
<
<

  • (8) Upgrading Earlier Versions to TWiki 01 Mai 2000
>
>

  • (8) Upgrading Earlier Versions of TWiki
Changed:
<
<

TWiki Username vs. Login Username

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

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

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

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

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

-- PeterThoeny - 16 May 2001

>
>

TWiki Username vs. Login Username

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

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

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

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

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

-- PeterThoeny - 16 May 2001

Changed:
<
<

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 mark-up for template-specific content. Templates are used to define page layout, and also to supplydefault content for new pages.

Major changes from the previous template system

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

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

Functional Specifications

  • Special template directives (or preprocessor commands) are embedded in normal templates.
  • Use of template directives is optional, templates work without them.
  • All template preprocessing is done in &TWiki::Store::readTemplate() so that the caller simply gets an expanded template file (the same as before).
  • Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
  • Directives:
    • %TMPL:INCLUDE{"file"}%: Includes a template file. The template directory of the current web is searched first, then the templates root (twiki/templates).
    • %TMPL:DEF{"var"}%: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
    • %TMPL:END%: Ends variable definition.
    • %TMPL:P{"var"}%: Prints a previously defined variable.
  • Variables are live in a global name space, there is no parameter passing.
  • Two-pass processing, so that you can use a variable before declaring it or after.
  • Templates and TWikiSkins work transparently and interchangeably. For example, you can create a skin that overloads just the twiki.tmpl, like twiki.print.tmpl, that redefines the header and footer.
  • NOTE: The template directives work only for templates, they do not get processed in topic text.

TWiki Master Template

All common parts are defined in a master template, twiki.tmpl, that all other templates use.

Template variable: Defines:
%TMPL:DEF{"sep"}% "|" separator
%TMPL:DEF{"htmldoctype"}% Start of all HTML pages
%TMPL:DEF{"standardheader"}% Standard header (ex: view, index, seach)
%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

Types of Template

There are two types of templates:

  • HTML Page Templates: Defines layout of Tharsis pages
  • Template Topics: Defines default text when you create a new topic

HTML Page Templates

Tharsis uses HTML template files for all actions like topic view, edit, preview and so on. This allows you to change the look and feel of all pages by editing just some template files.

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

  1. twiki/templates/$webName/$scriptName.tmpl
  2. twiki/templates/$scriptName.tmpl

Note: $webName is the name of the web (ex: Main), and $scriptName is the script (ex: view).

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

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

Template Topics

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

Topic Name: What it is:
WebTopicViewTemplate Help text shown when you view a non existing topic.
WebTopicNonWikiTemplate Help text shown when you view a non existing topic that has not a 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. The following search order applies when you create a new topic:

  1. The topic name specified by the templatetopic CGI parameter.
  2. WebTopicEditTemplate in the current web.
  3. WebTopicEditTemplate in the TWiki web.

Template Topics in Action

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

  • New example topic: (date format is YYYYxMMxDD)

Above form asks for a topic name. A hidden input tag of name "templatetopic" specifies the ExampleTopicTemplate as the template topic. Here is the HTML source of the form:

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

The "onlywikiname" parameter enforces WikiWords for topic names.

Note: Use can use the %WIKIUSERNAME% and %DATE% variables in your topic templates as the signature; those variables are expanded when a new topic is created. The standard topic signature is:
-- %WIKIUSERNAME% - %DATE%

Templates by Example

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

Base template oopsbase.tmpl

The first line declares the 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/Test/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify

testscreen.gif

Known Issues

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

-- PeterThoeny - 23 Jul 2001
-- MikeMannix - 14 Sep 2001

>
>

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 mark-up for template-specific content. Templates are used to define page layout, and also to supplydefault content for new pages.

Major changes from the previous template system

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

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

Functional Specifications

  • Special template directives (or preprocessor commands) are embedded in normal templates.
  • Use of template directives is optional, templates work without them.
  • All template preprocessing is done in &TWiki::Store::readTemplate() so that the caller simply gets an expanded template file (the same as before).
  • Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
  • Directives:
    • %TMPL:INCLUDE{"file"}%: Includes a template file. The template directory of the current web is searched first, then the templates root (twiki/templates).
    • %TMPL:DEF{"var"}%: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
    • %TMPL:END%: Ends variable definition.
    • %TMPL:P{"var"}%: Prints a previously defined variable.
  • Variables are live in a global name space, there is no parameter passing.
  • Two-pass processing, so that you can use a variable before declaring it or after.
  • Templates and TWikiSkins work transparently and interchangeably. For example, you can create a skin that overloads just the twiki.tmpl, like twiki.print.tmpl, that redefines the header and footer.
  • NOTE: The template directives work only for templates, they do not get processed in topic text.

TWiki Master Template

All common parts are defined in a master template, twiki.tmpl, that all other templates use.

Template variable: Defines:
%TMPL:DEF{"sep"}% "|" separator
%TMPL:DEF{"htmldoctype"}% Start of all HTML pages
%TMPL:DEF{"standardheader"}% Standard header (ex: view, index, seach)
%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

Types of Template

There are two types of templates:

  • HTML Page Templates: Defines layout of Tharsis pages
  • Template Topics: Defines default text when you create a new topic

HTML Page Templates

Tharsis uses HTML template files for all actions like topic view, edit, preview and so on. This allows you to change the look and feel of all pages by editing just some template files.

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

  1. twiki/templates/$webName/$scriptName.tmpl
  2. twiki/templates/$scriptName.tmpl

Note: $webName is the name of the web (ex: Main), and $scriptName is the script (ex: view).

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

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

Template Topics

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

Topic Name: What it is:
WebTopicViewTemplate Help text shown when you view a non existing topic.
WebTopicNonWikiTemplate Help text shown when you view a non existing topic that has not a 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. The following search order applies when you create a new topic:

  1. The topic name specified by the templatetopic CGI parameter.
  2. WebTopicEditTemplate in the current web.
  3. WebTopicEditTemplate in the TWiki web.

Template Topics in Action

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

  • New example topic: (date format is YYYYxMMxDD)

Above form asks for a topic name. A hidden input tag of name "templatetopic" specifies the ExampleTopicTemplate as the template topic. Here is the HTML source of the form:

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

The "onlywikiname" parameter enforces WikiWords for topic names.

Note: Use can use the %WIKIUSERNAME% and %DATE% variables in your topic templates as the signature; those variables are expanded when a new topic is created. The standard topic signature is:
-- %WIKIUSERNAME% - %DATE%

Templates by Example

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

Base template oopsbase.tmpl

The first line declares the 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/Test/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify

testscreen.gif

Known Issues

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

-- PeterThoeny - 23 Jul 2001
-- MikeMannix - 14 Sep 2001

Changed:
<
<

TWiki Variables

Text strings expanded on the fly to display data or system info

Overview

TWikiVariables are text strings - %VARIABLE% - that expand into content whenever a page is opened. Variables are replaced by their actual values: stored data, or system info (like the date, or the current user). There are predefined variables, and Preference variables that you set. You can also define custom variables, with new names and values.

Predefined Variables

Most predefined variables return values that were either defined when TWiki was installed, or taken from server info (like current username, or date and time). Many of the variables let you control how the formatted results appear.

Tharsis expands the following variables (enclosed in % percent signs):

Variable: Expanded to:
%WIKIHOMEURL% The base script URL of Tharsis, is the link of the Home icon in the upper left corner, is http://tharsis-gate.org/twiki
%SCRIPTURL% The script URL of Tharsis, is http://www.tharsis-gate.org/twiki/bin
%SCRIPTURLPATH% The path of the script URL of Tharsis, is /twiki/bin
%SCRIPTSUFFIX% The script suffix, ex: .pl, .cgi is
%PUBURL% The public URL of TWiki, is http://www.tharsis-gate.org/twiki/pub
%PUBURLPATH% The path of the public URL of Tharsis, is /twiki/pub
%ATTACHURL% The attachment URL of the current topic, is http://www.tharsis-gate.org/twiki/pub/TWiki/TWikiVariables
Example: If you attach a file you can refer to it as %ATTACHURL%/image.gif
%ATTACHURLPATH% The path of the attachment URL of the current topic, is /twiki/pub/TWiki/TWikiVariables
%URLPARAM{"name"}% Returns the value of a URL parameter. Ex: %URLPARAM{"skin"}% returns print for a .../view/TWiki/TWikiVariables?skin=print URL. Is
%WIKITOOLNAME% Name of wiki tool, is Tharsis
%WIKIVERSION% Wiki tool version is 01 Dec 2001
%USERNAME% Your login username is guest
%WIKINAME% Your Wiki username. Same as %USERNAME% if not defined in the TWikiUsers topic. Is guest
%WIKIUSERNAME% Your %WIKINAME% including the Main web name. Usefull for signatures. Is Main.guest
%MAINWEB% The Main web containing TWikiUsers, OfficeLocations? and TWikiGroups. Is Main
%TWIKIWEB% The web containing all documentation and configuration of Tharsis is TWiki
%WEB% The current web is TWiki
%BASEWEB% The web name where the includes started, e.g. the web of the first topic of nested includes. Same as %WEB% in case there is no include.
%INCLUDINGWEB% The web name of the topic that includes the current topic. Same as %WEB% in case there is no include.
%HOMETOPIC% The home topic in each web. Is WebHome
%NOTIFYTOPIC% The notify topic in each web. Is WebNotify
%WIKIUSERSTOPIC% The index topic of all registered users. Is TWikiUsers
%WIKIPREFSTOPIC% The web preferences topic. Is TWikiPreferences
%WEBPREFSTOPIC% The web preferences topic. Is WebPreferences
%STATISTICSTOPIC% The web statistics topic. Is WebStatistics
%TOPIC% The current topic name, is TWikiVariables
%BASETOPIC% The name of the topic where the includes started, e.g. the first topic of nested includes. Same as %TOPIC% in case there is no include.
%INCLUDINGTOPIC% The name of the topic that includes the current topic. Same as %TOPIC% in case there is no include.
%SPACEDTOPIC% The current topic name with added spaces, for regular expression search of Ref-By, is TWiki%20*Variables
%TOPICLIST{"format"}% Topic index of a web. The "format" defines the format of one topic item. It may include variables: The $name variable gets expanded to the topic name; the $web variable gets expanded to the name of the web. Parameters are format, separator and web:
Parameter: Description: Default:
"format" Format of one line, may include $name and $web variables "$name"
format="format" (Alternative to above) "$name"
separator=", " line separator "\n" (new line)
web="Name" Name of web Current web
Examples:
%TOPICLIST{"   * $web.$name"}% creates a bullet list of all topics.
%TOPICLIST{separator=", "}% creates a comma separated list of all topics.
%TOPICLIST{" <option>$name</option>"}% creates an option list (for drop down menus).
%WEBLIST{"format"}% Web index, e.g. list of all webs. Hidden webs are excluded, e.g. webs with a NOSEARCHALL=on preference variable. The "format" defines the format of one web item. The $name variable gets expanded to the name of the web, $qname gets expanded to double quoted name, $marker to marker where web matches selection. Parameters are format, separator and web:
Parameter: Description: Default:
"format" Format of one line, may include $name variable "$name"
format="format" (Alternative to above) "$name"
separator=", " line separator "\n" (new line)
webs="public" comma sep list of Web, public expands to all non-hidden "public"
marker="selected" Text for $marker where item matches selection, otherwise equals "" "selected"
selection="%WEB%" Current value to be selected in list section="%WEB%"
Examples:
%WEBLIST{"   * [[$name.WebHome]]"}% creates a bullet list of all webs.
%WEBLIST{"" webs="Trash,public" selection="TWiki" separator=" "}% Dropdown of all public Webs + Trash Web, current Web highlighted.
%GMTIME% GM time, is Thu Oct 17 01:20:09 2019
%GMTIME{"format"}% Formatted GM time based on time variables.
Variable: Unit: Example
$seconds seconds 59
$minutes minutes 59
$hours hours 23
$day day of month 31
$month month in ISO format Dec
$mo 2 digit month 12
$year 4 digit year 1999
$ye 2 digit year 99
Variables can be shortened to 3 characters. Example:
%GMTIME{"$day $month, $year - $hour:$min:$sec"}% is
17 Oct, 2019 - 01:20:09
%SERVERTIME% Server time, is Thu Oct 17 12:20:09 2019
%SERVERTIME{"format"}% Formatted server time.
Example: %SERVERTIME{"$hou:$min"}% is 12:20
%HTTP_HOST% HTTP_HOST environment variable, is www.tharsis-gate.org
%REMOTE_ADDR% REMOTE_ADDR environment variable, is 35.175.191.168
%REMOTE_PORT% REMOTE_PORT environment variable, is 59676
%REMOTE_USER% REMOTE_USER environment variable, is
%INCLUDE{"page" ...}% Server side include to IncludeTopicsAndWebPages. Parameters are page name, and an optional pattern="(reg-exp)". The page name is:
"SomeTopic" The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}%
"Web.Topic" A topic in another web, i.e. %INCLUDE{"TWiki.TWikiWebsTable"}%
"http://..." A full qualified URL, i.e. %INCLUDE{"http://twiki.org/"}%
%STARTINCLUDE% If present in included topic, start to include text from this location up to the end, or up to the location of the %STOPINCLUDE% variable. A normal view of the topic shows everyting exept the %STARTINCLUDE% variable itself.
%STOPINCLUDE% If present in included topic, stop to include text at this location and ignore the remaining text. A normal view of the topic shows everyting exept the %STOPINCLUDE% variable itself.
%TOC% Table of Contents of current topic.
%TOC{"SomeTopic" ...}% Table of Contents. Shows a TOC that is generated automatically based on headings of a topic. Headings in WikiSyntax ("---++ text") and HTML ("<h2>text<h2>") are taken into account. (But not "<H2>text</H2>", which can be used to exclude a heading from the TOC.) Parameters are topic name, web and depth:
Parameter: Description: Default:
"TopicName" topic name Current topic
web="Name" Name of web Current web
depth="2" Limit depth of headings shown in TOC 6
Examples: %TOC{depth="2"}%, %TOC{"TWikiDocumentation" web="TWiki"}%
%SEARCH{"text" ...}% Inline search, shows a search result embedded in a topic. Parameters are the search term, web, scope, order and many more: [1]
Parameter: Description: Default:
"text" Search term. (Is a regular expression or literal, depending on the regex parameter) required
search="text" (Alternative to above) N/A
web="Name"
web="Main Know"
web="all"
Wiki web to search: A web, a list of webs separated by whitespace, or all webs. [2] Current web
scope="topic"
scope="text"
Search topic name (title) or in the text (body) of the topic Topic text (body)
order="topic"
order="modified"
order="editby"
Sort the results of search by the topic names, last modified time, or last editor Sort by topic name
limit="all"
limit="16"
Limit the number of results returned All results
regex="on" RegularExpression search Literal search
reverse="on" Reverse the direction of the search Ascending search
casesensitive="on" Case sensitive search Ignore case
nosummary="on" Show topic title only Show topic summary
bookview="on" BookView search, e.g. show complete topic text Show topic summary
nosearch="on" Suppress search string Show search string
noheader="on" Suppress search header
Topics: Changed: By:
Show search header
nototal="on" Do not show number of topics found Show number
format="..." Flexible custom result formatting: see FormattedSearch for usage Results in table
Example: %SEARCH{"wiki" web="Main" scope="topic"}%
%METASEARCH{...}% Special search of meta data
Parameter: Description: Default:
type="topicmoved" What sort of search is required?
"topicmoved" if search for a topic that may have been moved
"parent" if searcing for topics that have a specific parent i.e. its children
required
web="%WEB%" Wiki web to search: A web, a list of webs separated by whitespace, or all webs. required
topic="%TOPIC%" The topic the search relates to required
title="Title" Text the is pre-pended to any search results required
Example: %METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%, you may want to use this in WebTopicViewTemplate and WebTopicNonWikiTemplate
%METASEARCH{type="parent" web="%WEB%" topic="%TOPIC%" title="Children: "}%
%VAR{"NAME" web="Web"}% Get a preference value from a web other then the current one. Example: To get %WEBBGCOLOR% of the Main web write %VAR{"WEBBGCOLOR" web="Main"}%, is #FFFFC0

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

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

Preferences Variables

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

Variable: Level: What:
%WIKIWEBMASTER% SL Webmaster email address (sender of email notifications) , is fantom@tharsis.dyndns.org
%WIKIWEBLIST% SL List of Tharsis webs (in upper right corner of topics)
%WEBTOPICLIST% WL Common links of web (second line of topics)
%WEBCOPYRIGHT% SL , WL Copyright notice (bottom right corner of topics)
%WEBBGCOLOR% WL Background color of web
%NOSEARCHALL% WL Exclude web from a web="all" search (set variable to on for hidden webs)
%NEWTOPICBGCOLOR% SL , UL Background color of non existing topic. ( UL needs authentication for topic views )
%NEWTOPICFONTCOLOR% SL , UL Font color of non existing topic. ( UL needs authentication for topic views )
%EDITBOXWIDTH% SL , UL Horizontal size of edit box, is 70
%EDITBOXHEIGHT% SL , UL Vertical size of edit box, is 15
%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: checked="checked"
%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:
%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:
%HTTP_EQUIV_ON_VIEW% SL http-equiv meta tags for view, rdiff, attach, search* scripts.
%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.
%DENYWEBCHANGE% WL List of users and groups who are not allowed to change topics in the Tharsis web. (More in TWikiAccessControl)
%ALLOWWEBCHANGE% WL List of users and groups who are allowed to change topics in the Tharsis web. (More in TWikiAccessControl)
%DENYTOPICCHANGE% (any topic) List of users and groups who are not allowed to change the current topic. (More in TWikiAccessControl)
%ALLOWTOPICCHANGE% (any topic) List of users and groups who are allowed to change the current topic. (More in TWikiAccessControl)
%DENYWEBRENAME% WL List of users and groups who are not allowed to rename topics in the Tharsis web. (More in TWikiAccessControl)
%ALLOWWEBRENAME% WL List of users and groups who are allowed to rename topics in the Tharsis web. (More in TWikiAccessControl)
%DENYTOPICRENAME% (any topic) List of users and groups who are not allowed to rename the current topic. (More in TWikiAccessControl)
%ALLOWTOPICRENAME% (any topic) List of users and groups who are allowed to rename the current topic. (More in TWikiAccessControl)
%FINALPREFERENCES% SL , WL List of preferences that are not allowed to be overridden by next level preferences

Setting Preferences

  • The syntax for Preferences variables is the same anywhere in TWiki. In Edit mode, from the start of a new line:
    [6 spaces] * [space] Set [space] VARIABLENAME [space] = [value]
    Example:
    • Set VARIABLENAME = value

Creating Custom Variables

  • You can add your own preference variables for an entire site, a single web, or a single topic, using the standard syntax. Whatever you include in your variable will be expanded on display, and treated exactly as if it had been written out. So you can place formatted text, page links, image paths.

Example: Create a custom logo variable
  • To place a logo anywhere in a web by typing %MYLOGO%, simply define the variable on the web's WebPreferences page. You also have to upload logo.gif - this can be done by attaching a file to LogoTopic (any topic name you choose):
    • Set MYLOGO = %PUBURL%/%MAINWEB%/LogoTopic/logo.gif

-- PeterThoeny - 13 Sep 2001
-- MikeMannix - 30 Nov 2001

>
>

TWiki Variables

Text strings expanded on the fly to display data or system info

Overview

TWikiVariables are text strings - %VARIABLE% - that expand into content whenever a page is opened. Variables are replaced by their actual values: stored data, or system info (like the date, or the current user). There are predefined variables, and Preference variables that you set. You can also define custom variables, with new names and values.

Predefined Variables

Most predefined variables return values that were either defined when TWiki was installed, or taken from server info (like current username, or date and time). Many of the variables let you control how the formatted results appear.

Tharsis expands the following variables (enclosed in % percent signs):

Variable: Expanded to:
%WIKIHOMEURL% The base script URL of Tharsis, is the link of the Home icon in the upper left corner, is http://tharsis-gate.org/twiki
%SCRIPTURL% The script URL of Tharsis, is http://www.tharsis-gate.org/twiki/bin
%SCRIPTURLPATH% The path of the script URL of Tharsis, is /twiki/bin
%SCRIPTSUFFIX% The script suffix, ex: .pl, .cgi is
%PUBURL% The public URL of TWiki, is http://www.tharsis-gate.org/twiki/pub
%PUBURLPATH% The path of the public URL of Tharsis, is /twiki/pub
%ATTACHURL% The attachment URL of the current topic, is http://www.tharsis-gate.org/twiki/pub/TWiki/TWikiVariables
Example: If you attach a file you can refer to it as %ATTACHURL%/image.gif
%ATTACHURLPATH% The path of the attachment URL of the current topic, is /twiki/pub/TWiki/TWikiVariables
%URLPARAM{"name"}% Returns the value of a URL parameter. Ex: %URLPARAM{"skin"}% returns print for a .../view/TWiki/TWikiVariables?skin=print URL. Is
%WIKITOOLNAME% Name of wiki tool, is Tharsis
%WIKIVERSION% Wiki tool version is 01 Dec 2001
%USERNAME% Your login username is guest
%WIKINAME% Your Wiki username. Same as %USERNAME% if not defined in the TWikiUsers topic. Is guest
%WIKIUSERNAME% Your %WIKINAME% including the Main web name. Usefull for signatures. Is Main.guest
%MAINWEB% The Main web containing TWikiUsers, OfficeLocations? and TWikiGroups. Is Main
%TWIKIWEB% The web containing all documentation and configuration of Tharsis is TWiki
%WEB% The current web is TWiki
%BASEWEB% The web name where the includes started, e.g. the web of the first topic of nested includes. Same as %WEB% in case there is no include.
%INCLUDINGWEB% The web name of the topic that includes the current topic. Same as %WEB% in case there is no include.
%HOMETOPIC% The home topic in each web. Is WebHome
%NOTIFYTOPIC% The notify topic in each web. Is WebNotify
%WIKIUSERSTOPIC% The index topic of all registered users. Is TWikiUsers
%WIKIPREFSTOPIC% The web preferences topic. Is TWikiPreferences
%WEBPREFSTOPIC% The web preferences topic. Is WebPreferences
%STATISTICSTOPIC% The web statistics topic. Is WebStatistics
%TOPIC% The current topic name, is TWikiVariables
%BASETOPIC% The name of the topic where the includes started, e.g. the first topic of nested includes. Same as %TOPIC% in case there is no include.
%INCLUDINGTOPIC% The name of the topic that includes the current topic. Same as %TOPIC% in case there is no include.
%SPACEDTOPIC% The current topic name with added spaces, for regular expression search of Ref-By, is TWiki%20*Variables
%TOPICLIST{"format"}% Topic index of a web. The "format" defines the format of one topic item. It may include variables: The $name variable gets expanded to the topic name; the $web variable gets expanded to the name of the web. Parameters are format, separator and web:
Parameter: Description: Default:
"format" Format of one line, may include $name and $web variables "$name"
format="format" (Alternative to above) "$name"
separator=", " line separator "\n" (new line)
web="Name" Name of web Current web
Examples:
%TOPICLIST{"   * $web.$name"}% creates a bullet list of all topics.
%TOPICLIST{separator=", "}% creates a comma separated list of all topics.
%TOPICLIST{" <option>$name</option>"}% creates an option list (for drop down menus).
%WEBLIST{"format"}% Web index, e.g. list of all webs. Hidden webs are excluded, e.g. webs with a NOSEARCHALL=on preference variable. The "format" defines the format of one web item. The $name variable gets expanded to the name of the web, $qname gets expanded to double quoted name, $marker to marker where web matches selection. Parameters are format, separator and web:
Parameter: Description: Default:
"format" Format of one line, may include $name variable "$name"
format="format" (Alternative to above) "$name"
separator=", " line separator "\n" (new line)
webs="public" comma sep list of Web, public expands to all non-hidden "public"
marker="selected" Text for $marker where item matches selection, otherwise equals "" "selected"
selection="%WEB%" Current value to be selected in list section="%WEB%"
Examples:
%WEBLIST{"   * [[$name.WebHome]]"}% creates a bullet list of all webs.
%WEBLIST{"" webs="Trash,public" selection="TWiki" separator=" "}% Dropdown of all public Webs + Trash Web, current Web highlighted.
%GMTIME% GM time, is Thu Oct 17 01:20:09 2019
%GMTIME{"format"}% Formatted GM time based on time variables.
Variable: Unit: Example
$seconds seconds 59
$minutes minutes 59
$hours hours 23
$day day of month 31
$month month in ISO format Dec
$mo 2 digit month 12
$year 4 digit year 1999
$ye 2 digit year 99
Variables can be shortened to 3 characters. Example:
%GMTIME{"$day $month, $year - $hour:$min:$sec"}% is
17 Oct, 2019 - 01:20:09
%SERVERTIME% Server time, is Thu Oct 17 12:20:09 2019
%SERVERTIME{"format"}% Formatted server time.
Example: %SERVERTIME{"$hou:$min"}% is 12:20
%HTTP_HOST% HTTP_HOST environment variable, is www.tharsis-gate.org
%REMOTE_ADDR% REMOTE_ADDR environment variable, is 35.175.191.168
%REMOTE_PORT% REMOTE_PORT environment variable, is 59676
%REMOTE_USER% REMOTE_USER environment variable, is
%INCLUDE{"page" ...}% Server side include to IncludeTopicsAndWebPages. Parameters are page name, and an optional pattern="(reg-exp)". The page name is:
"SomeTopic" The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}%
"Web.Topic" A topic in another web, i.e. %INCLUDE{"TWiki.TWikiWebsTable"}%
"http://..." A full qualified URL, i.e. %INCLUDE{"http://twiki.org/"}%
%STARTINCLUDE% If present in included topic, start to include text from this location up to the end, or up to the location of the %STOPINCLUDE% variable. A normal view of the topic shows everyting exept the %STARTINCLUDE% variable itself.
%STOPINCLUDE% If present in included topic, stop to include text at this location and ignore the remaining text. A normal view of the topic shows everyting exept the %STOPINCLUDE% variable itself.
%TOC% Table of Contents of current topic.
%TOC{"SomeTopic" ...}% Table of Contents. Shows a TOC that is generated automatically based on headings of a topic. Headings in WikiSyntax ("---++ text") and HTML ("<h2>text<h2>") are taken into account. (But not "<H2>text</H2>", which can be used to exclude a heading from the TOC.) Parameters are topic name, web and depth:
Parameter: Description: Default:
"TopicName" topic name Current topic
web="Name" Name of web Current web
depth="2" Limit depth of headings shown in TOC 6
Examples: %TOC{depth="2"}%, %TOC{"TWikiDocumentation" web="TWiki"}%
%SEARCH{"text" ...}% Inline search, shows a search result embedded in a topic. Parameters are the search term, web, scope, order and many more: [1]
Parameter: Description: Default:
"text" Search term. (Is a regular expression or literal, depending on the regex parameter) required
search="text" (Alternative to above) N/A
web="Name"
web="Main Know"
web="all"
Wiki web to search: A web, a list of webs separated by whitespace, or all webs. [2] Current web
scope="topic"
scope="text"
Search topic name (title) or in the text (body) of the topic Topic text (body)
order="topic"
order="modified"
order="editby"
Sort the results of search by the topic names, last modified time, or last editor Sort by topic name
limit="all"
limit="16"
Limit the number of results returned All results
regex="on" RegularExpression search Literal search
reverse="on" Reverse the direction of the search Ascending search
casesensitive="on" Case sensitive search Ignore case
nosummary="on" Show topic title only Show topic summary
bookview="on" BookView search, e.g. show complete topic text Show topic summary
nosearch="on" Suppress search string Show search string
noheader="on" Suppress search header
Topics: Changed: By:
Show search header
nototal="on" Do not show number of topics found Show number
format="..." Flexible custom result formatting: see FormattedSearch for usage Results in table
Example: %SEARCH{"wiki" web="Main" scope="topic"}%
%METASEARCH{...}% Special search of meta data
Parameter: Description: Default:
type="topicmoved" What sort of search is required?
"topicmoved" if search for a topic that may have been moved
"parent" if searcing for topics that have a specific parent i.e. its children
required
web="%WEB%" Wiki web to search: A web, a list of webs separated by whitespace, or all webs. required
topic="%TOPIC%" The topic the search relates to required
title="Title" Text the is pre-pended to any search results required
Example: %METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%, you may want to use this in WebTopicViewTemplate and WebTopicNonWikiTemplate
%METASEARCH{type="parent" web="%WEB%" topic="%TOPIC%" title="Children: "}%
%VAR{"NAME" web="Web"}% Get a preference value from a web other then the current one. Example: To get %WEBBGCOLOR% of the Main web write %VAR{"WEBBGCOLOR" web="Main"}%, is #FFFFC0

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

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

Preferences Variables

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

Variable: Level: What:
%WIKIWEBMASTER% SL Webmaster email address (sender of email notifications) , is fantom@tharsis.dyndns.org
%WIKIWEBLIST% SL List of Tharsis webs (in upper right corner of topics)
%WEBTOPICLIST% WL Common links of web (second line of topics)
%WEBCOPYRIGHT% SL , WL Copyright notice (bottom right corner of topics)
%WEBBGCOLOR% WL Background color of web
%NOSEARCHALL% WL Exclude web from a web="all" search (set variable to on for hidden webs)
%NEWTOPICBGCOLOR% SL , UL Background color of non existing topic. ( UL needs authentication for topic views )
%NEWTOPICFONTCOLOR% SL , UL Font color of non existing topic. ( UL needs authentication for topic views )
%EDITBOXWIDTH% SL , UL Horizontal size of edit box, is 70
%EDITBOXHEIGHT% SL , UL Vertical size of edit box, is 15
%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: checked="checked"
%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:
%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:
%HTTP_EQUIV_ON_VIEW% SL http-equiv meta tags for view, rdiff, attach, search* scripts.
%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.
%DENYWEBCHANGE% WL List of users and groups who are not allowed to change topics in the Tharsis web. (More in TWikiAccessControl)
%ALLOWWEBCHANGE% WL List of users and groups who are allowed to change topics in the Tharsis web. (More in TWikiAccessControl)
%DENYTOPICCHANGE% (any topic) List of users and groups who are not allowed to change the current topic. (More in TWikiAccessControl)
%ALLOWTOPICCHANGE% (any topic) List of users and groups who are allowed to change the current topic. (More in TWikiAccessControl)
%DENYWEBRENAME% WL List of users and groups who are not allowed to rename topics in the Tharsis web. (More in TWikiAccessControl)
%ALLOWWEBRENAME% WL List of users and groups who are allowed to rename topics in the Tharsis web. (More in TWikiAccessControl)
%DENYTOPICRENAME% (any topic) List of users and groups who are not allowed to rename the current topic. (More in TWikiAccessControl)
%ALLOWTOPICRENAME% (any topic) List of users and groups who are allowed to rename the current topic. (More in TWikiAccessControl)
%FINALPREFERENCES% SL , WL List of preferences that are not allowed to be overridden by next level preferences

Setting Preferences

  • The syntax for Preferences variables is the same anywhere in TWiki. In Edit mode, from the start of a new line:
    [6 spaces] * [space] Set [space] VARIABLENAME [space] = [value]
    Example:
    • Set VARIABLENAME = value

Creating Custom Variables

  • You can add your own preference variables for an entire site, a single web, or a single topic, using the standard syntax. Whatever you include in your variable will be expanded on display, and treated exactly as if it had been written out. So you can place formatted text, page links, image paths.

Example: Create a custom logo variable
  • To place a logo anywhere in a web by typing %MYLOGO%, simply define the variable on the web's WebPreferences page. You also have to upload logo.gif - this can be done by attaching a file to LogoTopic (any topic name you choose):
    • Set MYLOGO = %PUBURL%/%MAINWEB%/LogoTopic/logo.gif

-- PeterThoeny - 13 Sep 2001
-- MikeMannix - 30 Nov 2001

Changed:
<
<

>
>

Changed:
<
<

Note: This feature has been replaced by: TWikiForms

>
>

Note: This feature has been replaced by: TWikiForms

Changed:
<
<

TWiki System Requirements

Server and client system requirements for TWiki 01-Sep-2001

Overview

Maintaining minimum client and server requirements is necessary to keep TWiki deployment as broad as possible.

Server Requirements

TWiki is written in Perl 5, uses a number of shell commands, and requires RCS (Revision Control System), a GNU Free Software package. TWiki is developed in a basic Linux/Apache environment. It also works with Microsoft Windows, and should have no problem on any other platform that meets the requirements:

Required Server Environment
Resource Unix Windows
Perl 5.005_03 or higher
Non standard Perl modules Net::SMTP (or sendmail) Net::SMTP, MIME::Base64, Digest::SHA1
RCS 5.7 or higher
Other external programs ls, fgrep, egrep
Web server Apache; others (with support for CGI, authentication, extended path) *

Current documentation covers Linux only. A TWikiOnWindows installation guide is next.

Client Requirements

The TWiki standard installation has extremely low browser requirements:

  • HTML 3.2 compliant
  • generates XHTML 1.0 pages that are compatible with HTML 3.2
  • minimal use of JavaScript in the user interface (degrades gracefully)
  • no cookies
  • no CSS

You can easily add capabilities, through customizing the templates, for one, while tailoring the browser requirements to your situation.

Known Issues

  • The new TWikiPlugins feature currently does not have compatibility guidelines for developers. Plugins can require just about anything: browser-specific functions, stylesheets (CSS), DHTML, Java applets, cookies.

-- MikeMannix - 15 Sep 2001

>
>

Changed:
<
<

>
>

Changed:
<
<

>
>

Changed:
<
<

(8) Upgrading Earlier Versions to TWiki 01 Mai 2000

>
>

(8) Upgrading Earlier Versions of TWiki

Changed:
<
<

To upgrade an earlier TWiki version like 01 Sep 1999 to version 01 May 2000 you should do the following things:

  • Back up your system.
  • Update the templates in the /templates directory (and its subdirs):
    • Take the templates of the latest distribution as the base and merge your changes back into it.
  • Update the Perl scripts in the /bin directory:
    • Take the scripts of the latest distribution as the base and merge your changes back into it. Do so also for wikicfg.pm because it has important changes as well.
  • Update topics:
  • Add the PoweredByTWikiLogo to your Tharsis home page.

-- PeterThoeny - 28 Apr 2000

>
>


 <<O>>  Difference Topic TWikiDocumentation (r1.13 - 23 May 2000 - PeterThoeny)
Changed:
<
<

  • (2) Wiki Variables
  • (3) Notification of Changes by Email
  • (4) TWiki Category Table
  • (5) Implementation Notes
  • (6) Installation Notes
  • (7) Upgrading Earlier Versions to TWiki 01 Mai 2000
>
>

  • (2) Wiki Templates
  • (3) Wiki Variables
  • (4) Notification of Changes by Email
  • (5) TWiki Category Table
  • (6) Implementation Notes
  • (7) Installation Notes
  • (8) Upgrading Earlier Versions to TWiki 01 Mai 2000
Added:
>
>


(2) Wiki Templates

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 mark-up for template-specific content. Templates are used to define page layout, and also to supplydefault content for new pages.

Major changes from the previous template system

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

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

Functional Specifications

  • Special template directives (or preprocessor commands) are embedded in normal templates.
  • Use of template directives is optional, templates work without them.
  • All template preprocessing is done in &TWiki::Store::readTemplate() so that the caller simply gets an expanded template file (the same as before).
  • Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
  • Directives:
    • %TMPL:INCLUDE{"file"}%: Includes a template file. The template directory of the current web is searched first, then the templates root (twiki/templates).
    • %TMPL:DEF{"var"}%: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
    • %TMPL:END%: Ends variable definition.
    • %TMPL:P{"var"}%: Prints a previously defined variable.
  • Variables are live in a global name space, there is no parameter passing.
  • Two-pass processing, so that you can use a variable before declaring it or after.
  • Templates and TWikiSkins work transparently and interchangeably. For example, you can create a skin that overloads just the twiki.tmpl, like twiki.print.tmpl, that redefines the header and footer.
  • NOTE: The template directives work only for templates, they do not get processed in topic text.

TWiki Master Template

All common parts are defined in a master template, twiki.tmpl, that all other templates use.

Template variable: Defines:
%TMPL:DEF{"sep"}% "|" separator
%TMPL:DEF{"htmldoctype"}% Start of all HTML pages
%TMPL:DEF{"standardheader"}% Standard header (ex: view, index, seach)
%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

Types of Template

There are two types of templates:

  • HTML Page Templates: Defines layout of Tharsis pages
  • Template Topics: Defines default text when you create a new topic

HTML Page Templates

Tharsis uses HTML template files for all actions like topic view, edit, preview and so on. This allows you to change the look and feel of all pages by editing just some template files.

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

  1. twiki/templates/$webName/$scriptName.tmpl
  2. twiki/templates/$scriptName.tmpl

Note: $webName is the name of the web (ex: Main), and $scriptName is the script (ex: view).

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

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

Template Topics

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

Topic Name: What it is:
WebTopicViewTemplate Help text shown when you view a non existing topic.
WebTopicNonWikiTemplate Help text shown when you view a non existing topic that has not a 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. The following search order applies when you create a new topic:

  1. The topic name specified by the templatetopic CGI parameter.
  2. WebTopicEditTemplate in the current web.
  3. WebTopicEditTemplate in the TWiki web.

Template Topics in Action

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

  • New example topic: (date format is YYYYxMMxDD)

Above form asks for a topic name. A hidden input tag of name "templatetopic" specifies the ExampleTopicTemplate as the template topic. Here is the HTML source of the form:

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

The "onlywikiname" parameter enforces WikiWords for topic names.

Note: Use can use the %WIKIUSERNAME% and %DATE% variables in your topic templates as the signature; those variables are expanded when a new topic is created. The standard topic signature is:
-- %WIKIUSERNAME% - %DATE%

Templates by Example

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

Base template oopsbase.tmpl

The first line declares the 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/Test/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify

testscreen.gif

Known Issues

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

-- PeterThoeny - 23 Jul 2001
-- MikeMannix - 14 Sep 2001

Changed:
<
<

(2) Wiki Variables

>
>

(3) Wiki Variables

Changed:
<
<

(3) Notification of Changes by Email

>
>

(4) Notification of Changes by Email

Changed:
<
<

(4) TWiki Category Table

>
>

(5) TWiki Category Table

Changed:
<
<

(5) Implementation Notes

>
>

(6) Implementation Notes

Changed:
<
<

(6) Installation Notes

>
>

(7) Installation Notes

Changed:
<
<

(7) Upgrading Earlier Versions to TWiki 01 Mai 2000

>
>

(8) Upgrading Earlier Versions to TWiki 01 Mai 2000


 <<O>>  Difference Topic TWikiDocumentation (r1.12 - 22 Apr 2000 - PeterThoeny)
Changed:
<
<

  • (1) Login Username vs. Wiki Username
>
>

  • (1) Wiki Username vs. Login Username
Added:
>
>

  • (7) Upgrading Earlier Versions to TWiki 01 Mai 2000
Changed:
<
<

Related Topics: TWikiHistory, TWikiPlannedFeatures, TWikiEnhancementRequests.

>
>

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

Changed:
<
<

(1) Login Username vs. Wiki Username

>
>

(1) Wiki Username vs. Login Username

Changed:
<
<

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

  • Login username: When you login to the Intranet you use your login username, e.g. thoeny. TWiki uses this name internally to log who changed topics.
  • Wiki username: Is your name in WikiNotation, e.g. PeterThoeny. When you create your own home page topic, you should use your WikiName for the topic name. Like that, your name will be linked automatically where ever it is used. Please create your home page in TWiki.Main, not any other TWiki web.

Note: When you write a WikiName of a user (your own or somebody else's) be sure to specify the Main web in front of the Wiki user name, e.g. write it as Main.wikiUsername. This assures that the name will be linked automatically to the TWiki.Main web, even if the text is written in a different Wiki web.

TWiki can map the Intranet username to the Wiki username automatically, provided that the Login username and Wiki username pair has been entered in the TWikiUsers topic.

>
>

TWiki Username vs. Login Username

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

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

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

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

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

-- PeterThoeny - 16 May 2001

Changed:
<
<

Each TWiki web does an automatic email notification of recent changes. Users can subscribe / unsubscribe themselves in WebNotify of each TWiki web. The Perl script mailnotify is called by a deamon once every 60 minutes. For each Twiki web mailnotify is sending an automated email to subscribed users in case some topics changed within these 60 minutes.

>
>

Deleted:
<
<

Implementation note: Edit the cron table so that mailnotify is called every 60 minutes. Please consult man crontab of how to modify the table that schedules program execution at certain intervals. Example:

% crontab -e
15,45 * * * * (cd ~twiki/public_html/bin; ./mailnotify)
The above line will call mailnotify at 15 minutes and 45 minutes passed every hour.
Changed:
<
<

It is possible to add a category table to a TWiki web. This permits storing and searching for more structured information. Editing a topic shows a HTML form with the usual text area and a table with selectors, checkboxes, radio buttons and text fields. The category table is shown at the end of a topic. The format of the category table can be defined per TWiki web.

If you want to use a Category Table in a TWiki web you need to have the following three files in the twiki/templates/{Yourweb} directory:

  • twikicatitems.tmpl : Defines the items in the table
  • twikicatedit.tmpl : Defines the look of the table when editing a topic
  • twikicatview.tmpl : Defines the look of the table when viewing a topic

Format of category definition template twikicatitems.tmpl

Valid lines:

select|{name}|{selSize}|{val1}|{val2}|{val3}...
checkbox|{name}|{checkFlag}|{itemsPerLine}|{val1}|{val2}|{val3}...
radio|{name}|{itemsPerLine}|{val1}|{val2}|{val3}...
text|{name}|{charSize}
# comments start with a # character

Explanation:

  {name}             name of tag
  {selSize}          vertical size of SELECT tag
  {val1}|{val2}...   values
  {checkFlag}        set to true for [Set] [Clear] buttons, else set to false
  {itemsPerLine}     input items per line before wrap around, 0 if no wrap around
  {charSize}         number of characters for text fields

Remark: Line radio|UseCategory|0|Yes|No has a special meaning. If present, it is possible to choose in "edit" if the category table is included in the topic or not

Example file:

radio|UseCategory|0|Yes|No, delete this category table
select|TopicClassification|1|Select one...|NoDisclosure|PublicSupported|PublicFAQ
checkbox|OperatingSystem|true|5|OsSolaris|OsSunOS|OsHPUX|OsWin
text|OsVersion|16

Format of twikicatedit.tmpl and twikicatview.tmpl

Use the example below and customize if needed. twikicatedit.tmpl and twikicatview.tmpl can be identical, but they do not have to be.

Attention: <!--TWikiCat--> is needed at the beginning and end as markers. Do not delete them!

Example:

<!--TWikiCat--> <h4> TWikiCategory </h4>
<table border="2" cellspacing="1" cellpadding="1">
%REPEAT%<tr>
<td valign="top" align="right"> %CATNAME%:  <br>%CATMODIFIER%</td><td>  %CATVALUE% </td>
</tr>%REPEAT%
</table><!--TWikiCat-->

Above template files will result in the following category table when viewing a topic:

TWikiCategory

TopicClassification:
PublicFAQ
OperatingSystem:
OsSolaris
OsVersion:
2.5 

Above template files will result in the following table when editing a topic:

TWikiCategory

UseCategory :
Yes    No, delete this category table   
TopicClassification :
OperatingSystem :
   
OsSolaris    OsSunOS    OsHPUX    OsWin   
OsVersion :

Note: It is possible to force the values of a category table when creating a new topic. This is useful to create new topics using a form for the topic name. The default values of the category table can be specified as hidden fields if needed, i.e. <input type="hidden" name="someCategory" value="someValue">

Example (edit this page to see the source) :

  • New PublicFAQ? topic:
>
>

Note: This feature has been replaced by: TWikiForms

Changed:
<
<

Platform

TWiki is written in PERL 5, but it uses also many shell command. The current implementation runs only on a Unix machine. RCS for revision control must be installed on the system.

Directories

Directory: Used for:
twiki/bin TWiki PERL scripts
twiki/pub Public files (FileAttachments, images)
twiki/data source text
twiki/templates HTML templates, used by TWiki scripts

Files in twiki/bin

File: Used for:
.htaccess.txt Authentication. Rename to .htaccess and customize if used
attach Script that shows the attach file page (FileAttachment)
changes Script that shows recent changes
delete (not used yet)
edit Script to edit a topic
geturl Script to fetch URL data
mailnotify Script called by cron job to notify users of changes
oops Script that shows a OK or oops dialog
preview Script to preview topic after edit
rdiff Script to see differences of topics
register Script to register new users
save Script that saves a topic, called by preview
search Script that displays search results
statistics Script to create statistics topic
testenv Script to test CGI environment variables
upload Script that does file upload (FileAttachment)
view Script to view a topic ( the script )
viewfile Script to view an file attachment
wiki.pm main TWiki library
wikicfg.pm for initialization and configuration, used by wiki.pm
wikisearch.pm search engine, used by wiki.pm
>
>

TWiki System Requirements

Server and client system requirements for TWiki 01-Sep-2001

Overview

Maintaining minimum client and server requirements is necessary to keep TWiki deployment as broad as possible.

Server Requirements

TWiki is written in Perl 5, uses a number of shell commands, and requires RCS (Revision Control System), a GNU Free Software package. TWiki is developed in a basic Linux/Apache environment. It also works with Microsoft Windows, and should have no problem on any other platform that meets the requirements:

Required Server Environment
Resource Unix Windows
Perl 5.005_03 or higher
Non standard Perl modules Net::SMTP (or sendmail) Net::SMTP, MIME::Base64, Digest::SHA1
RCS 5.7 or higher
Other external programs ls, fgrep, egrep
Web server Apache; others (with support for CGI, authentication, extended path) *

Current documentation covers Linux only. A TWikiOnWindows installation guide is next.

Client Requirements

The TWiki standard installation has extremely low browser requirements:

  • HTML 3.2 compliant
  • generates XHTML 1.0 pages that are compatible with HTML 3.2
  • minimal use of JavaScript in the user interface (degrades gracefully)
  • no cookies
  • no CSS

You can easily add capabilities, through customizing the templates, for one, while tailoring the browser requirements to your situation.

Known Issues

  • The new TWikiPlugins feature currently does not have compatibility guidelines for developers. Plugins can require just about anything: browser-specific functions, stylesheets (CSS), DHTML, Java applets, cookies.

-- MikeMannix - 15 Sep 2001

Changed:
<
<

These installation steps use Apache web server on Linux as an example. TWiki should run on other web servers and Unix systems as well.

>
>

Deleted:
<
<

Note: These installation notes assume user nobody for all files manupulated by the cgi scripts (executed by the web server), and user twiki for all other files. You need to replace user nobody with an other user in case the web server executes the script with a different user ( default for Debian is www-data ). Also, you can substitute user twiki with your own user name.

Changed:
<
<

  • Request the TWiki distribution (in Unix ZIP format) from http://TWiki.SourceForge.net/download.html .
  • Create directory /home/httpd/twiki and unzip the TWiki distribution to this directory.
  • The twiki/bin directory of TWiki must be set as a cgi-bin directory. Add /home/httpd/twiki/bin to /etc/httpd/conf/access.conf with only ExecCGI option.
  • The twiki/pub directory of TWiki must be set so that it is visible as a URL. Add /home/httpd/twiki/pub to /etc/httpd/conf/access.conf with normal access options (copy from /home/httpd/html).
  • Now add Alias for /twiki/pub and ScriptAlias for /twiki/bin to /etc/httpd/conf/srm-conf .
  • Restart Apache by /etc/rc.d/rc5.d/S85httpd restart .
  • Test if the twiki/bin directory is cgi-enabled:
    • Enter the URL of that directory into your browser ( http://your.domain.com/twiki/bin ). It is not set correctly as cgi-bin in case you get something like "Index of /twiki/bin" . It is OK if you get a message like "Forbidden. You don't have permission to access /twiki/bin/ on this server."
    • Execute the testenv script from your browser ( http://your.domain.com/twiki/bin/testenv ). It should show a table of all CGI environment variables.
  • Make sure PERL and the PERL CGI library is installed on your system. Default location of PERL executable is /usr/bin/perl . In case PERL is installed in a different location, the first line of all perl scripts in the twiki/bin directory need to be changed (alternatively you can create a symbolic link from /usr/bin/perl ).
  • To be able to edit the perl scripts and .tmpl files it is necessary to chown and chgrp -R twiki so all the files have the owner you want.
  • The scripts execute as nobody . Set the file permission of all Perl scripts in the twiki/bin directory as executable to -rw-r-xr-x .
  • Set the file permission of all files below twiki/data to 666 ( -rw-rw-rw- ).
  • Set the file permission of the twiki/data directory and all its subdirectories to 777 ( drwxrwxrwx ).
  • Set the file permission of the twiki/pub directory to 777 ( drwxrwxrwx ).
  • Edit the file twiki/bin/wikicfg.pm and set the variables at the beginning of the file to your needs.
  • Make sure RCS is installed. In case RCS is not in the path environment variable, add it to path . Alternatively, add the full path name to the rcs, ci, co, rlog, rcsdiff commands in the variables of twiki/bin/wikicfg.pm .
  • Point your browser at http://your.domain.com/twiki/bin/view and start wiki-ing away!
  • Note in case cgi user is not nobody : The *,v RCS repository files delivered with the installation package are locked by user nobody . In case the user is different (e.g. www-data ), it is not possible to check in files, this has the effect that the topic version number does not increase when saving a topic. In this case you need to unlock all repository files and lock them as user www-data (check the rcs man pages), or simply delete all the repository files.
  • Security issue: Directories twiki/data , twiki/templates and all its subdirectories should be set so that they are not visible as a URL. (Alternatively, move the directries to a place where they are not visible, and change the variables in twiki/bin/wikicfg.pm accordingly)
  • Enable email notification of topic changes, (3) has more.

  • Optional: You can add new rendering rules or new %variables%. To insure an easy upgrade of TWiki it is recommended to do this customization in twiki/bin/wikicfg.pm , not twiki/bin/wiki.pm .

  • Optional: If you are on a public server and you would like to authenticate users you need to rename file .htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. For details consult the HTTP server documentation (for Apache server: [1], [2], [3]). Note: In case .htaccess does not have any effect you need to enable it: Add "AllowOverride All" to the Directory section of access.conf for your twiki/bin directory.

  • Optional: You can automatically generate usage statistics for all webs. To enable this:
    • Make sure variable $doLogTopicView, $doLogTopicSave and $doLogTopicUpload in wikicfg.pm are set. This will generate log entries in file twiki/data/log<date>.txt .
    • Topic WebStatistics must be present in all webs where you want to have statistics. You can use the topic in the Main web as a template.
    • Call the twiki/bin/statistics script from a cron job, once a day is recommended. This will update the WebStatistics topics in all webs.
    • Attention: The script must run as the same user as the CGI scripts are running, which is user nobody on most systems. Example crontab entry:
      0 0 * * * (cd /path/to/TWiki/bin; ./statistics >/dev/null 2>&1)
    • There is a workaround in case you can't run the script as user nobody : Run the utility twiki/bin/geturl in your cron job and specify the URL of the twiki/bin/statistics script as a parameter. Example:
      0 0 * * * (cd /path/to/TWiki/bin; ./geturl mydomain.com /urlpath/to/TWiki/bin/statistics >/dev/null 2>&1)
    • The twiki/bin/statistics script can also be executed as a CGI script, just enter the URL in your browser. Examples:
      • Update current month for all webs:
        http://mydomain.com/twiki/bin/statistics
      • Update current month for Main web only:
        http://mydomain.com/twiki/bin/statistics/Main
      • Update January 2000 for Main web:
        http://mydomain.com/twiki/bin/statistics/Main?logdate=200001

  • To create a new web:
    • Use a name for the web consisting of characters A..Z , a..z but not in WikiNotation.
    • Create a new template directory under twiki/templates .
    • Create a new data directory under twiki/data and check the file permission of the directory.
    • Copy the files WebHome.txt , WebPreferences.txt , WebNotify.txt , WebSearch.txt and WebStatistics.txt from the twiki/data/Main directory to the new data directory, preserving the original files' owner, group and permissions ( on Unix use cp -p ). The data files must be writable by the owner the CGI scripts are running on ( usually nobody ). Hint: You can set permissions of .txt and .txt,v files to -rw-rw-rw- and then edit the topic using your browser, RCS will restore the file permission correctly when saving the topic.
    • Add the new web to the web list (on top of each topic) by editing the site-level preferences TWikiPreferences?:
      • Add the new web to the WIKIWEBLIST variable.
    • Add the new web to the web table (at the bottom of each WebHome topic) by editing the TWikiWebsTable? topic.
    • Change the web preferences by editing the WebPreferences topic of the new web:
      • Set the WEBBGCOLOR variable to a color of your taste. The number represents the unique color for the web (consult an HTML book for colors.)
      • Customize the WEBTOPICLIST variable to contain the web specific links you prefer.
      • Optional: Set the WEBCOPYRIGHT variable to have a web-specific copyright text (at the bottom of each topic).
    • If needed, create customized templates in the new templates directory. (Non existing templates are inherited from twiki/templates )
    • If you want to use a category table, copy the three files twikicatitems.tmpl , twikicatedit.tmpl and twikicatview.tmpl from the twiki/templates/Know directory to the new templates directory, and customize it. The TWiki Category Table section has more.
    • In case you want usage statistics for this web: Copy file WebStatistics.txt from the twiki/data/Main directory to the new data directory. Edit topic WebStatistics in the new web and delete old usage entries.

Here are contents of directories with file permissions. Please note that this is for debugging reasons only and does not exactly reflect the distribution:

directory twiki/bin :

drwxr-xr-x   2 twiki   twiki       1024 Feb 18 18:31 .
drwxr-xr-x   8 twiki   twiki       1024 Feb 26 04:20 ..
-rw-rw-r--   1 twiki   twiki        770 Feb 10 12:10 .htaccess
-rw-r-xr-x   1 twiki   twiki       3968 Feb 18 00:26 attach
-rwxr-xr-x   1 twiki   twiki       3033 Feb 17 23:57 changes
-rw-r-xr-x   1 twiki   twiki       1377 Feb  8 18:18 delete
-rw-r-xr-x   1 twiki   twiki       8785 Feb 17 23:58 edit
-rwxr--r--   1 twiki   twiki       1811 Feb  4 14:31 geturl
-rwxr-xr-x   1 twiki   twiki       5047 Feb  8 20:33 mailnotify
-rw-r-xr-x   1 twiki   twiki       1825 Feb  8 18:29 oops
-rw-r-xr-x   1 twiki   twiki       6932 Feb 11 02:06 preview
-rw-r-xr-x   1 twiki   twiki       7804 Feb 17 23:59 rdiff
-rw-r-xr-x   1 twiki   twiki       7010 Feb 18 00:03 register
-rw-r-xr-x   1 twiki   twiki       2501 Jan 25 19:39 save
-rwxr-xr-x   1 twiki   twiki       1778 Feb 18 00:04 search
-rw-r-xr-x   1 twiki   twiki       9810 Feb  8 18:43 statistics
-rwxr-xr-x   1 twiki   twiki        509 Feb  7 18:55 testenv
-rw-r-xr-x   1 twiki   twiki       6856 Feb 18 00:11 upload
-rw-r-xr-x   1 twiki   twiki       4922 Feb 17 23:54 view
-rw-r-xr-x   1 twiki   twiki       1606 May 21  1999 viewfile
-rw-r-xr-x   1 twiki   twiki      27794 Feb 26 06:03 wiki.pm
-rw-r-xr-x   1 twiki   twiki      10143 Feb 27 04:03 wikicfg.pm
-rw-r-xr-x   1 twiki   twiki       5440 Feb  7 04:36 wikisearch.pm

directory twiki/templates/ :

drwxr-xr-x   7 twiki   twiki       1024 Jan 16 19:39 .
drwxr-xr-x   8 twiki   twiki       1024 Feb 26 04:20 ..
drwxr-xr-x   2 twiki   twiki       1024 Jun  8  1999 Know
drwxr-xr-x   2 twiki   twiki       1024 Dec  9  1998 Main
-rw-r--r--   1 twiki   twiki       2286 Feb 24 21:50 attach.tmpl
-rw-r--r--   1 twiki   twiki       1272 Feb  8 16:07 attachtable.tmpl
-rw-r--r--   1 twiki   twiki       1884 Feb 24 21:54 changes.tmpl
-rw-r--r--   1 twiki   twiki       2242 Feb 24 21:33 edit.tmpl
-rw-r--r--   1 twiki   twiki        965 Feb  8 16:07 mailnotify.tmpl
-rw-r--r--   1 twiki   twiki         30 Jan 14  1999 notedited.tmpl
-rw-r--r--   1 twiki   twiki        934 Feb  8 16:07 notext.tmpl
-rw-r--r--   1 twiki   twiki        899 Feb  8 16:07 notwiki.tmpl
-rw-r--r--   1 twiki   twiki        299 Feb 24 21:58 noweb.tmpl
-rw-r--r--   1 twiki   twiki        957 Feb 24 22:17 oops.tmpl
-rw-r--r--   1 twiki   twiki        871 Feb 24 22:17 oopsdel.tmpl
-rw-r--r--   1 twiki   twiki       1330 Feb 24 22:17 oopslocked.tmpl
-rw-r--r--   1 twiki   twiki       1024 Feb 24 22:17 oopsregexist.tmpl
-rw-r--r--   1 twiki   twiki        912 Feb 24 22:17 oopsregpasswd.tmpl
-rw-r--r--   1 twiki   twiki        923 Feb 24 22:17 oopsregrequ.tmpl
-rw-r--r--   1 twiki   twiki       1125 Feb 24 22:17 oopsregthanks.tmpl
-rw-r--r--   1 twiki   twiki        942 Feb 24 22:17 oopsregwiki.tmpl
-rw-r--r--   1 twiki   twiki       1564 Feb 24 22:17 oopsrev.tmpl
-rw-r--r--   1 twiki   twiki        906 Feb 24 22:17 oopsupload.tmpl
-rw-r--r--   1 twiki   twiki       1535 Feb 24 22:02 preview.tmpl
-rw-r--r--   1 twiki   twiki       1661 Feb 24 22:04 rdiff.tmpl
-rw-r--r--   1 twiki   twiki        263 Aug  3  1999 register.tmpl
-rw-r--r--   1 twiki   twiki        936 Feb  8 16:08 registernotify.tmpl
-rw-r--r--   1 twiki   twiki       1779 Feb 24 22:06 search.tmpl
-rw-r--r--   1 twiki   twiki       1533 Feb 24 21:43 view.tmpl

directory twiki/templates/Main :

drwxr-xr-x   2 twiki   twiki       1024 Dec  9  1998 .
drwxr-xr-x   7 twiki   twiki       1024 Jan 16 19:39 ..
-rw-r--r--   1 twiki   twiki       2732 Feb 24 21:34 edit.tmpl

directory twiki/templates/Know (has a TWiki Category Table) :

drwxr-xr-x   2 twiki   twiki       1024 Jun  8  1999 .
drwxr-xr-x   7 twiki   twiki       1024 Jan 16 19:39 ..
-rw-rw-r--   1 twiki   twiki        446 Jun  8  1999 notedited.tmpl
-rw-rw-r--   1 twiki   twiki        206 Jun  8  1999 twikicatedit.tmpl
-rw-rw-r--   1 twiki   twiki       1060 Jul 16  1999 twikicatitems.tmpl
-rw-rw-r--   1 twiki   twiki        231 Jun  8  1999 twikicatview.tmpl

directory twiki/data/ :

drwxrwxrwx   8 twiki   twiki       1024 Feb 26 04:17 .
drwxr-xr-x   8 twiki   twiki       1024 Feb 26 04:20 ..
-rw-r--r--   1 nobody  nobody      2241 Feb 25 20:18 .htpasswd
drwxrwxrwx   2 twiki   twiki       3072 Feb 27 01:15 Know
drwxrwxrwx   2 twiki   twiki       9216 Feb 27 18:16 Main
-rw-rw-rw-   1 twiki   twiki          1 Feb 26 06:01 debug.txt
-rw-r--r--   1 nobody  nobody   1263064 Jan 31 23:13 log200001.txt
-rw-r--r--   1 nobody  nobody   1063398 Feb 27 18:33 log200002.txt

part of directory twiki/data/Main :

drwxrwxrwx   2 twiki   twiki       9216 Feb 27 18:16 .
drwxrwxrwx   8 twiki   twiki       1024 Feb 26 04:17 ..
-rw-rw-rw-   1 twiki   twiki       5722 Feb 27 18:13 .changes
-rw-rw-rw-   1 twiki   twiki          9 Feb 27 18:15 .mailnotify
-rw-r--r--   1 nobody  nobody     26163 Feb 24 12:22 TWikiDocumentation.txt
-r--r--r--   1 nobody  nobody     44133 Feb 24 12:22 TWikiDocumentation.txt,v
-rw-r--r--   1 nobody  nobody     11661 Feb 27 18:13 TWikiHistory.txt
-r--r--r--   1 nobody  nobody     18877 Feb 27 18:13 TWikiHistory.txt,v
-rw-r--r--   1 nobody  nobody      3029 Feb 26 04:46 TWikiPreferences.txt
-r--r--r--   1 nobody  nobody      3219 Feb 26 04:46 TWikiPreferences.txt,v
-rw-r--r--   1 nobody  nobody      7188 Feb 11 21:39 TWikiRegistration.txt
-r--r--r--   1 nobody  nobody      7375 Feb 11 21:39 TWikiRegistration.txt,v
-rw-r--r--   1 nobody  nobody      3180 Feb 25 20:19 TWikiUsers.txt
-r--r--r--   1 nobody  nobody     16537 Feb 25 20:19 TWikiUsers.txt,v
-rw-r--r--   1 nobody  nobody      2613 Feb  7 04:47 TWikiVariables.txt
-r--r--r--   1 nobody  nobody      3125 Feb  7 04:47 TWikiVariables.txt,v
-rw-r--r--   1 nobody  nobody      2068 Feb 10 11:34 TWikiWeb.txt
-r--r--r--   1 nobody  nobody      3610 Feb 10 11:34 TWikiWeb.txt,v
-rw-r--r--   1 nobody  nobody      1677 Feb 26 05:11 TWikiWebsTable.txt
-r--r--r--   1 nobody  nobody      1866 Feb 26 05:11 TWikiWebsTable.txt,v
-rw-r--r--   1 nobody  nobody      2294 Feb 27 17:54 WebHome.txt
-r--r--r--   1 nobody  nobody      5282 Feb 27 17:54 WebHome.txt,v
-rw-r--r--   1 nobody  nobody       586 Jan 17 01:05 WebNotify.txt
-r--r--r--   1 nobody  nobody      1629 Jan 17 01:05 WebNotify.txt,v
-rw-r--r--   1 nobody  nobody      1834 Feb 25 14:13 WebPreferences.txt
-r--r--r--   1 nobody  nobody      2023 Feb 25 14:13 WebPreferences.txt,v
-rw-r--r--   1 nobody  nobody      4407 Feb 11 21:08 WebSearch.txt
-r--r--r--   1 nobody  nobody     10822 Feb 11 21:08 WebSearch.txt,v
-rw-r--r--   1 nobody  nobody      4416 Feb 27 00:00 WebStatistics.txt
-r--r--r--   1 nobody  nobody     27759 Feb 27 00:00 WebStatistics.txt,v

directory twiki/pub/ :

drwxrwxrwx  11 twiki   twiki       1024 Feb  8 18:10 .
drwxr-xr-x   8 twiki   twiki       1024 Feb 26 04:20 ..
drwxrwxrwx   4 nobody  nobody      1024 Aug 28  1999 Know
drwxrwxrwx  19 nobody  nobody      1024 Feb 27 09:56 Main
-rw-r--r--   1 twiki   twiki       1078 Jan 14 20:24 favicon.ico
drwxr-xr-x   2 twiki   twiki       1024 Mar 27  1999 icn
-rw-r--r--   1 twiki   twiki       3016 Sep 10 04:27 twikilogo.gif
-rw-r--r--   1 twiki   twiki       5320 Sep 10 04:27 twikilogo1.gif
-rw-r--r--   1 twiki   twiki       6125 Sep 10 04:27 twikilogo2.gif
-rw-r--r--   1 twiki   twiki       7218 Sep 10 04:27 twikilogo3.gif
-rw-r--r--   1 twiki   twiki       6710 Sep 11 02:21 twikilogo4.gif
-rw-r--r--   1 twiki   twiki       2877 Jun 15  1999 wikiHome.gif

directory twiki/pub/icn/ :

drwxr-xr-x   2 twiki   twiki       1024 Mar 27  1999 .
drwxrwxrwx  11 twiki   twiki       1024 Feb  8 18:10 ..
-rw-r--r--   1 twiki   twiki        801 Mar 27  1999 _filetypes.txt
-rw-r--r--   1 twiki   twiki        143 Mar 27  1999 bat.gif
-rw-r--r--   1 twiki   twiki        926 Mar 27  1999 bmp.gif
-rw-r--r--   1 twiki   twiki        141 Mar 27  1999 c.gif
-rw-r--r--   1 twiki   twiki        144 Mar 27  1999 dll.gif
-rw-r--r--   1 twiki   twiki        152 Mar 27  1999 doc.gif
-rw-r--r--   1 twiki   twiki        130 Mar 27  1999 else.gif
-rw-r--r--   1 twiki   twiki        876 Mar 27  1999 exe.gif
-rw-r--r--   1 twiki   twiki        147 Mar 27  1999 fon.gif
-rw-r--r--   1 twiki   twiki        142 Mar 27  1999 h.gif
-rw-r--r--   1 twiki   twiki        156 Mar 27  1999 hlp.gif
-rw-r--r--   1 twiki   twiki        186 Mar 27  1999 html.gif
-rw-r--r--   1 twiki   twiki        144 Mar 27  1999 java.gif
-rw-r--r--   1 twiki   twiki        148 Mar 27  1999 mov.gif
-rw-r--r--   1 twiki   twiki        150 Mar 27  1999 pdf.gif
-rw-r--r--   1 twiki   twiki        146 Mar 27  1999 pl.gif
-rw-r--r--   1 twiki   twiki        150 Mar 27  1999 ppt.gif
-rw-r--r--   1 twiki   twiki        148 Mar 27  1999 ps.gif
-rw-r--r--   1 twiki   twiki        148 Mar 27  1999 py.gif
-rw-r--r--   1 twiki   twiki        130 Mar 27  1999 ram.gif
-rw-r--r--   1 twiki   twiki        154 Mar 27  1999 reg.gif
-rw-r--r--   1 twiki   twiki        147 Mar 27  1999 sh.gif
-rw-r--r--   1 twiki   twiki        155 Mar 27  1999 sniff.gif
-rw-r--r--   1 twiki   twiki        149 Mar 27  1999 ttf.gif
-rw-r--r--   1 twiki   twiki        134 Mar 27  1999 txt.gif
-rw-r--r--   1 twiki   twiki        154 Mar 27  1999 wav.gif
-rw-r--r--   1 twiki   twiki        152 Mar 27  1999 wri.gif
-rw-r--r--   1 twiki   twiki        152 Mar 27  1999 xls.gif
-rw-r--r--   1 twiki   twiki        144 Mar 27  1999 zip.gif
>
>


(7) Upgrading Earlier Versions to TWiki 01 Mai 2000
Changed:
<
<

-- PeterThoeny - 05 Apr 2000

>
>

To upgrade an earlier TWiki version like 01 Sep 1999 to version 01 May 2000 you should do the following things:

  • Back up your system.
  • Update the templates in the /templates directory (and its subdirs):
    • Take the templates of the latest distribution as the base and merge your changes back into it.
  • Update the Perl scripts in the /bin directory:
    • Take the scripts of the latest distribution as the base and merge your changes back into it. Do so also for wikicfg.pm because it has important changes as well.
  • Update topics:
  • Add the PoweredByTWikiLogo to your Tharsis home page.

-- PeterThoeny - 28 Apr 2000


 <<O>>  Difference Topic TWikiDocumentation (r1.11 - 28 Feb 2000 - PeterThoeny)
Changed:
<
<

Documentation of the TWiki Implementation

>
>

Documentation of the TWiki Implementation (version 01 Dec 2001)

Added:
>
>

geturl Script to fetch URL data
Added:
>
>

statistics Script to create statistics topic
testenv Script to test CGI environment variables
Added:
>
>

wikisearch.pm search engine, used by wiki.pm
Changed:
<
<

>
>

Deleted:
<
<

  • Make sure PERL and the PERL CGI library is installed on your system. Default location of PERL executable is /usr/bin/perl . In case PERL is installed in a different location, the first line of all perl scripts in the twiki/bin directory need to be changed (alternatively you can create a symbolic link from /usr/bin/perl ).
Changed:
<
<

  • On systems where the Perl scripts require a file extension you need to:
    • Rename all scripts in the twiki/bin directory to have a file extension, i.e. rename view to view.cgi .
    • Specify this file extension in the $scriptSuffix variable in twiki/bin/wikicfg.pm .
>
>

  • Make sure PERL and the PERL CGI library is installed on your system. Default location of PERL executable is /usr/bin/perl . In case PERL is installed in a different location, the first line of all perl scripts in the twiki/bin directory need to be changed (alternatively you can create a symbolic link from /usr/bin/perl ).
Changed:
<
<

  • Point your browser at http://your.domain.com/twiki/bin/view and start wiki-ing away!
  • Note in case cgi user is not nobody : The *,v RCS repository files delivered with the installation package are locked by user nobody . In case the user is different (e.g. www-data ), it is not possible to check in files, this has the effect that the topic version number does not increase when saving a topic. In this case you need to unlock all repository files and lock them as user www-data , or simply delete all the repository files.
>
>

  • Point your browser at http://your.domain.com/twiki/bin/view and start wiki-ing away!
  • Note in case cgi user is not nobody : The *,v RCS repository files delivered with the installation package are locked by user nobody . In case the user is different (e.g. www-data ), it is not possible to check in files, this has the effect that the topic version number does not increase when saving a topic. In this case you need to unlock all repository files and lock them as user www-data (check the rcs man pages), or simply delete all the repository files.
Added:
>
>

  • Enable email notification of topic changes, (3) has more.
Changed:
<
<

      • Update current month for all webs:
        http://www.tharsis-gate.org/twiki/bin/statistics
      • Update current month for Main web only:
        http://www.tharsis-gate.org/twiki/bin/statistics/Main
      • Update January 2000 for Main web:
        http://www.tharsis-gate.org/twiki/bin/statistics/Main?logdate=200001
>
>

      • Update current month for all webs:
        http://mydomain.com/twiki/bin/statistics
      • Update current month for Main web only:
        http://mydomain.com/twiki/bin/statistics/Main
      • Update January 2000 for Main web:
        http://mydomain.com/twiki/bin/statistics/Main?logdate=200001
Changed:
<
<

    • Copy the files WebHome.txt , WebNotify.txt , WebSearch.txt , WebStatistics.txt , webcolor.inc and weblist.inc from the twiki/data/Main directory to the new data directory, preserving the original files' owner, group and permissions ( on Unix use cp -p ). The data files must be writable by the owner the CGI scripts are running on ( usually nobody ). Hint: You can set permissions of .txt and .txt,v files to -rw-rw-rw- and then edit the topic using your browser, RCS will restore the file permission correctly when saving the topic.
    • Change webcolor.inc to a color of your taste. The number represents the unique color for the web (consult an HTML book for colors.) Note: The file must not have a new line, just the number without a return.
    • Customize weblist.inc (web specific links on top) if needed.
    • Add the new web in twiki/data/wikiwebs.inc (web specific links on top) and twiki/data/wikiwebtable.inc (table of all webs at the end of the WebHome topics).
    • In case you need a web specific copyright notice (at the bottom), copy file webcopyright.inc from the twiki/data directory to the new data directory, and customize it.
>
>

    • Copy the files WebHome.txt , WebPreferences.txt , WebNotify.txt , WebSearch.txt and WebStatistics.txt from the twiki/data/Main directory to the new data directory, preserving the original files' owner, group and permissions ( on Unix use cp -p ). The data files must be writable by the owner the CGI scripts are running on ( usually nobody ). Hint: You can set permissions of .txt and .txt,v files to -rw-rw-rw- and then edit the topic using your browser, RCS will restore the file permission correctly when saving the topic.
    • Add the new web to the web list (on top of each topic) by editing the site-level preferences TWikiPreferences?:
      • Add the new web to the WIKIWEBLIST variable.
    • Add the new web to the web table (at the bottom of each WebHome topic) by editing the TWikiWebsTable? topic.
    • Change the web preferences by editing the WebPreferences topic of the new web:
      • Set the WEBBGCOLOR variable to a color of your taste. The number represents the unique color for the web (consult an HTML book for colors.)
      • Customize the WEBTOPICLIST variable to contain the web specific links you prefer.
      • Optional: Set the WEBCOPYRIGHT variable to have a web-specific copyright text (at the bottom of each topic).
Changed:
<
<

    • In case you want usage statistics for this web: Copy file WebStatistics.txt from the twiki/data/Main directory to the new data directory. Edit topic WebStatistics and delete old usage entries.
>
>

    • In case you want usage statistics for this web: Copy file WebStatistics.txt from the twiki/data/Main directory to the new data directory. Edit topic WebStatistics in the new web and delete old usage entries.
Changed:
<
<

drwxr-xr-x 5 twiki t5 512 Nov 11 02:52 . drwxr-xr-x 5 twiki t5 512 Nov 6 02:57 .. -rw-r--r-- 1 twiki t5 430 Oct 21 18:51 .htaccess -rw-r-xr-x 1 twiki t5 3752 Mar 27 02:21 attach -rw-r-xr-x 1 twiki t5 2810 Oct 21 18:51 changes -rw-r-xr-x 1 twiki t5 1244 Mar 27 02:21 delete -rw-r-xr-x 1 twiki t5 2589 Nov 6 03:05 edit -rwxr--r-- 1 twiki t5 1811 Feb 4 12:15 geturl -rwxr-xr-x 1 twiki t5 4614 Oct 21 18:52 mailnotify -rw-r-xr-x 1 twiki t5 1353 Oct 23 20:19 oops -rw-r-xr-x 1 twiki t5 2043 Nov 6 03:05 preview -rw-r-xr-x 1 twiki t5 6249 Aug 3 04:34 register -rw-r-xr-x 1 twiki t5 6890 Nov 11 03:06 rdiff -rw-r-xr-x 1 twiki t5 1819 Nov 6 03:06 save -rw-r-xr-x 1 twiki t5 3174 Oct 21 18:51 search -rw-r-xr-x 1 twiki t5 9774 Feb 4 12:26 statistics -rwxr-xr-x 1 twiki t5 509 Feb 7 18:55 testenv -rw-r-xr-x 1 twiki t5 6696 Mar 27 02:22 upload -rw-r-xr-x 1 twiki t5 3878 Nov 11 03:06 view -rw-r-xr-x 1 twiki t5 1538 Mar 27 02:22 viewfile -rw-r-xr-x 1 twiki t5 16169 Nov 7 01:43 wiki.pm -rw-r-xr-x 1 twiki t5 3945 Jun 23 01:24 wikicfg.pm -rw-r-xr-x 1 twiki t5 5127 Feb 4 11:37 wikisearch.pm

>
>

drwxr-xr-x 2 twiki twiki 1024 Feb 18 18:31 . drwxr-xr-x 8 twiki twiki 1024 Feb 26 04:20 .. -rw-rw-r-- 1 twiki twiki 770 Feb 10 12:10 .htaccess -rw-r-xr-x 1 twiki twiki 3968 Feb 18 00:26 attach -rwxr-xr-x 1 twiki twiki 3033 Feb 17 23:57 changes -rw-r-xr-x 1 twiki twiki 1377 Feb 8 18:18 delete -rw-r-xr-x 1 twiki twiki 8785 Feb 17 23:58 edit -rwxr--r-- 1 twiki twiki 1811 Feb 4 14:31 geturl -rwxr-xr-x 1 twiki twiki 5047 Feb 8 20:33 mailnotify -rw-r-xr-x 1 twiki twiki 1825 Feb 8 18:29 oops -rw-r-xr-x 1 twiki twiki 6932 Feb 11 02:06 preview -rw-r-xr-x 1 twiki twiki 7804 Feb 17 23:59 rdiff -rw-r-xr-x 1 twiki twiki 7010 Feb 18 00:03 register -rw-r-xr-x 1 twiki twiki 2501 Jan 25 19:39 save -rwxr-xr-x 1 twiki twiki 1778 Feb 18 00:04 search -rw-r-xr-x 1 twiki twiki 9810 Feb 8 18:43 statistics -rwxr-xr-x 1 twiki twiki 509 Feb 7 18:55 testenv -rw-r-xr-x 1 twiki twiki 6856 Feb 18 00:11 upload -rw-r-xr-x 1 twiki twiki 4922 Feb 17 23:54 view -rw-r-xr-x 1 twiki twiki 1606 May 21 1999 viewfile -rw-r-xr-x 1 twiki twiki 27794 Feb 26 06:03 wiki.pm -rw-r-xr-x 1 twiki twiki 10143 Feb 27 04:03 wikicfg.pm -rw-r-xr-x 1 twiki twiki 5440 Feb 7 04:36 wikisearch.pm

Changed:
<
<

drwxr-xr-x 6 twiki t5 512 Nov 4 20:34 . drwxr-xr-x 5 twiki t5 512 Nov 11 02:52 .. drwxr-xr-x 2 twiki t5 512 Oct 23 20:57 Know drwxr-xr-x 2 twiki t5 512 Nov 4 20:35 Main -rw-r--r-- 1 twiki t5 2232 Mar 27 02:03 attach.tmpl -rw-r--r-- 1 twiki t5 1200 Mar 27 02:03 attachtable.tmpl -rw-r--r-- 1 twiki t5 1751 Nov 11 02:41 changes.tmpl -rw-r--r-- 1 twiki t5 1711 Nov 6 03:01 edit.tmpl -rw-r--r-- 1 twiki t5 896 Oct 21 18:51 mailnotify.tmpl -rw-r--r-- 1 twiki t5 25 Oct 21 18:51 notedited.tmpl -rw-r--r-- 1 twiki t5 21 Oct 21 18:51 notext.tmpl -rw-r--r-- 1 twiki t5 157 Oct 23 21:05 notwiki.tmpl -rw-r--r-- 1 twiki t5 218 Oct 23 20:06 noweb.tmpl -rw-r--r-- 1 twiki t5 279 Oct 23 20:29 oops.tmpl -rw-r--r-- 1 twiki t5 833 Mar 27 02:03 oopsdel.tmpl -rw-r--r-- 1 twiki t5 1331 Oct 23 20:29 oopslocked.tmpl -rw-r--r-- 1 twiki t5 1026 Aug 03 08:21 oopsregexist.tmpl -rw-r--r-- 1 twiki t5 935 Aug 03 08:23 oopsregpasswd.tmpl -rw-r--r-- 1 twiki t5 924 Aug 03 08:26 oopsregrequ.tmpl -rw-r--r-- 1 twiki t5 931 Aug 03 08:29 oopsregwiki.tmpl -rw-r--r-- 1 twiki t5 868 Mar 27 02:03 oopsupload.tmpl -rw-r--r-- 1 twiki t5 2010 Nov 6 03:01 preview.tmpl -rw-r--r-- 1 twiki t5 1501 Nov 12 22:56 rdiff.tmpl -rw-r--r-- 1 twiki t5 263 Aug 3 02:44 register.tmpl -rw-r--r-- 1 twiki t5 1548 Oct 23 21:10 search.tmpl -rw-r--r-- 1 twiki t5 1541 Oct 26 21:07 view.tmpl

>
>

drwxr-xr-x 7 twiki twiki 1024 Jan 16 19:39 . drwxr-xr-x 8 twiki twiki 1024 Feb 26 04:20 .. drwxr-xr-x 2 twiki twiki 1024 Jun 8 1999 Know drwxr-xr-x 2 twiki twiki 1024 Dec 9 1998 Main -rw-r--r-- 1 twiki twiki 2286 Feb 24 21:50 attach.tmpl -rw-r--r-- 1 twiki twiki 1272 Feb 8 16:07 attachtable.tmpl -rw-r--r-- 1 twiki twiki 1884 Feb 24 21:54 changes.tmpl -rw-r--r-- 1 twiki twiki 2242 Feb 24 21:33 edit.tmpl -rw-r--r-- 1 twiki twiki 965 Feb 8 16:07 mailnotify.tmpl -rw-r--r-- 1 twiki twiki 30 Jan 14 1999 notedited.tmpl -rw-r--r-- 1 twiki twiki 934 Feb 8 16:07 notext.tmpl -rw-r--r-- 1 twiki twiki 899 Feb 8 16:07 notwiki.tmpl -rw-r--r-- 1 twiki twiki 299 Feb 24 21:58 noweb.tmpl -rw-r--r-- 1 twiki twiki 957 Feb 24 22:17 oops.tmpl -rw-r--r-- 1 twiki twiki 871 Feb 24 22:17 oopsdel.tmpl -rw-r--r-- 1 twiki twiki 1330 Feb 24 22:17 oopslocked.tmpl -rw-r--r-- 1 twiki twiki 1024 Feb 24 22:17 oopsregexist.tmpl -rw-r--r-- 1 twiki twiki 912 Feb 24 22:17 oopsregpasswd.tmpl -rw-r--r-- 1 twiki twiki 923 Feb 24 22:17 oopsregrequ.tmpl -rw-r--r-- 1 twiki twiki 1125 Feb 24 22:17 oopsregthanks.tmpl -rw-r--r-- 1 twiki twiki 942 Feb 24 22:17 oopsregwiki.tmpl -rw-r--r-- 1 twiki twiki 1564 Feb 24 22:17 oopsrev.tmpl -rw-r--r-- 1 twiki twiki 906 Feb 24 22:17 oopsupload.tmpl -rw-r--r-- 1 twiki twiki 1535 Feb 24 22:02 preview.tmpl -rw-r--r-- 1 twiki twiki 1661 Feb 24 22:04 rdiff.tmpl -rw-r--r-- 1 twiki twiki 263 Aug 3 1999 register.tmpl -rw-r--r-- 1 twiki twiki 936 Feb 8 16:08 registernotify.tmpl -rw-r--r-- 1 twiki twiki 1779 Feb 24 22:06 search.tmpl -rw-r--r-- 1 twiki twiki 1533 Feb 24 21:43 view.tmpl

Changed:
<
<

drwxr-xr-x 2 twiki t5 512 Nov 4 20:35 . drwxr-xr-x 6 twiki t5 512 Nov 4 20:34 .. -rw-r--r-- 1 twiki t5 2328 Nov 6 03:03 edit.tmpl

>
>

drwxr-xr-x 2 twiki twiki 1024 Dec 9 1998 . drwxr-xr-x 7 twiki twiki 1024 Jan 16 19:39 .. -rw-r--r-- 1 twiki twiki 2732 Feb 24 21:34 edit.tmpl

Changed:
<
<

drwxr-xr-x 2 twiki t5 512 Nov 4 20:35 . drwxr-xr-x 6 twiki t5 512 Nov 4 20:34 .. -rw-r--r-- 1 twiki t5 611 Dec 7 20:59 notedited.tmpl -rw-r--r-- 1 twiki t5 210 Dec 24 23:22 twikicatedit.tmpl -rw-r--r-- 1 twiki t5 1887 Jan 6 20:54 twikicatitems.tmpl -rw-r--r-- 1 twiki t5 245 Dec 24 23:27 twikicatview.tmpl

>
>

drwxr-xr-x 2 twiki twiki 1024 Jun 8 1999 . drwxr-xr-x 7 twiki twiki 1024 Jan 16 19:39 .. -rw-rw-r-- 1 twiki twiki 446 Jun 8 1999 notedited.tmpl -rw-rw-r-- 1 twiki twiki 206 Jun 8 1999 twikicatedit.tmpl -rw-rw-r-- 1 twiki twiki 1060 Jul 16 1999 twikicatitems.tmpl -rw-rw-r-- 1 twiki twiki 231 Jun 8 1999 twikicatview.tmpl

Changed:
<
<

drwxrwxrwx 6 twiki t5 512 Nov 19 01:01 . drwxr-xr-x 5 twiki t5 512 Nov 11 02:52 .. drwxrwxrwx 2 twiki t5 9216 Nov 13 13:55 Know drwxrwxrwx 2 twiki t5 4608 Nov 15 21:42 Main -rw-r--r-- 1 nobody 65535 53 Aug 03 08:31 .htpasswd -rw-rw-rw- 1 twiki t5 1091 Nov 6 04:15 debug.txt -rw-r--r-- 1 nobody 65535 4153 Nov 19 01:01 log199810.txt -rw-r--r-- 1 nobody 65535 7189 Nov 19 01:01 log199811.txt -rw-r--r-- 1 twiki t5 2356 Oct 22 00:56 webcopyright.inc -rw-r--r-- 1 twiki t5 276 Oct 22 00:28 wikiwebs.inc -rw-r--r-- 1 twiki t5 1484 Oct 22 01:11 wikiwebtable.inc

>
>

drwxrwxrwx 8 twiki twiki 1024 Feb 26 04:17 . drwxr-xr-x 8 twiki twiki 1024 Feb 26 04:20 .. -rw-r--r-- 1 nobody nobody 2241 Feb 25 20:18 .htpasswd drwxrwxrwx 2 twiki twiki 3072 Feb 27 01:15 Know drwxrwxrwx 2 twiki twiki 9216 Feb 27 18:16 Main -rw-rw-rw- 1 twiki twiki 1 Feb 26 06:01 debug.txt -rw-r--r-- 1 nobody nobody 1263064 Jan 31 23:13 log200001.txt -rw-r--r-- 1 nobody nobody 1063398 Feb 27 18:33 log200002.txt

Changed:
<
<

drwxrwxrwx 2 twiki t5 4608 Nov 19 00:56 . drwxrwxrwx 6 twiki t5 512 Nov 19 01:01 .. -rw-rw-rw- 1 twiki t5 5974 Nov 15 21:42 .changes -rw-rw-rw- 1 twiki t5 9 Nov 15 23:00 .mailnotify -rw-r--r-- 1 nobody 65535 3991 Jul 22 04:33 FileAttachment.txt -r--r--r-- 1 nobody 65535 4173 Jul 22 04:33 FileAttachment.txt,v -rw-r--r-- 1 nobody 65535 6773 Aug 5 16:18 TWikiRegistration.txt -r--r--r-- 1 nobody 65535 6960 Aug 5 16:18 TWikiRegistration.txt,v -rw-r--r-- 1 nobody 65535 1990 Nov 6 18:25 TWikiUsers?.txt -r--r--r-- 1 nobody 65535 3045 Nov 6 18:25 TWikiUsers?.txt,v -rw-r--r-- 1 nobody 65535 1181 Oct 29 20:54 WebHome.txt -r--r--r-- 1 nobody 65535 1537 Oct 29 20:54 WebHome.txt,v -rw-r--r-- 1 nobody 65535 454 Oct 21 18:52 WebNotify.txt -r--r--r-- 1 nobody 65535 638 Oct 27 02:45 WebNotify.txt,v -rw-r--r-- 1 nobody 65535 3653 Oct 21 18:52 WebSearch.txt -r--r--r-- 1 nobody 65535 3835 Oct 27 02:45 WebSearch.txt,v -rw-r--r-- 1 nobody 65535 4282 Feb 4 15:08 WebStatistics.txt -r--r--r-- 1 nobody 65535 4471 Feb 4 15:08 WebStatistics.txt,v -rw-r--r-- 1 twiki t5 7 Oct 21 18:52 webcolor.inc -rw-r--r-- 1 twiki t5 278 May 20 17:42 webcopyright.inc -rw-r--r-- 1 twiki t5 402 Oct 26 07:45 weblist.inc

>
>

drwxrwxrwx 2 twiki twiki 9216 Feb 27 18:16 . drwxrwxrwx 8 twiki twiki 1024 Feb 26 04:17 .. -rw-rw-rw- 1 twiki twiki 5722 Feb 27 18:13 .changes -rw-rw-rw- 1 twiki twiki 9 Feb 27 18:15 .mailnotify -rw-r--r-- 1 nobody nobody 26163 Feb 24 12:22 TWikiDocumentation.txt -r--r--r-- 1 nobody nobody 44133 Feb 24 12:22 TWikiDocumentation.txt,v -rw-r--r-- 1 nobody nobody 11661 Feb 27 18:13 TWikiHistory.txt -r--r--r-- 1 nobody nobody 18877 Feb 27 18:13 TWikiHistory.txt,v -rw-r--r-- 1 nobody nobody 3029 Feb 26 04:46 TWikiPreferences.txt -r--r--r-- 1 nobody nobody 3219 Feb 26 04:46 TWikiPreferences.txt,v -rw-r--r-- 1 nobody nobody 7188 Feb 11 21:39 TWikiRegistration.txt -r--r--r-- 1 nobody nobody 7375 Feb 11 21:39 TWikiRegistration.txt,v -rw-r--r-- 1 nobody nobody 3180 Feb 25 20:19 TWikiUsers?.txt -r--r--r-- 1 nobody nobody 16537 Feb 25 20:19 TWikiUsers?.txt,v -rw-r--r-- 1 nobody nobody 2613 Feb 7 04:47 TWikiVariables.txt -r--r--r-- 1 nobody nobody 3125 Feb 7 04:47 TWikiVariables.txt,v -rw-r--r-- 1 nobody nobody 2068 Feb 10 11:34 TWikiWeb?.txt -r--r--r-- 1 nobody nobody 3610 Feb 10 11:34 TWikiWeb?.txt,v -rw-r--r-- 1 nobody nobody 1677 Feb 26 05:11 TWikiWebsTable.txt -r--r--r-- 1 nobody nobody 1866 Feb 26 05:11 TWikiWebsTable.txt,v -rw-r--r-- 1 nobody nobody 2294 Feb 27 17:54 WebHome.txt -r--r--r-- 1 nobody nobody 5282 Feb 27 17:54 WebHome.txt,v -rw-r--r-- 1 nobody nobody 586 Jan 17 01:05 WebNotify.txt -r--r--r-- 1 nobody nobody 1629 Jan 17 01:05 WebNotify.txt,v -rw-r--r-- 1 nobody nobody 1834 Feb 25 14:13 WebPreferences.txt -r--r--r-- 1 nobody nobody 2023 Feb 25 14:13 WebPreferences.txt,v -rw-r--r-- 1 nobody nobody 4407 Feb 11 21:08 WebSearch.txt -r--r--r-- 1 nobody nobody 10822 Feb 11 21:08 WebSearch.txt,v -rw-r--r-- 1 nobody nobody 4416 Feb 27 00:00 WebStatistics.txt -r--r--r-- 1 nobody nobody 27759 Feb 27 00:00 WebStatistics.txt,v

Changed:
<
<

drwxrwxrwx 4 twiki t5 1024 Mar 27 02:58 . drwxr-xr-x 4 twiki t5 1024 Mar 27 02:08 .. drwxrwxrwx 4 nobody nobody 1024 Mar 27 03:54 Main -rw-r--r-- 1 twiki t5 2877 Mar 27 02:27 wikiHome.gif drwxr-xr-x 2 twiki t5 1024 Mar 27 03:17 icn

>
>

drwxrwxrwx 11 twiki twiki 1024 Feb 8 18:10 . drwxr-xr-x 8 twiki twiki 1024 Feb 26 04:20 .. drwxrwxrwx 4 nobody nobody 1024 Aug 28 1999 Know drwxrwxrwx 19 nobody nobody 1024 Feb 27 09:56 Main -rw-r--r-- 1 twiki twiki 1078 Jan 14 20:24 favicon.ico drwxr-xr-x 2 twiki twiki 1024 Mar 27 1999 icn -rw-r--r-- 1 twiki twiki 3016 Sep 10 04:27 twikilogo.gif -rw-r--r-- 1 twiki twiki 5320 Sep 10 04:27 twikilogo1.gif -rw-r--r-- 1 twiki twiki 6125 Sep 10 04:27 twikilogo2.gif -rw-r--r-- 1 twiki twiki 7218 Sep 10 04:27 twikilogo3.gif -rw-r--r-- 1 twiki twiki 6710 Sep 11 02:21 twikilogo4.gif -rw-r--r-- 1 twiki twiki 2877 Jun 15 1999 wikiHome.gif

Changed:
<
<

drwxr-xr-x 2 twiki t5 1024 Mar 27 03:17 . drwxrwxrwx 4 twiki t5 1024 Mar 27 02:58 .. -rw-r--r-- 1 twiki t5 801 Mar 27 03:02 _filetypes.txt -rw-r--r-- 1 twiki t5 143 Mar 27 03:16 bat.gif -rw-r--r-- 1 twiki t5 926 Mar 27 03:16 bmp.gif -rw-r--r-- 1 twiki t5 141 Mar 27 03:16 c.gif -rw-r--r-- 1 twiki t5 144 Mar 27 03:16 dll.gif -rw-r--r-- 1 twiki t5 152 Mar 27 03:16 doc.gif -rw-r--r-- 1 twiki t5 130 Mar 27 03:16 else.gif -rw-r--r-- 1 twiki t5 876 Mar 27 03:16 exe.gif -rw-r--r-- 1 twiki t5 147 Mar 27 03:16 fon.gif -rw-r--r-- 1 twiki t5 142 Mar 27 03:16 h.gif -rw-r--r-- 1 twiki t5 156 Mar 27 03:16 hlp.gif -rw-r--r-- 1 twiki t5 186 Mar 27 03:16 html.gif -rw-r--r-- 1 twiki t5 144 Mar 27 03:16 java.gif -rw-r--r-- 1 twiki t5 148 Mar 27 03:16 mov.gif -rw-r--r-- 1 twiki t5 150 Mar 27 03:16 pdf.gif -rw-r--r-- 1 twiki t5 146 Mar 27 03:16 pl.gif -rw-r--r-- 1 twiki t5 150 Mar 27 03:16 ppt.gif -rw-r--r-- 1 twiki t5 148 Mar 27 03:16 ps.gif -rw-r--r-- 1 twiki t5 148 Mar 27 03:16 py.gif -rw-r--r-- 1 twiki t5 130 Mar 27 03:17 ram.gif -rw-r--r-- 1 twiki t5 154 Mar 27 03:17 reg.gif -rw-r--r-- 1 twiki t5 147 Mar 27 03:17 sh.gif -rw-r--r-- 1 twiki t5 155 Mar 27 03:17 sniff.gif -rw-r--r-- 1 twiki t5 149 Mar 27 03:17 ttf.gif -rw-r--r-- 1 twiki t5 134 Mar 27 03:17 txt.gif -rw-r--r-- 1 twiki t5 154 Mar 27 03:17 wav.gif -rw-r--r-- 1 twiki t5 152 Mar 27 03:17 wri.gif -rw-r--r-- 1 twiki t5 152 Mar 27 03:17 xls.gif -rw-r--r-- 1 twiki t5 144 Mar 27 03:17 zip.gif

>
>

drwxr-xr-x 2 twiki twiki 1024 Mar 27 1999 . drwxrwxrwx 11 twiki twiki 1024 Feb 8 18:10 .. -rw-r--r-- 1 twiki twiki 801 Mar 27 1999 _filetypes.txt -rw-r--r-- 1 twiki twiki 143 Mar 27 1999 bat.gif -rw-r--r-- 1 twiki twiki 926 Mar 27 1999 bmp.gif -rw-r--r-- 1 twiki twiki 141 Mar 27 1999 c.gif -rw-r--r-- 1 twiki twiki 144 Mar 27 1999 dll.gif -rw-r--r-- 1 twiki twiki 152 Mar 27 1999 doc.gif -rw-r--r-- 1 twiki twiki 130 Mar 27 1999 else.gif -rw-r--r-- 1 twiki twiki 876 Mar 27 1999 exe.gif -rw-r--r-- 1 twiki twiki 147 Mar 27 1999 fon.gif -rw-r--r-- 1 twiki twiki 142 Mar 27 1999 h.gif -rw-r--r-- 1 twiki twiki 156 Mar 27 1999 hlp.gif -rw-r--r-- 1 twiki twiki 186 Mar 27 1999 html.gif -rw-r--r-- 1 twiki twiki 144 Mar 27 1999 java.gif -rw-r--r-- 1 twiki twiki 148 Mar 27 1999 mov.gif -rw-r--r-- 1 twiki twiki 150 Mar 27 1999 pdf.gif -rw-r--r-- 1 twiki twiki 146 Mar 27 1999 pl.gif -rw-r--r-- 1 twiki twiki 150 Mar 27 1999 ppt.gif -rw-r--r-- 1 twiki twiki 148 Mar 27 1999 ps.gif -rw-r--r-- 1 twiki twiki 148 Mar 27 1999 py.gif -rw-r--r-- 1 twiki twiki 130 Mar 27 1999 ram.gif -rw-r--r-- 1 twiki twiki 154 Mar 27 1999 reg.gif -rw-r--r-- 1 twiki twiki 147 Mar 27 1999 sh.gif -rw-r--r-- 1 twiki twiki 155 Mar 27 1999 sniff.gif -rw-r--r-- 1 twiki twiki 149 Mar 27 1999 ttf.gif -rw-r--r-- 1 twiki twiki 134 Mar 27 1999 txt.gif -rw-r--r-- 1 twiki twiki 154 Mar 27 1999 wav.gif -rw-r--r-- 1 twiki twiki 152 Mar 27 1999 wri.gif -rw-r--r-- 1 twiki twiki 152 Mar 27 1999 xls.gif -rw-r--r-- 1 twiki twiki 144 Mar 27 1999 zip.gif

Changed:
<
<

-- PeterThoeny - 11 Feb 2000

>
>

-- PeterThoeny - 05 Apr 2000


 <<O>>  Difference Topic TWikiDocumentation (r1.10 - 12 Feb 2000 - PeterThoeny)
Changed:
<
<

>
>

Added:
>
>

  • Make sure PERL and the PERL CGI library is installed on your system. Default location of PERL executable is /usr/bin/perl . In case PERL is installed in a different location, the first line of all perl scripts in the twiki/bin directory need to be changed (alternatively you can create a symbolic link from /usr/bin/perl ).
Changed:
<
<

  • Make sure PERL and the PERL CGI library is installed on your system. Default location of PERL executable is /usr/bin/perl . In case PERL is installed in a different location, the first line of all perl scripts in the twiki/bin directory need to be changed (alternatively you can create a symbolic link from /usr/bin/perl ).
>
>

  • On systems where the Perl scripts require a file extension you need to:
    • Rename all scripts in the twiki/bin directory to have a file extension, i.e. rename view to view.cgi .
    • Specify this file extension in the $scriptSuffix variable in twiki/bin/wikicfg.pm .
Changed:
<
<

>
>

  • Point your browser at http://your.domain.com/twiki/bin/view and start wiki-ing away!
Changed:
<
<

-- PeterThoeny - 22 Oct 1998
-- PeterThoeny - 18 Nov 1998
-- PeterThoeny - 11 Jan 1999
-- PeterThoeny - 20 Jan 1999
-- PeterThoeny - 06 Mar 1999
-- PeterThoeny - 27 Mar 1999
-- PeterThoeny - 02 Jun 1999
-- PeterThoeny - 14 Jun 1999
-- PeterThoeny - 23 Jun 1999
-- PeterThoeny - 01 Sep 1999
-- PeterThoeny - 29 Sep 1999
-- PeterThoeny - 14 Jan 2000
-- PeterThoeny - 02 Feb 2000
-- PeterThoeny - 04 Feb 2000

>
>

-- PeterThoeny - 11 Feb 2000


 <<O>>  Difference Topic TWikiDocumentation (r1.9 - 04 Feb 2000 - PeterThoeny)
Changed:
<
<

TWiki Variables

Text strings expanded on the fly to display data or system info

Overview

TWikiVariables are text strings - %VARIABLE% - that expand into content whenever a page is opened. Variables are replaced by their actual values: stored data, or system info (like the date, or the current user). There are predefined variables, and Preference variables that you set. You can also define custom variables, with new names and values.

Predefined Variables

Most predefined variables return values that were either defined when TWiki was installed, or taken from server info (like current username, or date and time). Many of the variables let you control how the formatted results appear.

Tharsis expands the following variables (enclosed in % percent signs):

Variable: Expanded to:
%WIKIHOMEURL% The base script URL of Tharsis, is the link of the Home icon in the upper left corner, is http://tharsis-gate.org/twiki
%SCRIPTURL% The script URL of Tharsis, is http://www.tharsis-gate.org/twiki/bin
%SCRIPTURLPATH% The path of the script URL of Tharsis, is /twiki/bin
%SCRIPTSUFFIX% The script suffix, ex: .pl, .cgi is
%PUBURL% The public URL of TWiki, is http://www.tharsis-gate.org/twiki/pub
%PUBURLPATH% The path of the public URL of Tharsis, is /twiki/pub
%ATTACHURL% The attachment URL of the current topic, is http://www.tharsis-gate.org/twiki/pub/TWiki/TWikiVariables
Example: If you attach a file you can refer to it as %ATTACHURL%/image.gif
%ATTACHURLPATH% The path of the attachment URL of the current topic, is /twiki/pub/TWiki/TWikiVariables
%URLPARAM{"name"}% Returns the value of a URL parameter. Ex: %URLPARAM{"skin"}% returns print for a .../view/TWiki/TWikiVariables?skin=print URL. Is
%WIKITOOLNAME% Name of wiki tool, is Tharsis
%WIKIVERSION% Wiki tool version is 01 Dec 2001
%USERNAME% Your login username is guest
%WIKINAME% Your Wiki username. Same as %USERNAME% if not defined in the TWikiUsers topic. Is guest
%WIKIUSERNAME% Your %WIKINAME% including the Main web name. Usefull for signatures. Is Main.guest
%MAINWEB% The Main web containing TWikiUsers, OfficeLocations? and TWikiGroups. Is Main
%TWIKIWEB% The web containing all documentation and configuration of Tharsis is TWiki
%WEB% The current web is TWiki
%BASEWEB% The web name where the includes started, e.g. the web of the first topic of nested includes. Same as %WEB% in case there is no include.
%INCLUDINGWEB% The web name of the topic that includes the current topic. Same as %WEB% in case there is no include.
%HOMETOPIC% The home topic in each web. Is WebHome
%NOTIFYTOPIC% The notify topic in each web. Is WebNotify
%WIKIUSERSTOPIC% The index topic of all registered users. Is TWikiUsers
%WIKIPREFSTOPIC% The web preferences topic. Is TWikiPreferences
%WEBPREFSTOPIC% The web preferences topic. Is WebPreferences
%STATISTICSTOPIC% The web statistics topic. Is WebStatistics
%TOPIC% The current topic name, is TWikiVariables
%BASETOPIC% The name of the topic where the includes started, e.g. the first topic of nested includes. Same as %TOPIC% in case there is no include.
%INCLUDINGTOPIC% The name of the topic that includes the current topic. Same as %TOPIC% in case there is no include.
%SPACEDTOPIC% The current topic name with added spaces, for regular expression search of Ref-By, is TWiki%20*Variables
%TOPICLIST{"format"}% Topic index of a web. The "format" defines the format of one topic item. It may include variables: The $name variable gets expanded to the topic name; the $web variable gets expanded to the name of the web. Parameters are format, separator and web:
Parameter: Description: Default:
"format" Format of one line, may include $name and $web variables "$name"
format="format" (Alternative to above) "$name"
separator=", " line separator "\n" (new line)
web="Name" Name of web Current web
Examples:
%TOPICLIST{"   * $web.$name"}% creates a bullet list of all topics.
%TOPICLIST{separator=", "}% creates a comma separated list of all topics.
%TOPICLIST{" <option>$name</option>"}% creates an option list (for drop down menus).
%WEBLIST{"format"}% Web index, e.g. list of all webs. Hidden webs are excluded, e.g. webs with a NOSEARCHALL=on preference variable. The "format" defines the format of one web item. The $name variable gets expanded to the name of the web, $qname gets expanded to double quoted name, $marker to marker where web matches selection. Parameters are format, separator and web:
Parameter: Description: Default:
"format" Format of one line, may include $name variable "$name"
format="format" (Alternative to above) "$name"
separator=", " line separator "\n" (new line)
webs="public" comma sep list of Web, public expands to all non-hidden "public"
marker="selected" Text for $marker where item matches selection, otherwise equals "" "selected"
selection="%WEB%" Current value to be selected in list section="%WEB%"
Examples:
%WEBLIST{"   * [[$name.WebHome]]"}% creates a bullet list of all webs.
%WEBLIST{"" webs="Trash,public" selection="TWiki" separator=" "}% Dropdown of all public Webs + Trash Web, current Web highlighted.
%GMTIME% GM time, is Thu Oct 17 01:20:10 2019
%GMTIME{"format"}% Formatted GM time based on time variables.
Variable: Unit: Example
$seconds seconds 59
$minutes minutes 59
$hours hours 23
$day day of month 31
$month month in ISO format Dec
$mo 2 digit month 12
$year 4 digit year 1999
$ye 2 digit year 99
Variables can be shortened to 3 characters. Example:
%GMTIME{"$day $month, $year - $hour:$min:$sec"}% is
17 Oct, 2019 - 01:20:10
%SERVERTIME% Server time, is Thu Oct 17 12:20:10 2019
%SERVERTIME{"format"}% Formatted server time.
Example: %SERVERTIME{"$hou:$min"}% is 12:20
%HTTP_HOST% HTTP_HOST environment variable, is www.tharsis-gate.org
%REMOTE_ADDR% REMOTE_ADDR environment variable, is 35.175.191.168
%REMOTE_PORT% REMOTE_PORT environment variable, is 59676
%REMOTE_USER% REMOTE_USER environment variable, is
%INCLUDE{"page" ...}% Server side include to IncludeTopicsAndWebPages. Parameters are page name, and an optional pattern="(reg-exp)". The page name is:
"SomeTopic" The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}%
"Web.Topic" A topic in another web, i.e. %INCLUDE{"TWiki.TWikiWebsTable"}%
"http://..." A full qualified URL, i.e. %INCLUDE{"http://twiki.org/"}%
%STARTINCLUDE% If present in included topic, start to include text from this location up to the end, or up to the location of the %STOPINCLUDE% variable. A normal view of the topic shows everyting exept the %STARTINCLUDE% variable itself.
%STOPINCLUDE% If present in included topic, stop to include text at this location and ignore the remaining text. A normal view of the topic shows everyting exept the %STOPINCLUDE% variable itself.
%TOC% Table of Contents of current topic.
%TOC{"SomeTopic" ...}% Table of Contents. Shows a TOC that is generated automatically based on headings of a topic. Headings in WikiSyntax ("---++ text") and HTML ("<h2>text<h2>") are taken into account. (But not "<H2>text</H2>", which can be used to exclude a heading from the TOC.) Parameters are topic name, web and depth:
Parameter: Description: Default:
"TopicName" topic name Current topic
web="Name" Name of web Current web
depth="2" Limit depth of headings shown in TOC 6
Examples: %TOC{depth="2"}%, %TOC{"TWikiDocumentation" web="TWiki"}%
%SEARCH{"text" ...}% Inline search, shows a search result embedded in a topic. Parameters are the search term, web, scope, order and many more: [1]
Parameter: Description: Default:
"text" Search term. (Is a regular expression or literal, depending on the regex parameter) required
search="text" (Alternative to above) N/A
web="Name"
web="Main Know"
web="all"
Wiki web to search: A web, a list of webs separated by whitespace, or all webs. [2] Current web
scope="topic"
scope="text"
Search topic name (title) or in the text (body) of the topic Topic text (body)
order="topic"
order="modified"
order="editby"
Sort the results of search by the topic names, last modified time, or last editor Sort by topic name
limit="all"
limit="16"
Limit the number of results returned All results
regex="on" RegularExpression search Literal search
reverse="on" Reverse the direction of the search Ascending search
casesensitive="on" Case sensitive search Ignore case
nosummary="on" Show topic title only Show topic summary
bookview="on" BookView search, e.g. show complete topic text Show topic summary
nosearch="on" Suppress search string Show search string
noheader="on" Suppress search header
Topics: Changed: By:
Show search header
nototal="on" Do not show number of topics found Show number
format="..." Flexible custom result formatting: see FormattedSearch for usage Results in table
Example: %SEARCH{"wiki" web="Main" scope="topic"}%
%METASEARCH{...}% Special search of meta data
Parameter: Description: Default:
type="topicmoved" What sort of search is required?
"topicmoved" if search for a topic that may have been moved
"parent" if searcing for topics that have a specific parent i.e. its children
required
web="%WEB%" Wiki web to search: A web, a list of webs separated by whitespace, or all webs. required
topic="%TOPIC%" The topic the search relates to required
title="Title" Text the is pre-pended to any search results required
Example: %METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%, you may want to use this in WebTopicViewTemplate and WebTopicNonWikiTemplate
%METASEARCH{type="parent" web="%WEB%" topic="%TOPIC%" title="Children: "}%
%VAR{"NAME" web="Web"}% Get a preference value from a web other then the current one. Example: To get %WEBBGCOLOR% of the Main web write %VAR{"WEBBGCOLOR" web="Main"}%, is #FFFFC0

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

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

Preferences Variables

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

Variable: Level: What:
%WIKIWEBMASTER% SL Webmaster email address (sender of email notifications) , is fantom@tharsis.dyndns.org
%WIKIWEBLIST% SL List of Tharsis webs (in upper right corner of topics)
%WEBTOPICLIST% WL Common links of web (second line of topics)
%WEBCOPYRIGHT% SL , WL Copyright notice (bottom right corner of topics)
%WEBBGCOLOR% WL Background color of web
%NOSEARCHALL% WL Exclude web from a web="all" search (set variable to on for hidden webs)
%NEWTOPICBGCOLOR% SL , UL Background color of non existing topic. ( UL needs authentication for topic views )
%NEWTOPICFONTCOLOR% SL , UL Font color of non existing topic. ( UL needs authentication for topic views )
%EDITBOXWIDTH% SL , UL Horizontal size of edit box, is 70
%EDITBOXHEIGHT% SL , UL Vertical size of edit box, is 15
%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: checked="checked"
%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:
%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:
%HTTP_EQUIV_ON_VIEW% SL http-equiv meta tags for view, rdiff, attach, search* scripts.
%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.
%DENYWEBCHANGE% WL List of users and groups who are not allowed to change topics in the Tharsis web. (More in TWikiAccessControl)
%ALLOWWEBCHANGE% WL List of users and groups who are allowed to change topics in the Tharsis web. (More in TWikiAccessControl)
%DENYTOPICCHANGE% (any topic) List of users and groups who are not allowed to change the current topic. (More in TWikiAccessControl)
%ALLOWTOPICCHANGE% (any topic) List of users and groups who are allowed to change the current topic. (More in TWikiAccessControl)
%DENYWEBRENAME% WL List of users and groups who are not allowed to rename topics in the Tharsis web. (More in TWikiAccessControl)
%ALLOWWEBRENAME% WL List of users and groups who are allowed to rename topics in the Tharsis web. (More in TWikiAccessControl)
%DENYTOPICRENAME% (any topic) List of users and groups who are not allowed to rename the current topic. (More in TWikiAccessControl)
%ALLOWTOPICRENAME% (any topic) List of users and groups who are allowed to rename the current topic. (More in TWikiAccessControl)
%FINALPREFERENCES% SL , WL List of preferences that are not allowed to be overridden by next level preferences

Setting Preferences

  • The syntax for Preferences variables is the same anywhere in TWiki. In Edit mode, from the start of a new line:
    [6 spaces] * [space] Set [space] VARIABLENAME [space] = [value]
    Example:
    • Set VARIABLENAME = value

Creating Custom Variables

  • You can add your own preference variables for an entire site, a single web, or a single topic, using the standard syntax. Whatever you include in your variable will be expanded on display, and treated exactly as if it had been written out. So you can place formatted text, page links, image paths.

Example: Create a custom logo variable
  • To place a logo anywhere in a web by typing %MYLOGO%, simply define the variable on the web's WebPreferences page. You also have to upload logo.gif - this can be done by attaching a file to LogoTopic (any topic name you choose):
    • Set MYLOGO = %PUBURL%/%MAINWEB%/LogoTopic/logo.gif

-- PeterThoeny - 13 Sep 2001
-- MikeMannix - 30 Nov 2001

>
>

TWiki Variables

Text strings expanded on the fly to display data or system info

Overview

TWikiVariables are text strings - %VARIABLE% - that expand into content whenever a page is opened. Variables are replaced by their actual values: stored data, or system info (like the date, or the current user). There are predefined variables, and Preference variables that you set. You can also define custom variables, with new names and values.

Predefined Variables

Most predefined variables return values that were either defined when TWiki was installed, or taken from server info (like current username, or date and time). Many of the variables let you control how the formatted results appear.

Tharsis expands the following variables (enclosed in % percent signs):

Variable: Expanded to:
%WIKIHOMEURL% The base script URL of Tharsis, is the link of the Home icon in the upper left corner, is http://tharsis-gate.org/twiki
%SCRIPTURL% The script URL of Tharsis, is http://www.tharsis-gate.org/twiki/bin
%SCRIPTURLPATH% The path of the script URL of Tharsis, is /twiki/bin
%SCRIPTSUFFIX% The script suffix, ex: .pl, .cgi is
%PUBURL% The public URL of TWiki, is http://www.tharsis-gate.org/twiki/pub
%PUBURLPATH% The path of the public URL of Tharsis, is /twiki/pub
%ATTACHURL% The attachment URL of the current topic, is http://www.tharsis-gate.org/twiki/pub/TWiki/TWikiVariables
Example: If you attach a file you can refer to it as %ATTACHURL%/image.gif
%ATTACHURLPATH% The path of the attachment URL of the current topic, is /twiki/pub/TWiki/TWikiVariables
%URLPARAM{"name"}% Returns the value of a URL parameter. Ex: %URLPARAM{"skin"}% returns print for a .../view/TWiki/TWikiVariables?skin=print URL. Is
%WIKITOOLNAME% Name of wiki tool, is Tharsis
%WIKIVERSION% Wiki tool version is 01 Dec 2001
%USERNAME% Your login username is guest
%WIKINAME% Your Wiki username. Same as %USERNAME% if not defined in the TWikiUsers topic. Is guest
%WIKIUSERNAME% Your %WIKINAME% including the Main web name. Usefull for signatures. Is Main.guest
%MAINWEB% The Main web containing TWikiUsers, OfficeLocations? and TWikiGroups. Is Main
%TWIKIWEB% The web containing all documentation and configuration of Tharsis is TWiki
%WEB% The current web is TWiki
%BASEWEB% The web name where the includes started, e.g. the web of the first topic of nested includes. Same as %WEB% in case there is no include.
%INCLUDINGWEB% The web name of the topic that includes the current topic. Same as %WEB% in case there is no include.
%HOMETOPIC% The home topic in each web. Is WebHome
%NOTIFYTOPIC% The notify topic in each web. Is WebNotify
%WIKIUSERSTOPIC% The index topic of all registered users. Is TWikiUsers
%WIKIPREFSTOPIC% The web preferences topic. Is TWikiPreferences
%WEBPREFSTOPIC% The web preferences topic. Is WebPreferences
%STATISTICSTOPIC% The web statistics topic. Is WebStatistics
%TOPIC% The current topic name, is TWikiVariables
%BASETOPIC% The name of the topic where the includes started, e.g. the first topic of nested includes. Same as %TOPIC% in case there is no include.
%INCLUDINGTOPIC% The name of the topic that includes the current topic. Same as %TOPIC% in case there is no include.
%SPACEDTOPIC% The current topic name with added spaces, for regular expression search of Ref-By, is TWiki%20*Variables
%TOPICLIST{"format"}% Topic index of a web. The "format" defines the format of one topic item. It may include variables: The $name variable gets expanded to the topic name; the $web variable gets expanded to the name of the web. Parameters are format, separator and web:
Parameter: Description: Default:
"format" Format of one line, may include $name and $web variables "$name"
format="format" (Alternative to above) "$name"
separator=", " line separator "\n" (new line)
web="Name" Name of web Current web
Examples:
%TOPICLIST{"   * $web.$name"}% creates a bullet list of all topics.
%TOPICLIST{separator=", "}% creates a comma separated list of all topics.
%TOPICLIST{" <option>$name</option>"}% creates an option list (for drop down menus).
%WEBLIST{"format"}% Web index, e.g. list of all webs. Hidden webs are excluded, e.g. webs with a NOSEARCHALL=on preference variable. The "format" defines the format of one web item. The $name variable gets expanded to the name of the web, $qname gets expanded to double quoted name, $marker to marker where web matches selection. Parameters are format, separator and web:
Parameter: Description: Default:
"format" Format of one line, may include $name variable "$name"
format="format" (Alternative to above) "$name"
separator=", " line separator "\n" (new line)
webs="public" comma sep list of Web, public expands to all non-hidden "public"
marker="selected" Text for $marker where item matches selection, otherwise equals "" "selected"
selection="%WEB%" Current value to be selected in list section="%WEB%"
Examples:
%WEBLIST{"   * [[$name.WebHome]]"}% creates a bullet list of all webs.
%WEBLIST{"" webs="Trash,public" selection="TWiki" separator=" "}% Dropdown of all public Webs + Trash Web, current Web highlighted.
%GMTIME% GM time, is Thu Oct 17 01:20:10 2019
%GMTIME{"format"}% Formatted GM time based on time variables.
Variable: Unit: Example
$seconds seconds 59
$minutes minutes 59
$hours hours 23
$day day of month 31
$month month in ISO format Dec
$mo 2 digit month 12
$year 4 digit year 1999
$ye 2 digit year 99
Variables can be shortened to 3 characters. Example:
%GMTIME{"$day $month, $year - $hour:$min:$sec"}% is
17 Oct, 2019 - 01:20:10
%SERVERTIME% Server time, is Thu Oct 17 12:20:10 2019
%SERVERTIME{"format"}% Formatted server time.
Example: %SERVERTIME{"$hou:$min"}% is 12:20
%HTTP_HOST% HTTP_HOST environment variable, is www.tharsis-gate.org
%REMOTE_ADDR% REMOTE_ADDR environment variable, is 35.175.191.168
%REMOTE_PORT% REMOTE_PORT environment variable, is 59676
%REMOTE_USER% REMOTE_USER environment variable, is
%INCLUDE{"page" ...}% Server side include to IncludeTopicsAndWebPages. Parameters are page name, and an optional pattern="(reg-exp)". The page name is:
"SomeTopic" The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}%
"Web.Topic" A topic in another web, i.e. %INCLUDE{"TWiki.TWikiWebsTable"}%
"http://..." A full qualified URL, i.e. %INCLUDE{"http://twiki.org/"}%
%STARTINCLUDE% If present in included topic, start to include text from this location up to the end, or up to the location of the %STOPINCLUDE% variable. A normal view of the topic shows everyting exept the %STARTINCLUDE% variable itself.
%STOPINCLUDE% If present in included topic, stop to include text at this location and ignore the remaining text. A normal view of the topic shows everyting exept the %STOPINCLUDE% variable itself.
%TOC% Table of Contents of current topic.
%TOC{"SomeTopic" ...}% Table of Contents. Shows a TOC that is generated automatically based on headings of a topic. Headings in WikiSyntax ("---++ text") and HTML ("<h2>text<h2>") are taken into account. (But not "<H2>text</H2>", which can be used to exclude a heading from the TOC.) Parameters are topic name, web and depth:
Parameter: Description: Default:
"TopicName" topic name Current topic
web="Name" Name of web Current web
depth="2" Limit depth of headings shown in TOC 6
Examples: %TOC{depth="2"}%, %TOC{"TWikiDocumentation" web="TWiki"}%
%SEARCH{"text" ...}% Inline search, shows a search result embedded in a topic. Parameters are the search term, web, scope, order and many more: [1]
Parameter: Description: Default:
"text" Search term. (Is a regular expression or literal, depending on the regex parameter) required
search="text" (Alternative to above) N/A
web="Name"
web="Main Know"
web="all"
Wiki web to search: A web, a list of webs separated by whitespace, or all webs. [2] Current web
scope="topic"
scope="text"
Search topic name (title) or in the text (body) of the topic Topic text (body)
order="topic"
order="modified"
order="editby"
Sort the results of search by the topic names, last modified time, or last editor Sort by topic name
limit="all"
limit="16"
Limit the number of results returned All results
regex="on" RegularExpression search Literal search
reverse="on" Reverse the direction of the search Ascending search
casesensitive="on" Case sensitive search Ignore case
nosummary="on" Show topic title only Show topic summary
bookview="on" BookView search, e.g. show complete topic text Show topic summary
nosearch="on" Suppress search string Show search string
noheader="on" Suppress search header
Topics: Changed: By:
Show search header
nototal="on" Do not show number of topics found Show number
format="..." Flexible custom result formatting: see FormattedSearch for usage Results in table
Example: %SEARCH{"wiki" web="Main" scope="topic"}%
%METASEARCH{...}% Special search of meta data
Parameter: Description: Default:
type="topicmoved" What sort of search is required?
"topicmoved" if search for a topic that may have been moved
"parent" if searcing for topics that have a specific parent i.e. its children
required
web="%WEB%" Wiki web to search: A web, a list of webs separated by whitespace, or all webs. required
topic="%TOPIC%" The topic the search relates to required
title="Title" Text the is pre-pended to any search results required
Example: %METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%, you may want to use this in WebTopicViewTemplate and WebTopicNonWikiTemplate
%METASEARCH{type="parent" web="%WEB%" topic="%TOPIC%" title="Children: "}%
%VAR{"NAME" web="Web"}% Get a preference value from a web other then the current one. Example: To get %WEBBGCOLOR% of the Main web write %VAR{"WEBBGCOLOR" web="Main"}%, is #FFFFC0

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

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

Preferences Variables

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

Variable: Level: What:
%WIKIWEBMASTER% SL Webmaster email address (sender of email notifications) , is fantom@tharsis.dyndns.org
%WIKIWEBLIST% SL List of Tharsis webs (in upper right corner of topics)
%WEBTOPICLIST% WL Common links of web (second line of topics)
%WEBCOPYRIGHT% SL , WL Copyright notice (bottom right corner of topics)
%WEBBGCOLOR% WL Background color of web
%NOSEARCHALL% WL Exclude web from a web="all" search (set variable to on for hidden webs)
%NEWTOPICBGCOLOR% SL , UL Background color of non existing topic. ( UL needs authentication for topic views )
%NEWTOPICFONTCOLOR% SL , UL Font color of non existing topic. ( UL needs authentication for topic views )
%EDITBOXWIDTH% SL , UL Horizontal size of edit box, is 70
%EDITBOXHEIGHT% SL , UL Vertical size of edit box, is 15
%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: checked="checked"
%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:
%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:
%HTTP_EQUIV_ON_VIEW% SL http-equiv meta tags for view, rdiff, attach, search* scripts.
%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.
%DENYWEBCHANGE% WL List of users and groups who are not allowed to change topics in the Tharsis web. (More in TWikiAccessControl)
%ALLOWWEBCHANGE% WL List of users and groups who are allowed to change topics in the Tharsis web. (More in TWikiAccessControl)
%DENYTOPICCHANGE% (any topic) List of users and groups who are not allowed to change the current topic. (More in TWikiAccessControl)
%ALLOWTOPICCHANGE% (any topic) List of users and groups who are allowed to change the current topic. (More in TWikiAccessControl)
%DENYWEBRENAME% WL List of users and groups who are not allowed to rename topics in the Tharsis web. (More in TWikiAccessControl)
%ALLOWWEBRENAME% WL List of users and groups who are allowed to rename topics in the Tharsis web. (More in TWikiAccessControl)
%DENYTOPICRENAME% (any topic) List of users and groups who are not allowed to rename the current topic. (More in TWikiAccessControl)
%ALLOWTOPICRENAME% (any topic) List of users and groups who are allowed to rename the current topic. (More in TWikiAccessControl)
%FINALPREFERENCES% SL , WL List of preferences that are not allowed to be overridden by next level preferences

Setting Preferences

  • The syntax for Preferences variables is the same anywhere in TWiki. In Edit mode, from the start of a new line:
    [6 spaces] * [space] Set [space] VARIABLENAME [space] = [value]
    Example:
    • Set VARIABLENAME = value

Creating Custom Variables

  • You can add your own preference variables for an entire site, a single web, or a single topic, using the standard syntax. Whatever you include in your variable will be expanded on display, and treated exactly as if it had been written out. So you can place formatted text, page links, image paths.

Example: Create a custom logo variable
  • To place a logo anywhere in a web by typing %MYLOGO%, simply define the variable on the web's WebPreferences page. You also have to upload logo.gif - this can be done by attaching a file to LogoTopic (any topic name you choose):
    • Set MYLOGO = %PUBURL%/%MAINWEB%/LogoTopic/logo.gif

-- PeterThoeny - 13 Sep 2001
-- MikeMannix - 30 Nov 2001

Changed:
<
<

  • New PublicFAQ? topic:
>
>

  • New PublicFAQ? topic:
Changed:
<
<

  • Test if the twiki/bin directory is cgi-enabled: Enter the URL of that directory into your browser (http://your.domain.com/twiki/bin). It is not set correctly as cgi-bin in case you get something like "Index of /twiki/bin" . It is OK if you get a message like "Forbidden. You don't have permission to access /twiki/bin/ on this server." .
>
>

  • Test if the twiki/bin directory is cgi-enabled:
    • Enter the URL of that directory into your browser ( http://your.domain.com/twiki/bin ). It is not set correctly as cgi-bin in case you get something like "Index of /twiki/bin" . It is OK if you get a message like "Forbidden. You don't have permission to access /twiki/bin/ on this server."
    • Execute the testenv script from your browser ( http://your.domain.com/twiki/bin/testenv ). It should show a table of all CGI environment variables.
Added:
>
>

Changed:
<
<

  • Optional: If you are on a public server and you would like to authenticate users you need to rename file .htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. Consult the HTTP server documentation for details, an example site for Apache is at http://info.mcs.kent.edu/system/web_help/htaccess/ . Note: In case .htaccess does not have any effect you need to enable it: Add "AllowOverride All" to the Directory section of access.conf for your twiki/bin directory.
>
>

  • Optional: If you are on a public server and you would like to authenticate users you need to rename file .htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. For details consult the HTTP server documentation (for Apache server: [1], [2], [3]). Note: In case .htaccess does not have any effect you need to enable it: Add "AllowOverride All" to the Directory section of access.conf for your twiki/bin directory.

  • Optional: You can automatically generate usage statistics for all webs. To enable this:
    • Make sure variable $doLogTopicView, $doLogTopicSave and $doLogTopicUpload in wikicfg.pm are set. This will generate log entries in file twiki/data/log<date>.txt .
    • Topic WebStatistics must be present in all webs where you want to have statistics. You can use the topic in the Main web as a template.
    • Call the twiki/bin/statistics script from a cron job, once a day is recommended. This will update the WebStatistics topics in all webs.
    • Attention: The script must run as the same user as the CGI scripts are running, which is user nobody on most systems. Example crontab entry:
      0 0 * * * (cd /path/to/TWiki/bin; ./statistics >/dev/null 2>&1)
    • There is a workaround in case you can't run the script as user nobody : Run the utility twiki/bin/geturl in your cron job and specify the URL of the twiki/bin/statistics script as a parameter. Example:
      0 0 * * * (cd /path/to/TWiki/bin; ./geturl mydomain.com /urlpath/to/TWiki/bin/statistics >/dev/null 2>&1)
    • The twiki/bin/statistics script can also be executed as a CGI script, just enter the URL in your browser. Examples:
      • Update current month for all webs:
        http://www.tharsis-gate.org/twiki/bin/statistics
      • Update current month for Main web only:
        http://www.tharsis-gate.org/twiki/bin/statistics/Main
      • Update January 2000 for Main web:
        http://www.tharsis-gate.org/twiki/bin/statistics/Main?logdate=200001
Changed:
<
<

    • Copy the files WebHome.txt , WebNotify.txt , WebSearch.txt , webcolor.inc and weblist.inc from the twiki/data/Main directory to the new data directory.
>
>

    • Copy the files WebHome.txt , WebNotify.txt , WebSearch.txt , WebStatistics.txt , webcolor.inc and weblist.inc from the twiki/data/Main directory to the new data directory, preserving the original files' owner, group and permissions ( on Unix use cp -p ). The data files must be writable by the owner the CGI scripts are running on ( usually nobody ). Hint: You can set permissions of .txt and .txt,v files to -rw-rw-rw- and then edit the topic using your browser, RCS will restore the file permission correctly when saving the topic.
Changed:
<
<

    • Add the new web in twiki/data/wikiwebs.inc (web specific links on top) and twiki/data/wikiwebtable.inc (table of all webs at the end of the WbHome? topics).
>
>

    • Add the new web in twiki/data/wikiwebs.inc (web specific links on top) and twiki/data/wikiwebtable.inc (table of all webs at the end of the WebHome topics).
Added:
>
>

    • In case you want usage statistics for this web: Copy file WebStatistics.txt from the twiki/data/Main directory to the new data directory. Edit topic WebStatistics and delete old usage entries.
Added:
>
>

-rwxr--r-- 1 twiki t5 1811 Feb 4 12:15 geturl

Added:
>
>

-rw-r-xr-x 1 twiki t5 9774 Feb 4 12:26 statistics -rwxr-xr-x 1 twiki t5 509 Feb 7 18:55 testenv

Added:
>
>

-rw-r-xr-x 1 twiki t5 5127 Feb 4 11:37 wikisearch.pm

Added:
>
>

-rw-r--r-- 1 nobody 65535 4282 Feb 4 15:08 WebStatistics.txt -r--r--r-- 1 nobody 65535 4471 Feb 4 15:08 WebStatistics.txt,v

Added:
>
>

-- PeterThoeny - 04 Feb 2000


 <<O>>  Difference Topic TWikiDocumentation (r1.8 - 03 Feb 2000 - PeterThoeny)
Changed:
<
<

  • Optional: If you are on a public server and you would like to authenticate users you need to rename file .htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. Consult the HTTP server documentation for details.
>
>

  • Optional: If you are on a public server and you would like to authenticate users you need to rename file .htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. Consult the HTTP server documentation for details, an example site for Apache is at http://info.mcs.kent.edu/system/web_help/htaccess/ . Note: In case .htaccess does not have any effect you need to enable it: Add "AllowOverride All" to the Directory section of access.conf for your twiki/bin directory.
Changed:
<
<

    • Use a topic name consisting of characters A..Z , a..z but not in WikiNotation.
>
>

    • Use a name for the web consisting of characters A..Z , a..z but not in WikiNotation.
Changed:
<
<

    • Copy the files TWikiUsers?.txt, WebHome.txt, WebNotify.txt, WebSearch.txt, webcolor.inc, and weblist.inc from the twiki/data/Main directory to the new data directory.
    • Make changes to webcolor.inc (unique color for web), and possibly also weblist.inc (web specific links on top).
    • In case you need a web specific copyright notice (at the bottom), copy file webcopyright.inc from the twiki/data directory to the new data directory, and customize it.
>
>

    • Copy the files WebHome.txt , WebNotify.txt , WebSearch.txt , webcolor.inc and weblist.inc from the twiki/data/Main directory to the new data directory.
    • Change webcolor.inc to a color of your taste. The number represents the unique color for the web (consult an HTML book for colors.) Note: The file must not have a new line, just the number without a return.
    • Customize weblist.inc (web specific links on top) if needed.
    • Add the new web in twiki/data/wikiwebs.inc (web specific links on top) and twiki/data/wikiwebtable.inc (table of all webs at the end of the WbHome? topics).
    • In case you need a web specific copyright notice (at the bottom), copy file webcopyright.inc from the twiki/data directory to the new data directory, and customize it.
Changed:
<
<

    • If you want to use a category table, copy the three files twikicatitems.tmpl, twikicatedit.tmpl and twikicatview.tmpl from the twiki/templates/Know directory to the new templates directory, and customize it. The TWiki Category Table section has more.
>
>

    • If you want to use a category table, copy the three files twikicatitems.tmpl , twikicatedit.tmpl and twikicatview.tmpl from the twiki/templates/Know directory to the new templates directory, and customize it. The TWiki Category Table section has more.
Added:
>
>

-- PeterThoeny - 02 Feb 2000


 <<O>>  Difference Topic TWikiDocumentation (r1.7 - 15 Jan 2000 - PeterThoeny)
Added:
>
>

Note: It is possible to force the values of a category table when creating a new topic. This is useful to create new topics using a form for the topic name. The default values of the category table can be specified as hidden fields if needed, i.e. <input type="hidden" name="someCategory" value="someValue">

Example (edit this page to see the source) :

  • New PublicFAQ? topic:
Changed:
<
<

    • Create a new data directory under twiki/data .
>
>

    • Create a new data directory under twiki/data and check the file permission of the directory.
Added:
>
>

-- PeterThoeny - 14 Jan 2000


 <<O>>  Difference Topic TWikiDocumentation (r1.6 - 30 Sep 1999 - PeterThoeny)
Added:
>
>

Note: These installation notes assume user nobody for all files manupulated by the cgi scripts (executed by the web server), and user twiki for all other files. You need to replace user nobody with an other user in case the web server executes the script with a different user ( default for Debian is www-data ). Also, you can substitute user twiki with your own user name.

Added:
>
>

  • Note in case cgi user is not nobody : The *,v RCS repository files delivered with the installation package are locked by user nobody . In case the user is different (e.g. www-data ), it is not possible to check in files, this has the effect that the topic version number does not increase when saving a topic. In this case you need to unlock all repository files and lock them as user www-data , or simply delete all the repository files.
Changed:
<
<

For debugging reasons, here are contents of directories with file permissions:

>
>

Here are contents of directories with file permissions. Please note that this is for debugging reasons only and does not exactly reflect the distribution:

Deleted:
<
<

drwxrwxrwx 6 twiki t5 512 Nov 6 03:13 data drwxr-xr-x 6 twiki t5 512 Nov 4 20:34 templates

Changed:
<
<

-rwxrwxrwx 1 twiki t5 3752 Mar 27 02:21 attach -rwxr-xr-x 1 twiki t5 2810 Oct 21 18:51 changes -rwxrwxrwx 1 twiki t5 1244 Mar 27 02:21 delete

>
>

-rw-r-xr-x 1 twiki t5 3752 Mar 27 02:21 attach -rw-r-xr-x 1 twiki t5 2810 Oct 21 18:51 changes -rw-r-xr-x 1 twiki t5 1244 Mar 27 02:21 delete

Changed:
<
<

-rwxr-xr-x 1 twiki t5 3174 Oct 21 18:51 search -rwxrwxrwx 1 twiki t5 6696 Mar 27 02:22 upload

>
>

-rw-r-xr-x 1 twiki t5 3174 Oct 21 18:51 search -rw-r-xr-x 1 twiki t5 6696 Mar 27 02:22 upload

Changed:
<
<

-rwxrwxrwx 1 twiki t5 1538 Mar 27 02:22 viewfile

>
>

-rw-r-xr-x 1 twiki t5 1538 Mar 27 02:22 viewfile

Changed:
<
<

-rw-rw-rw- 1 twiki t5 7 Oct 21 18:52 webcolor.inc -rw-rw-rw- 1 twiki t5 278 May 20 17:42 webcopyright.inc -rw-rw-rw- 1 twiki t5 402 Oct 26 07:45 weblist.inc

>
>

-rw-r--r-- 1 twiki t5 7 Oct 21 18:52 webcolor.inc -rw-r--r-- 1 twiki t5 278 May 20 17:42 webcopyright.inc -rw-r--r-- 1 twiki t5 402 Oct 26 07:45 weblist.inc

Added:
>
>

-- PeterThoeny - 29 Sep 1999


 <<O>>  Difference Topic TWikiDocumentation (r1.5 - 02 Sep 1999 - PeterThoeny)
Changed:
<
<

If you want to use a Category Table in a TWiki web you need to have the following three files in the wiki/bin/templates/{Yourweb} directory:

>
>

If you want to use a Category Table in a TWiki web you need to have the following three files in the twiki/templates/{Yourweb} directory:

Deleted:
<
<

(under construction)

Changed:
<
<

TWiki is written in PERL, but it uses many shell command. The current implementation runs only on a Unix machine. RCS for revision control must be installed on the system.

>
>

TWiki is written in PERL 5, but it uses also many shell command. The current implementation runs only on a Unix machine. RCS for revision control must be installed on the system.

Changed:
<
<

Files

>
>

Directories

Changed:
<
<

.htaccess
changes
debug.txt
edit
error401.html
mailnotify      automatic email notification, called by a cron job
preview         preview topic, Perl script
save
search
view
wiki.pm
wikicfg.pm
>
>

Directory: Used for:
twiki/bin TWiki PERL scripts
twiki/pub Public files (FileAttachments, images)
twiki/data source text
twiki/templates HTML templates, used by TWiki scripts

Files in twiki/bin

File: Used for:
.htaccess.txt Authentication. Rename to .htaccess and customize if used
attach Script that shows the attach file page (FileAttachment)
changes Script that shows recent changes
delete (not used yet)
edit Script to edit a topic
mailnotify Script called by cron job to notify users of changes
oops Script that shows a OK or oops dialog
preview Script to preview topic after edit
rdiff Script to see differences of topics
register Script to register new users
save Script that saves a topic, called by preview
search Script that displays search results
upload Script that does file upload (FileAttachment)
view Script to view a topic ( the script )
viewfile Script to view an file attachment
wiki.pm main TWiki library
wikicfg.pm for initialization and configuration, used by wiki.pm
Changed:
<
<

  • Set the file permission of all files below twiki/bin/data to 666 ( -rw-rw-rw- ).
  • Set the file permission of the twiki/bin/data directory and all its subdirectories to 777 ( drwxrwxrwx ).
>
>

  • Set the file permission of all files below twiki/data to 666 ( -rw-rw-rw- ).
  • Set the file permission of the twiki/data directory and all its subdirectories to 777 ( drwxrwxrwx ).
Changed:
<
<

  • Security issue: Directories twiki/bin/data , twiki/bin/templates and all its subdirectories should be set so that they are not visible as a URL. (Alternatively, move the directries to a place where they are not visible, and change the variables in twiki/bin/wikicfg.pm accordingly)
>
>

  • Security issue: Directories twiki/data , twiki/templates and all its subdirectories should be set so that they are not visible as a URL. (Alternatively, move the directries to a place where they are not visible, and change the variables in twiki/bin/wikicfg.pm accordingly)
Changed:
<
<

    • Create a new template directory under twiki/bin/templates .
    • Create a new data directory under twiki/bin/data .
    • Copy the files TWikiUsers?.txt, WebHome.txt, WebNotify.txt, WebSearch.txt, webcolor.inc, and weblist.inc from the twiki/bin/data/Main directory to the new data directory.
>
>

    • Create a new template directory under twiki/templates .
    • Create a new data directory under twiki/data .
    • Copy the files TWikiUsers?.txt, WebHome.txt, WebNotify.txt, WebSearch.txt, webcolor.inc, and weblist.inc from the twiki/data/Main directory to the new data directory.
Changed:
<
<

    • In case you need a web specific copyright notice (at the bottom), copy file webcopyright.inc from the twiki/bin/data directory to the new data directory, and customize it.
    • If needed, create customized templates in the new templates directory. (Non existing templates are inherited from twiki/bin/templates )
    • If you want to use a category table, copy the three files twikicatitems.tmpl, twikicatedit.tmpl and twikicatview.tmpl from the twiki/bin/templates/Know directory to the new templates directory, and customize it. The TWiki Category Table section has more.
>
>

    • In case you need a web specific copyright notice (at the bottom), copy file webcopyright.inc from the twiki/data directory to the new data directory, and customize it.
    • If needed, create customized templates in the new templates directory. (Non existing templates are inherited from twiki/templates )
    • If you want to use a category table, copy the three files twikicatitems.tmpl, twikicatedit.tmpl and twikicatview.tmpl from the twiki/templates/Know directory to the new templates directory, and customize it. The TWiki Category Table section has more.
Deleted:
<
<

-rw-rw-rw- 1 twiki t5 1091 Nov 6 04:15 debug.txt

Changed:
<
<

directory twiki/bin/templates/ :

>
>

directory twiki/templates/ :

Changed:
<
<

directory twiki/bin/templates/Main :

>
>

directory twiki/templates/Main :

Changed:
<
<

directory twiki/bin/templates/Know (has a TWiki Category Table) :

>
>

directory twiki/templates/Know (has a TWiki Category Table) :

Changed:
<
<

directory twiki/bin/data/ :

>
>

directory twiki/data/ :

Added:
>
>

-rw-rw-rw- 1 twiki t5 1091 Nov 6 04:15 debug.txt

Changed:
<
<

part of directory twiki/bin/data/Main :

>
>

part of directory twiki/data/Main :

Added:
>
>

-- PeterThoeny - 01 Sep 1999


 <<O>>  Difference Topic TWikiDocumentation (r1.4 - 03 Aug 1999 - PeterThoeny)
Added:
>
>

  • Optional: If you are on a public server and you would like to authenticate users you need to rename file .htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. Consult the HTTP server documentation for details.
Changed:
<
<

drwxr-xr-x 6 twiki t5 512 Nov 6 03:13 data

>
>

drwxrwxrwx 6 twiki t5 512 Nov 6 03:13 data

Deleted:
<
<

-rw-r--r-- 1 twiki t5 1097 Oct 21 18:51 error401.html

Added:
>
>

-rw-r-xr-x 1 twiki t5 6249 Aug 3 04:34 register

Added:
>
>

-rw-r--r-- 1 twiki t5 1331 Oct 23 20:29 oopslocked.tmpl -rw-r--r-- 1 twiki t5 1026 Aug 03 08:21 oopsregexist.tmpl -rw-r--r-- 1 twiki t5 935 Aug 03 08:23 oopsregpasswd.tmpl -rw-r--r-- 1 twiki t5 924 Aug 03 08:26 oopsregrequ.tmpl -rw-r--r-- 1 twiki t5 931 Aug 03 08:29 oopsregwiki.tmpl

Added:
>
>

-rw-r--r-- 1 twiki t5 263 Aug 3 02:44 register.tmpl

Added:
>
>

-rw-r--r-- 1 nobody 65535 53 Aug 03 08:31 .htpasswd

Added:
>
>

-rw-r--r-- 1 nobody 65535 3991 Jul 22 04:33 FileAttachment.txt -r--r--r-- 1 nobody 65535 4173 Jul 22 04:33 FileAttachment.txt,v -rw-r--r-- 1 nobody 65535 6773 Aug 5 16:18 TWikiRegistration.txt -r--r--r-- 1 nobody 65535 6960 Aug 5 16:18 TWikiRegistration.txt,v


 <<O>>  Difference Topic TWikiDocumentation (r1.3 - 16 Jul 1999 - Main.thoeny)
Changed:
<
<

    • Create a new template directory and copy all files from the twiki/bin/templates/Main directory to the new directory.
    • Create a new data directory and copy the files .changes, .mailnotify, TWikiUsers?.txt, WebHome.txt, WebNotify.txt, WebSearch.txt, webcolor.inc, webcopyright.inc and weblist.inc from the twiki/bin/data/Main directory to the new directory.
    • Make changes to webcolor.inc (unique color for web), possibly also webcopyright.inc (copyright at the bottom) and weblist.inc (web specific links on top).
    • If you want to use a category table, create the three files twikicatitems.tmpl, twikicatedit.tmpl and twikicatview.tmpl described in the TWiki Category Table section.
>
>

    • Create a new template directory under twiki/bin/templates .
    • Create a new data directory under twiki/bin/data .
    • Copy the files TWikiUsers?.txt, WebHome.txt, WebNotify.txt, WebSearch.txt, webcolor.inc, and weblist.inc from the twiki/bin/data/Main directory to the new data directory.
    • Make changes to webcolor.inc (unique color for web), and possibly also weblist.inc (web specific links on top).
    • In case you need a web specific copyright notice (at the bottom), copy file webcopyright.inc from the twiki/bin/data directory to the new data directory, and customize it.
    • If needed, create customized templates in the new templates directory. (Non existing templates are inherited from twiki/bin/templates )
    • If you want to use a category table, copy the three files twikicatitems.tmpl, twikicatedit.tmpl and twikicatview.tmpl from the twiki/bin/templates/Know directory to the new templates directory, and customize it. The TWiki Category Table section has more.
Added:
>
>

-rw-r--r-- 1 twiki t5 2356 Oct 22 00:56 webcopyright.inc


 <<O>>  Difference Topic TWikiDocumentation (r1.2 - 23 Jun 1999 - Main.thoeny)
Added:
>
>

wikicfg.pm

Changed:
<
<

  • Edit the file wiki.pm and set the variables at the beginning of the file to your needs.
  • Make sure RCS is installed. In case RCS is not in the path environment variable, add it to path . Alternatively, add the full path name to the rcs, ci, co, rlog, rcsdiff commands in the wiki.pm variables.
>
>

  • Edit the file twiki/bin/wikicfg.pm and set the variables at the beginning of the file to your needs.
  • Make sure RCS is installed. In case RCS is not in the path environment variable, add it to path . Alternatively, add the full path name to the rcs, ci, co, rlog, rcsdiff commands in the variables of twiki/bin/wikicfg.pm .
Added:
>
>

  • Security issue: Directories twiki/bin/data , twiki/bin/templates and all its subdirectories should be set so that they are not visible as a URL. (Alternatively, move the directries to a place where they are not visible, and change the variables in twiki/bin/wikicfg.pm accordingly)
  • Optional: You can add new rendering rules or new %variables%. To insure an easy upgrade of TWiki it is recommended to do this customization in twiki/bin/wikicfg.pm , not twiki/bin/wiki.pm .
Added:
>
>

-rw-r-xr-x 1 twiki t5 3945 Jun 23 01:24 wikicfg.pm

Added:
>
>

-- PeterThoeny - 23 Jun 1999


 <<O>>  Difference Topic TWikiDocumentation (r1.1 - 15 Jun 1999 - Main.thoeny)
Added:
>
>

Documentation of the TWiki Implementation

  • (1) Login Username vs. Wiki Username
  • (2) Wiki Variables
  • (3) Notification of Changes by Email
  • (4) TWiki Category Table
  • (5) Implementation Notes
  • (6) Installation Notes

Related Topics: TWikiHistory, TWikiPlannedFeatures, TWikiEnhancementRequests.


(1) Login Username vs. Wiki Username

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

Note: When you write a WikiName of a user (your own or somebody else's) be sure to specify the Main web in front of the Wiki user name, e.g. write it as Main.wikiUsername. This assures that the name will be linked automatically to the TWiki.Main web, even if the text is written in a different Wiki web.

TWiki can map the Intranet username to the Wiki username automatically, provided that the Login username and Wiki username pair has been entered in the TWikiUsers topic.


(2) Wiki Variables

TWiki Variables

Text strings expanded on the fly to display data or system info

Overview

TWikiVariables are text strings - %VARIABLE% - that expand into content whenever a page is opened. Variables are replaced by their actual values: stored data, or system info (like the date, or the current user). There are predefined variables, and Preference variables that you set. You can also define custom variables, with new names and values.

Predefined Variables

Most predefined variables return values that were either defined when TWiki was installed, or taken from server info (like current username, or date and time). Many of the variables let you control how the formatted results appear.

Tharsis expands the following variables (enclosed in % percent signs):

Variable: Expanded to:
%WIKIHOMEURL% The base script URL of Tharsis, is the link of the Home icon in the upper left corner, is http://tharsis-gate.org/twiki
%SCRIPTURL% The script URL of Tharsis, is http://www.tharsis-gate.org/twiki/bin
%SCRIPTURLPATH% The path of the script URL of Tharsis, is /twiki/bin
%SCRIPTSUFFIX% The script suffix, ex: .pl, .cgi is
%PUBURL% The public URL of TWiki, is http://www.tharsis-gate.org/twiki/pub
%PUBURLPATH% The path of the public URL of Tharsis, is /twiki/pub
%ATTACHURL% The attachment URL of the current topic, is http://www.tharsis-gate.org/twiki/pub/TWiki/TWikiVariables
Example: If you attach a file you can refer to it as %ATTACHURL%/image.gif
%ATTACHURLPATH% The path of the attachment URL of the current topic, is /twiki/pub/TWiki/TWikiVariables
%URLPARAM{"name"}% Returns the value of a URL parameter. Ex: %URLPARAM{"skin"}% returns print for a .../view/TWiki/TWikiVariables?skin=print URL. Is
%WIKITOOLNAME% Name of wiki tool, is Tharsis
%WIKIVERSION% Wiki tool version is 01 Dec 2001
%USERNAME% Your login username is guest
%WIKINAME% Your Wiki username. Same as %USERNAME% if not defined in the TWikiUsers topic. Is guest
%WIKIUSERNAME% Your %WIKINAME% including the Main web name. Usefull for signatures. Is Main.guest
%MAINWEB% The Main web containing TWikiUsers, OfficeLocations? and TWikiGroups. Is Main
%TWIKIWEB% The web containing all documentation and configuration of Tharsis is TWiki
%WEB% The current web is TWiki
%BASEWEB% The web name where the includes started, e.g. the web of the first topic of nested includes. Same as %WEB% in case there is no include.
%INCLUDINGWEB% The web name of the topic that includes the current topic. Same as %WEB% in case there is no include.
%HOMETOPIC% The home topic in each web. Is WebHome
%NOTIFYTOPIC% The notify topic in each web. Is WebNotify
%WIKIUSERSTOPIC% The index topic of all registered users. Is TWikiUsers
%WIKIPREFSTOPIC% The web preferences topic. Is TWikiPreferences
%WEBPREFSTOPIC% The web preferences topic. Is WebPreferences
%STATISTICSTOPIC% The web statistics topic. Is WebStatistics
%TOPIC% The current topic name, is TWikiVariables
%BASETOPIC% The name of the topic where the includes started, e.g. the first topic of nested includes. Same as %TOPIC% in case there is no include.
%INCLUDINGTOPIC% The name of the topic that includes the current topic. Same as %TOPIC% in case there is no include.
%SPACEDTOPIC% The current topic name with added spaces, for regular expression search of Ref-By, is TWiki%20*Variables
%TOPICLIST{"format"}% Topic index of a web. The "format" defines the format of one topic item. It may include variables: The $name variable gets expanded to the topic name; the $web variable gets expanded to the name of the web. Parameters are format, separator and web:
Parameter: Description: Default:
"format" Format of one line, may include $name and $web variables "$name"
format="format" (Alternative to above) "$name"
separator=", " line separator "\n" (new line)
web="Name" Name of web Current web
Examples:
%TOPICLIST{"   * $web.$name"}% creates a bullet list of all topics.
%TOPICLIST{separator=", "}% creates a comma separated list of all topics.
%TOPICLIST{" <option>$name</option>"}% creates an option list (for drop down menus).
%WEBLIST{"format"}% Web index, e.g. list of all webs. Hidden webs are excluded, e.g. webs with a NOSEARCHALL=on preference variable. The "format" defines the format of one web item. The $name variable gets expanded to the name of the web, $qname gets expanded to double quoted name, $marker to marker where web matches selection. Parameters are format, separator and web:
Parameter: Description: Default:
"format" Format of one line, may include $name variable "$name"
format="format" (Alternative to above) "$name"
separator=", " line separator "\n" (new line)
webs="public" comma sep list of Web, public expands to all non-hidden "public"
marker="selected" Text for $marker where item matches selection, otherwise equals "" "selected"
selection="%WEB%" Current value to be selected in list section="%WEB%"
Examples:
%WEBLIST{"   * [[$name.WebHome]]"}% creates a bullet list of all webs.
%WEBLIST{"" webs="Trash,public" selection="TWiki" separator=" "}% Dropdown of all public Webs + Trash Web, current Web highlighted.
%GMTIME% GM time, is Thu Oct 17 01:20:10 2019
%GMTIME{"format"}% Formatted GM time based on time variables.
Variable: Unit: Example
$seconds seconds 59
$minutes minutes 59
$hours hours 23
$day day of month 31
$month month in ISO format Dec
$mo 2 digit month 12
$year 4 digit year 1999
$ye 2 digit year 99
Variables can be shortened to 3 characters. Example:
%GMTIME{"$day $month, $year - $hour:$min:$sec"}% is
17 Oct, 2019 - 01:20:10
%SERVERTIME% Server time, is Thu Oct 17 12:20:10 2019
%SERVERTIME{"format"}% Formatted server time.
Example: %SERVERTIME{"$hou:$min"}% is 12:20
%HTTP_HOST% HTTP_HOST environment variable, is www.tharsis-gate.org
%REMOTE_ADDR% REMOTE_ADDR environment variable, is 35.175.191.168
%REMOTE_PORT% REMOTE_PORT environment variable, is 59676
%REMOTE_USER% REMOTE_USER environment variable, is
%INCLUDE{"page" ...}% Server side include to IncludeTopicsAndWebPages. Parameters are page name, and an optional pattern="(reg-exp)". The page name is:
"SomeTopic" The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}%
"Web.Topic" A topic in another web, i.e. %INCLUDE{"TWiki.TWikiWebsTable"}%
"http://..." A full qualified URL, i.e. %INCLUDE{"http://twiki.org/"}%
%STARTINCLUDE% If present in included topic, start to include text from this location up to the end, or up to the location of the %STOPINCLUDE% variable. A normal view of the topic shows everyting exept the %STARTINCLUDE% variable itself.
%STOPINCLUDE% If present in included topic, stop to include text at this location and ignore the remaining text. A normal view of the topic shows everyting exept the %STOPINCLUDE% variable itself.
%TOC% Table of Contents of current topic.
%TOC{"SomeTopic" ...}% Table of Contents. Shows a TOC that is generated automatically based on headings of a topic. Headings in WikiSyntax ("---++ text") and HTML ("<h2>text<h2>") are taken into account. (But not "<H2>text</H2>", which can be used to exclude a heading from the TOC.) Parameters are topic name, web and depth:
Parameter: Description: Default:
"TopicName" topic name Current topic
web="Name" Name of web Current web
depth="2" Limit depth of headings shown in TOC 6
Examples: %TOC{depth="2"}%, %TOC{"TWikiDocumentation" web="TWiki"}%
%SEARCH{"text" ...}% Inline search, shows a search result embedded in a topic. Parameters are the search term, web, scope, order and many more: [1]
Parameter: Description: Default:
"text" Search term. (Is a regular expression or literal, depending on the regex parameter) required
search="text" (Alternative to above) N/A
web="Name"
web="Main Know"
web="all"
Wiki web to search: A web, a list of webs separated by whitespace, or all webs. [2] Current web
scope="topic"
scope="text"
Search topic name (title) or in the text (body) of the topic Topic text (body)
order="topic"
order="modified"
order="editby"
Sort the results of search by the topic names, last modified time, or last editor Sort by topic name
limit="all"
limit="16"
Limit the number of results returned All results
regex="on" RegularExpression search Literal search
reverse="on" Reverse the direction of the search Ascending search
casesensitive="on" Case sensitive search Ignore case
nosummary="on" Show topic title only Show topic summary
bookview="on" BookView search, e.g. show complete topic text Show topic summary
nosearch="on" Suppress search string Show search string
noheader="on" Suppress search header
Topics: Changed: By:
Show search header
nototal="on" Do not show number of topics found Show number
format="..." Flexible custom result formatting: see FormattedSearch for usage Results in table
Example: %SEARCH{"wiki" web="Main" scope="topic"}%
%METASEARCH{...}% Special search of meta data
Parameter: Description: Default:
type="topicmoved" What sort of search is required?
"topicmoved" if search for a topic that may have been moved
"parent" if searcing for topics that have a specific parent i.e. its children
required
web="%WEB%" Wiki web to search: A web, a list of webs separated by whitespace, or all webs. required
topic="%TOPIC%" The topic the search relates to required
title="Title" Text the is pre-pended to any search results required
Example: %METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%, you may want to use this in WebTopicViewTemplate and WebTopicNonWikiTemplate
%METASEARCH{type="parent" web="%WEB%" topic="%TOPIC%" title="Children: "}%
%VAR{"NAME" web="Web"}% Get a preference value from a web other then the current one. Example: To get %WEBBGCOLOR% of the Main web write %VAR{"WEBBGCOLOR" web="Main"}%, is #FFFFC0

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

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

Preferences Variables

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

Variable: Level: What:
%WIKIWEBMASTER% SL Webmaster email address (sender of email notifications) , is fantom@tharsis.dyndns.org
%WIKIWEBLIST% SL List of Tharsis webs (in upper right corner of topics)
%WEBTOPICLIST% WL Common links of web (second line of topics)
%WEBCOPYRIGHT% SL , WL Copyright notice (bottom right corner of topics)
%WEBBGCOLOR% WL Background color of web
%NOSEARCHALL% WL Exclude web from a web="all" search (set variable to on for hidden webs)
%NEWTOPICBGCOLOR% SL , UL Background color of non existing topic. ( UL needs authentication for topic views )
%NEWTOPICFONTCOLOR% SL , UL Font color of non existing topic. ( UL needs authentication for topic views )
%EDITBOXWIDTH% SL , UL Horizontal size of edit box, is 70
%EDITBOXHEIGHT% SL , UL Vertical size of edit box, is 15
%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: checked="checked"
%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:
%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:
%HTTP_EQUIV_ON_VIEW% SL http-equiv meta tags for view, rdiff, attach, search* scripts.
%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.
%DENYWEBCHANGE% WL List of users and groups who are not allowed to change topics in the Tharsis web. (More in TWikiAccessControl)
%ALLOWWEBCHANGE% WL List of users and groups who are allowed to change topics in the Tharsis web. (More in TWikiAccessControl)
%DENYTOPICCHANGE% (any topic) List of users and groups who are not allowed to change the current topic. (More in TWikiAccessControl)
%ALLOWTOPICCHANGE% (any topic) List of users and groups who are allowed to change the current topic. (More in TWikiAccessControl)
%DENYWEBRENAME% WL List of users and groups who are not allowed to rename topics in the Tharsis web. (More in TWikiAccessControl)
%ALLOWWEBRENAME% WL List of users and groups who are allowed to rename topics in the Tharsis web. (More in TWikiAccessControl)
%DENYTOPICRENAME% (any topic) List of users and groups who are not allowed to rename the current topic. (More in TWikiAccessControl)
%ALLOWTOPICRENAME% (any topic) List of users and groups who are allowed to rename the current topic. (More in TWikiAccessControl)
%FINALPREFERENCES% SL , WL List of preferences that are not allowed to be overridden by next level preferences

Setting Preferences

  • The syntax for Preferences variables is the same anywhere in TWiki. In Edit mode, from the start of a new line:
    [6 spaces] * [space] Set [space] VARIABLENAME [space] = [value]
    Example:
    • Set VARIABLENAME = value

Creating Custom Variables

  • You can add your own preference variables for an entire site, a single web, or a single topic, using the standard syntax. Whatever you include in your variable will be expanded on display, and treated exactly as if it had been written out. So you can place formatted text, page links, image paths.

Example: Create a custom logo variable
  • To place a logo anywhere in a web by typing %MYLOGO%, simply define the variable on the web's WebPreferences page. You also have to upload logo.gif - this can be done by attaching a file to LogoTopic (any topic name you choose):
    • Set MYLOGO = %PUBURL%/%MAINWEB%/LogoTopic/logo.gif

-- PeterThoeny - 13 Sep 2001
-- MikeMannix - 30 Nov 2001


(3) Notification of Changes by Email

Each TWiki web does an automatic email notification of recent changes. Users can subscribe / unsubscribe themselves in WebNotify of each TWiki web. The Perl script mailnotify is called by a deamon once every 60 minutes. For each Twiki web mailnotify is sending an automated email to subscribed users in case some topics changed within these 60 minutes.

Implementation note: Edit the cron table so that mailnotify is called every 60 minutes. Please consult man crontab of how to modify the table that schedules program execution at certain intervals. Example:

% crontab -e
15,45 * * * * (cd ~twiki/public_html/bin; ./mailnotify)
The above line will call mailnotify at 15 minutes and 45 minutes passed every hour.


(4) TWiki Category Table

It is possible to add a category table to a TWiki web. This permits storing and searching for more structured information. Editing a topic shows a HTML form with the usual text area and a table with selectors, checkboxes, radio buttons and text fields. The category table is shown at the end of a topic. The format of the category table can be defined per TWiki web.

If you want to use a Category Table in a TWiki web you need to have the following three files in the wiki/bin/templates/{Yourweb} directory:

  • twikicatitems.tmpl : Defines the items in the table
  • twikicatedit.tmpl : Defines the look of the table when editing a topic
  • twikicatview.tmpl : Defines the look of the table when viewing a topic

Format of category definition template twikicatitems.tmpl

Valid lines:

select|{name}|{selSize}|{val1}|{val2}|{val3}...
checkbox|{name}|{checkFlag}|{itemsPerLine}|{val1}|{val2}|{val3}...
radio|{name}|{itemsPerLine}|{val1}|{val2}|{val3}...
text|{name}|{charSize}
# comments start with a # character

Explanation:

  {name}             name of tag
  {selSize}          vertical size of SELECT tag
  {val1}|{val2}...   values
  {checkFlag}        set to true for [Set] [Clear] buttons, else set to false
  {itemsPerLine}     input items per line before wrap around, 0 if no wrap around
  {charSize}         number of characters for text fields

Remark: Line radio|UseCategory|0|Yes|No has a special meaning. If present, it is possible to choose in "edit" if the category table is included in the topic or not

Example file:

radio|UseCategory|0|Yes|No, delete this category table
select|TopicClassification|1|Select one...|NoDisclosure|PublicSupported|PublicFAQ
checkbox|OperatingSystem|true|5|OsSolaris|OsSunOS|OsHPUX|OsWin
text|OsVersion|16

Format of twikicatedit.tmpl and twikicatview.tmpl

Use the example below and customize if needed. twikicatedit.tmpl and twikicatview.tmpl can be identical, but they do not have to be.

Attention: <!--TWikiCat--> is needed at the beginning and end as markers. Do not delete them!

Example:

<!--TWikiCat--> <h4> TWikiCategory </h4>
<table border="2" cellspacing="1" cellpadding="1">
%REPEAT%<tr>
<td valign="top" align="right"> %CATNAME%:  <br>%CATMODIFIER%</td><td>  %CATVALUE% </td>
</tr>%REPEAT%
</table><!--TWikiCat-->

Above template files will result in the following category table when viewing a topic:

TWikiCategory

TopicClassification:
PublicFAQ
OperatingSystem:
OsSolaris
OsVersion:
2.5 

Above template files will result in the following table when editing a topic:

TWikiCategory

UseCategory :
Yes    No, delete this category table   
TopicClassification :
OperatingSystem :
   
OsSolaris    OsSunOS    OsHPUX    OsWin   
OsVersion :


(5) Implementation Notes

(under construction)

Platform

TWiki is written in PERL, but it uses many shell command. The current implementation runs only on a Unix machine. RCS for revision control must be installed on the system.

Files

.htaccess
changes
debug.txt
edit
error401.html
mailnotify      automatic email notification, called by a cron job
preview         preview topic, Perl script
save
search
view
wiki.pm


(6) Installation Notes

These installation steps use Apache web server on Linux as an example. TWiki should run on other web servers and Unix systems as well.

  • Request the TWiki distribution (in Unix ZIP format) from http://www.mindspring.net/~peterthoeny/twiki/index.html .
  • Create directory /home/httpd/twiki and unzip the TWiki distribution to this directory.
  • The twiki/bin directory of TWiki must be set as a cgi-bin directory. Add /home/httpd/twiki/bin to /etc/httpd/conf/access.conf with only ExecCGI option.
  • The twiki/pub directory of TWiki must be set so that it is visible as a URL. Add /home/httpd/twiki/pub to /etc/httpd/conf/access.conf with normal access options (copy from /home/httpd/html).
  • Now add Alias for /twiki/pub and ScriptAlias for /twiki/bin to /etc/httpd/conf/srm-conf .
  • Restart Apache by /etc/rc.d/rc5.d/S85httpd restart .
  • Test if the twiki/bin directory is cgi-enabled: Enter the URL of that directory into your browser (http://your.domain.com/twiki/bin). It is not set correctly as cgi-bin in case you get something like "Index of /twiki/bin" . It is OK if you get a message like "Forbidden. You don't have permission to access /twiki/bin/ on this server." .
  • Make sure PERL and the PERL CGI library is installed on your system. Default location of PERL executable is /usr/bin/perl . In case PERL is installed in a different location, the first line of all perl scripts in the twiki/bin directory need to be changed (alternatively you can create a symbolic link from /usr/bin/perl ).
  • To be able to edit the perl scripts and .tmpl files it is necessary to chown and chgrp -R twiki so all the files have the owner you want.
  • The scripts execute as nobody . Set the file permission of all Perl scripts in the twiki/bin directory as executable to -rw-r-xr-x .
  • Set the file permission of all files below twiki/bin/data to 666 ( -rw-rw-rw- ).
  • Set the file permission of the twiki/bin/data directory and all its subdirectories to 777 ( drwxrwxrwx ).
  • Set the file permission of the twiki/pub directory to 777 ( drwxrwxrwx ).
  • Edit the file wiki.pm and set the variables at the beginning of the file to your needs.
  • Make sure RCS is installed. In case RCS is not in the path environment variable, add it to path . Alternatively, add the full path name to the rcs, ci, co, rlog, rcsdiff commands in the wiki.pm variables.
  • Point your browser at http://your.domain.com/twiki/bin/view and start wiki-ing away!

  • To create a new web:
    • Use a topic name consisting of characters A..Z , a..z but not in WikiNotation.
    • Create a new template directory and copy all files from the twiki/bin/templates/Main directory to the new directory.
    • Create a new data directory and copy the files .changes, .mailnotify, TWikiUsers?.txt, WebHome.txt, WebNotify.txt, WebSearch.txt, webcolor.inc, webcopyright.inc and weblist.inc from the twiki/bin/data/Main directory to the new directory.
    • Make changes to webcolor.inc (unique color for web), possibly also webcopyright.inc (copyright at the bottom) and weblist.inc (web specific links on top).
    • If you want to use a category table, create the three files twikicatitems.tmpl, twikicatedit.tmpl and twikicatview.tmpl described in the TWiki Category Table section.

For debugging reasons, here are contents of directories with file permissions:

directory twiki/bin :

drwxr-xr-x   5 twiki    t5            512 Nov 11 02:52 .
drwxr-xr-x   5 twiki    t5            512 Nov  6 02:57 ..
drwxr-xr-x   6 twiki    t5            512 Nov  6 03:13 data
drwxr-xr-x   6 twiki    t5            512 Nov  4 20:34 templates
-rw-r--r--   1 twiki    t5            430 Oct 21 18:51 .htaccess
-rwxrwxrwx   1 twiki    t5           3752 Mar 27 02:21 attach
-rwxr-xr-x   1 twiki    t5           2810 Oct 21 18:51 changes
-rw-rw-rw-   1 twiki    t5           1091 Nov  6 04:15 debug.txt
-rwxrwxrwx   1 twiki    t5           1244 Mar 27 02:21 delete
-rw-r-xr-x   1 twiki    t5           2589 Nov  6 03:05 edit
-rw-r--r--   1 twiki    t5           1097 Oct 21 18:51 error401.html
-rwxr-xr-x   1 twiki    t5           4614 Oct 21 18:52 mailnotify
-rw-r-xr-x   1 twiki    t5           1353 Oct 23 20:19 oops
-rw-r-xr-x   1 twiki    t5           2043 Nov  6 03:05 preview
-rw-r-xr-x   1 twiki    t5           6890 Nov 11 03:06 rdiff
-rw-r-xr-x   1 twiki    t5           1819 Nov  6 03:06 save
-rwxr-xr-x   1 twiki    t5           3174 Oct 21 18:51 search
-rwxrwxrwx   1 twiki    t5           6696 Mar 27 02:22 upload
-rw-r-xr-x   1 twiki    t5           3878 Nov 11 03:06 view
-rwxrwxrwx   1 twiki    t5           1538 Mar 27 02:22 viewfile
-rw-r-xr-x   1 twiki    t5          16169 Nov  7 01:43 wiki.pm

directory twiki/bin/templates/ :

drwxr-xr-x   6 twiki    t5            512 Nov  4 20:34 .
drwxr-xr-x   5 twiki    t5            512 Nov 11 02:52 ..
drwxr-xr-x   2 twiki    t5            512 Oct 23 20:57 Know
drwxr-xr-x   2 twiki    t5            512 Nov  4 20:35 Main
-rw-r--r--   1 twiki    t5           2232 Mar 27 02:03 attach.tmpl
-rw-r--r--   1 twiki    t5           1200 Mar 27 02:03 attachtable.tmpl
-rw-r--r--   1 twiki    t5           1751 Nov 11 02:41 changes.tmpl
-rw-r--r--   1 twiki    t5           1711 Nov  6 03:01 edit.tmpl
-rw-r--r--   1 twiki    t5            896 Oct 21 18:51 mailnotify.tmpl
-rw-r--r--   1 twiki    t5             25 Oct 21 18:51 notedited.tmpl
-rw-r--r--   1 twiki    t5             21 Oct 21 18:51 notext.tmpl
-rw-r--r--   1 twiki    t5            157 Oct 23 21:05 notwiki.tmpl
-rw-r--r--   1 twiki    t5            218 Oct 23 20:06 noweb.tmpl
-rw-r--r--   1 twiki    t5            279 Oct 23 20:29 oops.tmpl
-rw-r--r--   1 twiki    t5            833 Mar 27 02:03 oopsdel.tmpl
-rw-r--r--   1 twiki    t5            868 Mar 27 02:03 oopsupload.tmpl
-rw-r--r--   1 twiki    t5           2010 Nov  6 03:01 preview.tmpl
-rw-r--r--   1 twiki    t5           1501 Nov 12 22:56 rdiff.tmpl
-rw-r--r--   1 twiki    t5           1548 Oct 23 21:10 search.tmpl
-rw-r--r--   1 twiki    t5           1541 Oct 26 21:07 view.tmpl

directory twiki/bin/templates/Main :

drwxr-xr-x   2 twiki    t5            512 Nov  4 20:35 .
drwxr-xr-x   6 twiki    t5            512 Nov  4 20:34 ..
-rw-r--r--   1 twiki    t5           2328 Nov  6 03:03 edit.tmpl

directory twiki/bin/templates/Know (has a TWiki Category Table) :

drwxr-xr-x   2 twiki    t5            512 Nov  4 20:35 .
drwxr-xr-x   6 twiki    t5            512 Nov  4 20:34 ..
-rw-r--r--   1 twiki    t5            611 Dec  7 20:59 notedited.tmpl
-rw-r--r--   1 twiki    t5            210 Dec 24 23:22 twikicatedit.tmpl
-rw-r--r--   1 twiki    t5           1887 Jan  6 20:54 twikicatitems.tmpl
-rw-r--r--   1 twiki    t5            245 Dec 24 23:27 twikicatview.tmpl

directory twiki/bin/data/ :

drwxrwxrwx   6 twiki    t5            512 Nov 19 01:01 .
drwxr-xr-x   5 twiki    t5            512 Nov 11 02:52 ..
drwxrwxrwx   2 twiki    t5           9216 Nov 13 13:55 Know
drwxrwxrwx   2 twiki    t5           4608 Nov 15 21:42 Main
-rw-r--r--   1 nobody   65535        4153 Nov 19 01:01 log199810.txt
-rw-r--r--   1 nobody   65535        7189 Nov 19 01:01 log199811.txt
-rw-r--r--   1 twiki    t5            276 Oct 22 00:28 wikiwebs.inc
-rw-r--r--   1 twiki    t5           1484 Oct 22 01:11 wikiwebtable.inc

part of directory twiki/bin/data/Main :

drwxrwxrwx   2 twiki    t5           4608 Nov 19 00:56 .
drwxrwxrwx   6 twiki    t5            512 Nov 19 01:01 ..
-rw-rw-rw-   1 twiki    t5           5974 Nov 15 21:42 .changes
-rw-rw-rw-   1 twiki    t5              9 Nov 15 23:00 .mailnotify
-rw-r--r--   1 nobody   65535        1990 Nov  6 18:25 TWikiUsers.txt
-r--r--r--   1 nobody   65535        3045 Nov  6 18:25 TWikiUsers.txt,v
-rw-r--r--   1 nobody   65535        1181 Oct 29 20:54 WebHome.txt
-r--r--r--   1 nobody   65535        1537 Oct 29 20:54 WebHome.txt,v
-rw-r--r--   1 nobody   65535         454 Oct 21 18:52 WebNotify.txt
-r--r--r--   1 nobody   65535         638 Oct 27 02:45 WebNotify.txt,v
-rw-r--r--   1 nobody   65535        3653 Oct 21 18:52 WebSearch.txt
-r--r--r--   1 nobody   65535        3835 Oct 27 02:45 WebSearch.txt,v
-rw-rw-rw-   1 twiki    t5              7 Oct 21 18:52 webcolor.inc
-rw-rw-rw-   1 twiki    t5            278 May 20 17:42 webcopyright.inc
-rw-rw-rw-   1 twiki    t5            402 Oct 26 07:45 weblist.inc

directory twiki/pub/ :

drwxrwxrwx   4 twiki    t5           1024 Mar 27 02:58 .
drwxr-xr-x   4 twiki    t5           1024 Mar 27 02:08 ..
drwxrwxrwx   4 nobody   nobody       1024 Mar 27 03:54 Main
-rw-r--r--   1 twiki    t5           2877 Mar 27 02:27 wikiHome.gif
drwxr-xr-x   2 twiki    t5           1024 Mar 27 03:17 icn

directory twiki/pub/icn/ :

drwxr-xr-x   2 twiki    t5           1024 Mar 27 03:17 .
drwxrwxrwx   4 twiki    t5           1024 Mar 27 02:58 ..
-rw-r--r--   1 twiki    t5            801 Mar 27 03:02 _filetypes.txt
-rw-r--r--   1 twiki    t5            143 Mar 27 03:16 bat.gif
-rw-r--r--   1 twiki    t5            926 Mar 27 03:16 bmp.gif
-rw-r--r--   1 twiki    t5            141 Mar 27 03:16 c.gif
-rw-r--r--   1 twiki    t5            144 Mar 27 03:16 dll.gif
-rw-r--r--   1 twiki    t5            152 Mar 27 03:16 doc.gif
-rw-r--r--   1 twiki    t5            130 Mar 27 03:16 else.gif
-rw-r--r--   1 twiki    t5            876 Mar 27 03:16 exe.gif
-rw-r--r--   1 twiki    t5            147 Mar 27 03:16 fon.gif
-rw-r--r--   1 twiki    t5            142 Mar 27 03:16 h.gif
-rw-r--r--   1 twiki    t5            156 Mar 27 03:16 hlp.gif
-rw-r--r--   1 twiki    t5            186 Mar 27 03:16 html.gif
-rw-r--r--   1 twiki    t5            144 Mar 27 03:16 java.gif
-rw-r--r--   1 twiki    t5            148 Mar 27 03:16 mov.gif
-rw-r--r--   1 twiki    t5            150 Mar 27 03:16 pdf.gif
-rw-r--r--   1 twiki    t5            146 Mar 27 03:16 pl.gif
-rw-r--r--   1 twiki    t5            150 Mar 27 03:16 ppt.gif
-rw-r--r--   1 twiki    t5            148 Mar 27 03:16 ps.gif
-rw-r--r--   1 twiki    t5            148 Mar 27 03:16 py.gif
-rw-r--r--   1 twiki    t5            130 Mar 27 03:17 ram.gif
-rw-r--r--   1 twiki    t5            154 Mar 27 03:17 reg.gif
-rw-r--r--   1 twiki    t5            147 Mar 27 03:17 sh.gif
-rw-r--r--   1 twiki    t5            155 Mar 27 03:17 sniff.gif
-rw-r--r--   1 twiki    t5            149 Mar 27 03:17 ttf.gif
-rw-r--r--   1 twiki    t5            134 Mar 27 03:17 txt.gif
-rw-r--r--   1 twiki    t5            154 Mar 27 03:17 wav.gif
-rw-r--r--   1 twiki    t5            152 Mar 27 03:17 wri.gif
-rw-r--r--   1 twiki    t5            152 Mar 27 03:17 xls.gif
-rw-r--r--   1 twiki    t5            144 Mar 27 03:17 zip.gif

-- PeterThoeny - 22 Oct 1998
-- PeterThoeny - 18 Nov 1998
-- PeterThoeny - 11 Jan 1999
-- PeterThoeny - 20 Jan 1999
-- PeterThoeny - 06 Mar 1999
-- PeterThoeny - 27 Mar 1999
-- PeterThoeny - 02 Jun 1999
-- PeterThoeny - 14 Jun 1999


Topic TWikiDocumentation . { View | Diffs | r1.39 | > | r1.38 | > | r1.37 | More }
Revision r1.1 - 15 Jun 1999 - 07:05 GMT - Main.thoeny
Revision r1.39 - 03 Dec 2001 - 12:38 GMT - MikeMannix
Copyright © 2001 by the contributing authors. All material on this collaboration tool is the property of the contributing authors.
Ideas, requests, problems regarding Tharsis? Send feedback.