TWiki Reference Manual (Alpha 30 Jul 2004 $Rev: 1701 $)
This page contains all documentation topics as one long, complete reference sheet.
Doubleclick anywhere to return to the top of the page.
- TWiki System Requirements
- TWiki Installation Guide
- Windows Install Cookbook
- TWiki Upgrade Guide
- TWiki User Authentication
- TWiki Access Control
- TWiki Text Formatting
- TWiki Variables
- File Attachments
- TWiki Forms
- TWiki Templates
- TWiki Skins
- TWiki Formatted Search Results
- TWiki Meta Data
- TWiki Plugins
- TWiki::Func Module Documentation
- Description
- Functions: CGI Environment
- getSessionValue( $key ) ==> $value
- setSessionValue( $key, $value ) ==> $result
- getSkin( ) ==> $skin
- getUrlHost( ) ==> $host
- getScriptUrl( $web, $topic, $script ) ==> $url
- getScriptUrlPath( ) ==> $path
- getViewUrl( $web, $topic ) ==> $url
- getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) ==> $url
- getPubUrlPath( ) ==> $path
- getCgiQuery( ) ==> $query
- writeHeader( $query )
- redirectCgiQuery( $query, $url )
- Functions: Preferences
- Functions: User Handling and Access Control
- Functions: Content Handling
- webExists( $web ) ==> $flag
- topicExists( $web, $topic ) ==> $flag
- getRevisionInfo($theWebName, $theTopic, $theRev, $attachment ) ==> ( $date, $user, $rev, $comment )
- checkTopicEditLock( $web, $topic ) ==> ( $oopsUrl, $loginName, $unlockTime )
- setTopicEditLock( $web, $topic, $lock ) ==> $oopsUrl
- readTopicText( $web, $topic, $rev, $ignorePermissions ) ==> $text
- saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) ==> $oopsUrl
- getPublicWebList( ) ==> @webs
- getTopicList( $web ) ==> @topics
- Functions: Rendering
- expandCommonVariables( $text, $topic, $web ) ==> $text
- renderText( $text, $web ) ==> $text
- internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) ==> $text
- search text( $text ) ==> $text
- formatTime( $time, $format, $timezone ) ==> $text
- formatGmTime( $time, $format ) ==> $text
- Functions: File I/O
- Functions: I18N related
- Copyright and License
- TWiki Site Tools
- Managing Topics
- Managing Webs
- Appendix A: TWiki Filesystem
- Appendix B: TWiki Development Timeline
Note: Read the most up to date version of this document at
http://TWiki.org/cgi-bin/view/TWiki/TWikiDocumentation
Related Topics: TWikiSite,
TWikiHistory,
TWikiPlannedFeatures,
TWikiEnhancementRequests
TWiki System Requirements
Server and client requirements for TWiki 01-Feb-2003
Low client and server requirements are core features that keep TWiki widely deployable, particularly across a range of browser platforms and versions.
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.
Resource | Required Server Environment * |
Perl | 5.005_03 or higher (5.6.1 recommended, 5.8.0 not recommended yet, see TWiki:Codev.IssuesWithPerl5dot8) |
Non-standard Perl modules | • Unix: Net::SMTP (or sendmail ) • Windows: Net::SMTP , MIME::Base64 , Digest::SHA1 |
RCS | 5.7 or higher (including GNU diff ) Optional, but the all-Perl RCS replacement is not currently recommended for live sites - see TWiki:Codev.RcsLite |
GNU diff | GNU diff 2.7 or higher is required when not using the all-Perl RcsLite. Install on PATH if not included with RCS (check version with diff -v ) Must be the version used by RCS, to avoid problems with binary attachments - RCS may have hard-coded path to diff |
Other external programs | fgrep, egrep |
Cron/scheduler | • Unix: cron • Windows: cron equivalents |
Web server | Apache 1.3 is well supported; Apache 2.0 is not recommended yet (see TWiki:Codev.IssuesWithApache2dot0). For other servers, CGI support, authentication, extended path info required; also, the register script is likely to need significant changes |
* Current documentation mainly covers Linux and Apache installations. See WindowsInstallCookbook for a Windows installation guide. See TWiki:Codev.TWikiOn for help with installation on various platforms including Unix, MacOS X, Apache mod_perl
, web hosts, etc.
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 functionality, by customizing
TWikiTemplates, for one, while tailoring the browser requirements to your situation.
Known Issues
- The TWikiPlugins feature currently does not have compatibility guidelines for developers. Plugins can require just about anything - browser-specific functions, stylesheets (CSS), Java applets, cookies, specific Perl modules,... - check the individual Plugin specs.
- Plugins included in the TWiki distribution do not add requirements.
--
TWiki:Main.MikeMannix - 12 Jan 2002
--
TWiki:Main.PeterThoeny - 16 Dec 2003
TWiki Installation Guide
Installation instructions for the TWiki 01-Feb-2003 production release.
If you are reading this on your own TWiki installation, please get the latest installation guide (TWiki:TWiki.TWikiInstallationGuide), as this often has important updates to resolve installation issues.
These installation steps are based on the
Apache web server on
Linux. TWiki runs on other web servers and Unix systems, and should be fine with any web server and OS that meet the
system requirements. Official documentation for platforms other than Linux is somewhat limited, so
please check the topics listed below, they include some important tips for HP-UX, Solaris, OS/390, and many other platforms.
Standard Installation
Request and download the TWiki 01-Feb-2003 distribution in Unix ZIP format from
http://TWiki.org/download.html. Please review the
AdminSkillsAssumptions before you install TWiki.
Step 1: Create & Configure the Directories
NOTE: If you don't have access to your Web server configuration files - for example, if you're installing on an ISP-hosted account, or you don't have administrator privileges on your intranet server - use the alternative Step 1 instead.
- 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 httpd.conf
(typcially located in /etc/httpd/
) 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.
- The
twiki/data
and twiki/templates
directories should be set so that they are not visible as URLs. Add them to httpd.conf
with deny from all
.
Example httpd.conf
entries:
ScriptAlias /twiki/bin/ "/home/httpd/twiki/bin/"
Alias /twiki/ "/home/httpd/twiki/"
<Directory "/home/httpd/twiki/bin">
Options +ExecCGI
SetHandler cgi-script
Allow from all
</Directory>
<Directory "/home/httpd/twiki/pub">
Options FollowSymLinks +Includes
AllowOverride None
Allow from all
</Directory>
<Directory "/home/httpd/twiki/data">
deny from all
</Directory>
<Directory "/home/httpd/twiki/templates">
deny from all
</Directory>
- 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 Unix/Linux root (administrator) privileges, for example, on a hosted Web account or an intranet server administered by someone else:
- 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 | start-up pages | root TWiki dir | /home/smith/twiki/ |
twiki/bin | CGI bin | CGI-enabled dir | /home/smith/twiki/bin |
twiki/lib | library files | same level as twiki/bin | /home/smith/twiki/lib |
twiki/pub | public files | htdoc enabled dir | /home/smith/twiki/pub |
twiki/data | topic data | dir secure from public access | /home/smith/twiki/data |
twiki/templates | web templates | dir secure from public access | /home/smith/twiki/templates |
If you are not able to create the
twiki/lib
directory at the same level as the
twiki/bin
directory (e.g. because CGI
bin
directories can't be under your home directory and you don't have root access), you can create this directory elsewhere and edit the
setlib.cfg
file in the
bin
directory:
# -------------- Change these settings if required
$twikiLibPath = '/some/other/path/lib'; # Path to lib directory containing TWiki.pm
You can also edit
$localPerlLibPath
in the
setlib.cfg
file if you are not root and need to install additional CPAN modules, but can't update the main Perl installation files on the server. Just set this variable to the full pathname to your local lib directory, typically under your home directory.
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 (and some intranet servers), Perl CGI scripts may require a
.cgi
extension to run. Some systems need .pl
, the regular Perl extension. Rename all twiki/bin
scripts 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.
- 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
.
- 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, such as 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 Perl (type this carefully!):
cd twiki/data
perl -pi~ -e 'NR <= 10 && s/nobody:/www-data:/ ' */*,v
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.
- RCS - revision control system to store revision of topics and attachments. You can use RCS executables or a version of RCS written in Perl, note that as the time of writing (Apr 2002) the Perl version has not been widely tested, so if you want to put up a live site the RCS executables are recommended.
- Set
$storeTopicImpl = "RcsWrap";
for the RCS executables and make sure RCS is installed. Set $rcsDir
in twiki/lib/TWiki.cfg
to match the location of your RCS binaries. You can check this by issuing the command rcs
at the prompt, it should result in something like "rcs: no input file"
.
- Check that you have GNU
diff
, by typing diff -v
- an error indicates you have a non-GNU diff, so install the GNU diffutils
package and make sure that diff
is on the PATH used by TWiki (see $safeEnvPath
in the TWiki.cfg
file).
- Set
$storeTopicImpl = "RcsLite";
for the Perl based RCS
- Security issue: Directories
twiki/data
, twiki/templates
and all their subdirectories should be set so that they are not visible through URLs. (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: Configure Site-Wide Email Preferences
- Edit the TWikiPreferences topic in the TWiki web (by pointing your browser to http://yourdomain.com/twiki/bin/view/TWiki/TWikiPreferences) to set the
WIKIWEBMASTER
email address, and other email settings required for registration and WebChangesAlert to work:
-
WIKIWEBMASTER
should be set to the email address of the TWiki administrator
-
SMTPMAILHOST
is typically set on Windows or other non-Unix/Linux systems, where sendmail
or similar is not available. When this is set and the Perl module Net::SMTP
is installed, TWiki will connect to this SMTP server (e.g. mail.yourdomain.com
) to send email for user registration and WebChangesAlerts. If you do have a sendmail-type program, leave SMTPMAILHOST
unset so that the external sendmail program is used instead (defined by $mailProgram
in TWiki.cfg
).
-
SMTPSENDERHOST
is optional, and set to the domain name sending the email (e.g. twiki.yourdomain.com
). For use where the SMTP server requires that you identify the TWiki server sending mail. If not set, Net::SMTP
will guess it for you.
- You may want to set up other TWikiPreferences later on.
- To enable the WebChangesAlerts (email notifications) you need to read about cron in the topic TWikiSiteTools.
Step 5: Finish Up from Your Browser
- Point your Web browser at
http://yourdomain.com/twiki/bin/view
and start TWiki-ing away!
- Or, point to
http://yourdomain.com/twiki/
to get the pre-TWiki index.html
page, with a link to the view
script. Customize this page if you want a public intro screen with a login link, instead of immediately calling up the .htaccess login dialog by going directly to view
.
- Edit the WebPreferences topic in each web, if necessary: set individual
WEBCOPYRIGHT
messages, and other preferences.
- Enable email notification of topic changes, TWikiSiteTools has more.
- Edit the WebNotify topic in all webs and add the users you want to notify.
- Add the TWiki:Main/PoweredByTWikiLogo to your Main.WebHome topic.
- You can add new
%VARIABLES%
. Define site-level variables in the TWikiPreferences topic. See also: TWikiVariables.
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:
- 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 /urlpathto/twiki/index.html http://yourdomain.com/urlpathto/twiki/bin/view
AuthUserFile /filepathto/twiki/data/.htpasswd
ErrorDocument 401 /urlpathto/twiki/bin/oops/TWiki/TWikiRegistration?template=oopsauth
- NOTE: If you had to add a
.cgi
or .pl
file extension to the bin
scripts, make sure to do the same for edit
, view
, preview
, and all the other script names in .htaccess
.
- 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 [3] section of access.conf
for your twiki/bin
directory.
- This applies only if you have root access: on hosted accounts, you shouldn't have this problem - otherwise, email tech support.
- NOTE: In the TWiki distribution package, the
twiki/data/.htpasswd.txt
file contains several TWiki core team user accounts and a guest user account. You probably want to remove those accounts by deleting the entries in .htpasswd
. Do not remove the guest user if you want to allow guest logins.
- Copy the TWikiRegistrationPub topic to TWikiRegistration, overwriting old version of 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.
- Customization:
- 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 carried over into the user home page correctly.
- You can customize the default user home page in NewUserTemplate.
- 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.
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 JCuckoo.Main web - don't try to move them or create them in other webs. From any other web, user signatures have to point to JCuckoo.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 - 03 Jun 2003
--
MikeMannix? - 16 May 2002
Windows Install Cookbook
Introduction
This cookbook is intended to get you up and running with TWiki on Windows quickly, with as few problems as possible. The 'cookbook' approach is simply to restrict the many choices that someone installing TWiki must make, so that a reasonably well-defined procedure can be followed - new users can simply follow the steps, while experts can use this as more of a guideline. Please read
TWiki:Codev.WindowsModPerlInstallCookbook in case you use mod_perl.
There is a huge volume of existing material on TWiki about installing on Windows, and I'm indebted to the many contributors for this - the aim of this cookbook is to synthesise the many tips into a recipe that works.
- NOTE: This cookbook is probably incomplete (e.g. it doesn't cover authentication setup), but it has now been successfully tried out by a few people - it is quite accurate and should get you started if you follow the instructions. Please consider it beta quality, and provide feedback in TWiki:Codev.WindowsInstallCookbookComments.
- NOTE: You will get the best results from following this cookbook exactly, using the same directories etc - however, if you really do need to vary things, it should be fairly obvious what to do.
--
RichardDonkin? - 24 Feb 2002
Recent updates
- 30 Nov 2002 - added
binutils
to list of Cygwin packages, and added warning not to use Apache 2.0
- 20 Nov 2002 - update to avoid TWiki:Support.InstallDigestSHA1Fails when installing Digest::SHA1 on Windows 2000
- 12 Nov 2002 - setting
SMTPMAILHOST
for user registration and notification
- 03 Sep 2002 - linked to TWiki:Codev.WindowsModPerlInstallCookbook
- 20 Jul 2002 - added flags to
grep
commands in TWiki.cfg
- 27 Jun 2002 - more updates to list of required Cygwin packages
- 20 Jun 2002 - added creation of
c:/twiki
directory
- 17 Jun 2002 - updates to list of required Cygwin packages
- 15 Jun 2002 - various notes on Cygwin installation and troubleshooting: use of 'Unix' as default text file type (i.e. for mounting
c:/cygwin
directories) is essential for binary attachment uploads to work properly
- 27 Apr 2002 - update to settings for
egrep
and fgrep
on some Cygwin versions (fix from TWiki:Main.DavidLeBlanc)
- 21 Apr 2002 - updates on download sizes and free disk space requirements, improved post-installation testing, and brief coverage of TWiki:Codev.WindowsInstallModNTLM to avoid TWiki:Codev.ForgettingPasswords
- 18 Apr 2002 - updates on Apache installation, setting TZ variable, and creation of
c:\temp
, based on comments by TWiki:Main.MaryDeMarco
- 3 Apr 2002 - added
pcre
to list of Cygwin packages (required by grep
), fixed bug in Apache config (Apache doesn't allow '#' comments on same line as config)
- 19 Mar 2002 - comment about Windows 98
- 18 Mar 2002 - fix for
register
script committed to TWiki:Codev.TWikiAlphaRelease - most users can ignore this for now, but the edits in step 5 will eventually go away
- 14 Mar 2002 - minor fix to section on Apache environment
- 13 Mar 2002 - added a link to another Windows text editor
- 4 Mar 2002 - changed status to beta, notes about using spaces in file names, pointer on TWiki authentication setup, overview of Cygwin permissions and security issues
- 3 Mar 2002 - minor update to include
uname -a
command to check Cygwin DLL version, and delete Apache config's PassEnv line
- 27 Feb 2002 - various improvements to Cygwin and Perl Net::SMTP installation sections, based on comments in TWiki:Codev.WindowsInstallCookbookComments by TWiki:Main.MartinWittmann. Also linked to a Windows editor that understands Unix/Cygwin file formats.
- 25 Feb 2002 - clarified changes required to
register
, fixed minor typo in Cygwin binary mode section, after beta testing by TWiki:Main.JerryWard (thanks!)
Scope
This document covers installation of the TWiki
01-Feb-2003 production release (
TWiki:Codev/TWikiRelease01Feb2003) in the following environment - if you want to use a different environment, feel free to use this as a guideline only. (It has been mainly tested with the TWiki
01-Dec-2001 release but should work fine with Feb 2003.)
Component | Name, version | Comment |
Operating System | Windows 2000 | Should also work for Windows NT |
Web Server | Apache 1.3.26 | Windows-specific security holes fixed in this build (check latest version at http://httpd.apache.org, but don't use Apache 2.0 yet) |
Unix tools | Cygwin 1.3.9 | Simplest way to get a whole set of required tools |
Perl | Cygwin perl-5.6.1-2 | Comes with Cygwin |
RCS | Cygwin rcs-5.7-2 | Comes with Cygwin, includes a file corruption bugfix |
Why this choice of packages? Because I've tried them, and they work well, without requiring a complicated setup... In particular, Apache is the commonest choice for TWiki on Unix/Linux, Cygwin Perl is very close to Unix Perl, and the Cygwin RCS is regularly updated, with a recent TWiki-relevant bug fix in Feb 2002. Cygwin also lets you install the Unix tools, Perl and RCS in a single step, saving quite a lot of time.
More recent minor versions should be OK, but they can introduce bugs.
Major version upgrades, such as Apache 2.0 and Perl 5.8, are very likely to cause problems - for example, Apache 2.0 is unable to authenticate (see
TWiki:Support.FailedAuthenticationWithApache2OnWinNT) users created by the current TWiki user registration script (due to a feature being removed in 2.0), and Perl 5.8 may introduce issues due to its Unicode features. Even though the Apache group says that Apache 2.0 is the best version, that's not true for TWiki.
Alternatives
There are doubtless other combinations of components that may work - in particular:
Covering the whole range of additional possibilities, particularly web servers, would make this cookbook too complex, and is best handled as a separate activity.
Checking versions
If you already have some of these add-ons installed, here's how to check the versions - this assumes you have
TWiki:Codev.CygWin already installed:
$ : Cygwin DLL version is the number in 1.3.x format
$ uname -r
$ less c:/your-apache-dir/Announcement
$ perl -v
$ rcs -V
If you have an older version of any component, do yourself a favour and
upgrade it as part of the install process.
Pre-requisites and upgrades
You will need to have local administrator rights and to be comfortable with Windows administration.
This cookbook is intended for a clean install, i.e. none of these components are already installed. However, since Cygwin and Apache's installation process is fairly upgrade-friendly, upgrades should work as well - take backups of all your data and config files first, though!
Text editing
Editing Cygwin files is best done with an editor that can handle Unix file format (see the Cygwin binary mode section below) - the installation process includes
nano
, a non-GUI editor, but if you prefer to use a GUI editor, you should first install PFE, a freeware editor that supports Unix format files. PFE is available on
download.com and
Simtel.
Another good
TWiki:Codev.OpenSource editor is SciTE (aka WSciTE), available at
http://www.scintilla.org/SciTE.html.
The Unix/Windows Environment
It's a little known fact that you can use pathnames such as
c:/apache
almost everywhere in Windows - try it in a File Open dialogue box. The main exception is the Win2000
cmd.exe
command line shell - here, you must use double quotes around forward slashes, e.g.
dir "c:/apache"
will work fine.
The reason this matters is that
'\'
is a special character to Perl and other tools, so it's much easier to use
'/'
everywhere.
The Cygwin environment
TWiki:Codev.CygWin is a Unix-like environment for Windows - many of its tools support the
c:/apache
format, but it also provides a more Unixlike syntax, e.g.
/usr/bin/rcs.exe
, because some Unix tools ported onto Cygwin only support the Unix format.
When you launch a Cygwin shell, your existing PATH variable is translated from the Windows format to the Unix format, and the ';' separators in the Windows PATH are changed into ':' separators as required by Unix. A Cygwin tool (e.g. Cygwin Perl or Cygwin RCS) will always use the Unix PATH format, and will accept Unix format pathnames.
The Apache environment
Apache runs as a native Windows process and has nothing to do with Cygwin (at least the version used in this cookbook doesn't). Hence it supports c:/ pathnames in its config files and the first line of Perl CGI scripts.
If you need to use spaces in file names (not recommended), put double quotes around the file name in the
httpd.conf
file. There have been some security-related bugs in Apache with long pathnames, which are a bit more likely if you use spaces, so it's best to just avoid long names and using spaces.
The Perl environment
Once Perl has been launched by Apache, it is in Cygwin mode, and so is everything it launches, including
ls
,
egrep
, and RCS tools that it (typically) launches with the
bash
shell.
If you need to use spaces in file names (not recommended), you
may be able to put double quotes around the file name in the
TWiki.cfg
file - however, it's not clear whether all the TWiki code would work with this.
Installing Components
Enough background, let's get on with the installation.
TWiki (part 1)
Head to
http://twiki.org, click the download link, and fill in the form to request a URL for download. You'll get an automated email, which should arrive by the time you need it.
Apache
1. Download Apache
- Check at http://httpd.apache.org/ for any security announcements
- Check the latest 1.3.x version number on this page
- Find a local mirror using http://www.apache.org/dyn/closer.cgi - choose httpd, then binaries, then win32
- The file to download is
apache_1.3.X-win32-x86-no_src.msi
where 'X' is 20 or higher
- Note that this is a Microsoft Installer format file (.MSI) - this is supported by Windows 2000.
- NOTE: If you are using Windows NT, download the .MSI installer (
instmsi.exe
) from the Apache Win32 download page - this enables you to install .MSI files. You may need to update the .MSI Installer if you have an old version under NT.
- NOTE: The Apache package itself requires a download of around 2 MB, and up to 10 MB of free disk space once installed.
2. Install Apache
- Double-click the .MSI file to run the installer
- Specify
c:\
as the installation directory - this actually installs Apache into c:\apache
(if you specify c:\apache
, it installs into c:\apache\Apache
). Putting Apache into c:\Program Files
is not recommended for easy editing of Apache config files from Cygwin.
- You can choose to run Apache as a Win2000 service or as a normal program - see the Apache docs for details.
3. Test Apache
- If necessary, start apache, either as a Win2000 service (using Admin Tools | Computer Management, or by typing
apache -k start -n apache
) or standalone (by typing apache -k start
)
- Point your browser at http://yourdomain.com/ to see the Apache intro page.
Congratulations, you now have a working web server!
To restart Apache after changing its config, type:
-
apache -k restart
for standalone Apache process running in another window
-
apache -k restart -n apache
for Apache running as a Win2000 service (-n gives name of service)
Another useful command is
apache -k stop
.
Cygwin, Unix tools, Perl and RCS
4. Install Cygwin
Head to
http://cygwin.com, and click the
Install Cygwin Now link. Save the
setup.exe
in a directory, e.g.
c:\download\cygwin-dist
.
Now run the Cygwin
setup.exe
file - this will also install Perl and RCS in one fell swoop.
- Choose Internet install
- On first page, accept the defaults (be sure that the default text file type is Unix to avoid problems with attachment uploads, and specify 'install for all users')
- Select
c:\download\cygwin-dist
as the local package directory, and suitable proxy settings, then pick a local mirror site
- In the package list screen, hit the View button until you get an alphabetical list that says Full to the right of the button.
- Leave the radio button on Curr (Current)
- The Current column shows what's installed on your system (if anything)
- For each package, make sure the New column in the installer has a version number under it. If it says 'Skip' or 'Keep' (meaning it's already installed), single-click that word until a version number is shown. Make sure you select the following packages:
-
bash
-
binutils
-
diffutils
-
gcc
-
grep
-
gzip
-
make
-
nano
-
ncftp
-
pcre
-
perl
(5.6.1-2 or higher)
-
rcs
(5.7-2 or higher)
-
tar
-
textutils
-
unzip
-
w32api
-
wget
(optional, useful for Perl install and TWiki:Codev.ReadWriteOfflineWiki)
- NOTE: Do not include
lynx
if you are upgrading from an older Cygwin installation (to avoid annoying DLL messages) - if you want Lynx, read the Cygwin FAQ entry and upgrade libncurses5
.
- Hit Next to do the installation.
- NOTE: The mandatory packages require a download of about 12 MB - about half of this is Perl, which would be necessary even without Cygwin, and most of the rest is
gcc
, which is required for simple installation of Perl modules that use the C language. Something like 20 to 30 MB of free disk space should be enough for Cygwin, but I didn't test this (try a du -k /
after a new install and let me know the last figure).
- NOTE: The installer keeps a local copy of downloaded files, so it's easy to re-install without re-downloading.
- Let the installer create the shortcuts suggested
5. Test Cygwin
- Launch the desktop icon - this runs the
bash
shell, which has command line editing features
- Use the cursor up key to recall previous commands - normal PC editing keys can then be used to edit a command
- TIP: When typing a directory or file name, hit the TAB key after the first few letters of the name -
bash
will 'complete' the name. If bash
beeps at you, hit TAB again to see the files/directories that match the name so far, and type a bit more before hitting TAB. This saves a lot of time!
- Type
rcs -V
- you should see the RCS version, 5.7
- Type
perl -v
- you should see cygwin mentioned in the first line, and the Perl version, 5.6.1
- Type
grep home /etc/passwd
- you should see some output.
The
Cygwin User Guide is well worth reading for some background on how Cygwin works.
6. Configure Cygwin for binary mode
- This is very important - omitting this step leads to a partially working system that corrupts RCS files - without this, Cygwin tools (including Perl and RCS) will add unwanted carriage returns (Ctrl/M, '\r') to files in an attempt to translate between the Windows and Unix text file formats (Unix text files only use line feeds ('\n').
- Stay in the Cygwin (bash) shell, and type the following (use only forward slashes, i.e. '/'):
$ mkdir /twiki /c c:/twiki
$ mount -b -s c:/twiki /twiki
$ mount -b -s c:/ /c
$ mount -b -c /cygdrive
$ mount
Device Directory Type Flags
C:\cygwin\bin /usr/bin system binmode
C:\cygwin\lib /usr/lib system binmode
C:\cygwin / system binmode
c:\twiki /twiki system binmode
c: /c system binmode
- This configures
/twiki
(known as a 'mount point') to map onto c:/twiki
and for that directory tree to always be in binary mode, and does the same for /c
, mapping it onto c:/
. The last-but-one command sets binary as the default for any unmounted drives (e.g. z:/
, aka /cygdrive/z
).
- It is very important that all lines in the output of
mount
say 'binmode' under Flags
- If the lines for
C:\cygwin
directories do not, you should uninstall and then re-install Cygwin to ensure that binary attachment uploads will work.
- You can now refer to files using Unix paths, e.g.
/twiki/bin/view
or /c/apache/Announcement
- see the Cygwin documentation for more details on this.
- Now test this, still using the Cygwin shell:
- Type
cd /twiki
- Type
echo hi >t
- Type
cat -v t
- you should see hi
as the output
- If you see filename errors, your mounts did not work for some reason - check your typing
- If you see
hi^M
as output, your /twiki directory is not in binary mode
- Clean up by doing
rm t
This setup is written to the Windows registry, so there's no need to put these commands into a
.profile
file. For more information on binary vs text mode, see this
User Guide section and this
FAQ entry.
TWiki (part 2)
7. Download TWiki
Download the latest TWiki release from the URL that
PeterThoeny sent you, and save it in the
c:/twiki
directory.
8. Install TWiki
Unzip the ZIP file under
c:/twiki
using
WinZip, or by going into Cygwin and doing the following - you can hit the
TAB
key to complete filenames after you've typed the first part:
$ cd /twiki
$ unzip TWiki20011201.zip
Configuring components
Now that all the components are installed, you need to configure them.
Configuring Apache
The setup given here is fairly simple, in that it allows only TWiki to be served by the web server. For more complex setups, you can investigate the Alias and ScriptAlias commands that are left commented out in this configuration.
- NOTE: This needs reviewing for security holes and to ensure nothing is missed, though this config does work.
1. Configure Apache (part 1)
Using a suitable text editor (e.g. Cygwin's
'nano'
, or the Windows
PFE editor, unless you already know
'vi'
), edit
c:/apache/conf/httpd.conf
as follows - this tells Apache where TWiki lives, and removes the need to tinker with the Windows 2000 environment settings.
- If you are using nano, always launch it with
nano -w filename
- this turns off wrapping of long lines.
- Note the trailing '/' characters in various places - they are important!
- Create the
c:\temp
directory, by typing mkdir c:\temp
in a DOS command line window
- Edit the following lines, some of which already exist in the file:
# Change this to point to the Apache administrator (e.g. you)
ServerAdmin you@yourdomain.com
# Replaces DocumentRoot "C:/apache/htdocs"
DocumentRoot "C:/twiki"
# Replaces <Directory "C:/apache/htdocs">
<Directory "C:/twiki">
- Add the following lines - the Alias and ScriptAlias lines can be omitted in this setup
# Alias /twiki/ "C:/twiki/"
# ScriptAlias /twiki/bin/ "C:/twiki/bin/"
<Directory "C:/twiki/bin/">
# RD: Changed None to All in next line, to enable .htaccess
AllowOverride All
Allow From All
Options ExecCGI
SetHandler cgi-script
</Directory>
# Environment setup required to run Apache as service or as a
# standalone process.
<IfModule mod_env.c>
# Adjust TZ for your server timezone, e.g. EST5EDT - put the non-daylight-savings
# timezone code first (e.g. EST or GMT), followed by the number of hours that it's behind GMT
# during non-daylight-savings time (use '-5' for timezones in advance of GMT).
SetEnv TZ GMT0BST
SetEnv RCSINIT -x,v/
# Adjust TEMP and TMP for your server and create directories if necessary
SetEnv TEMP c:/temp
SetEnv TMP c:/temp
SetEnv LOGNAME system
SetEnv HOME c:/twiki
</IfModule>
2. Configure Apache (part 2)
Add an AddHandler line to the
<IfModule mod_mime.c>
section of
httpd.conf
- this removes the need to rename all the TWiki CGI scripts later in the installation.
- Note the trailing '.' on the AddHandler line.
#
# Document types
#
<IfModule mod_mime.c>
# TWiki setup - avoid renaming scripts
AddHandler cgi-script .
</IfModule>
Configuring TWiki
3. Configure TWiki
Edit the TWiki config file,
c:/twiki/lib/TWiki.cfg
(or in Cygwin terms,
/twiki/lib/TWiki.cfg
) as follows:
- NOTE: It should be possible to use
c:/twiki
format pathnames for Cygwin, given the above binmode setup, but I have not tested this fully - a Cygwin Perl test script does generate binary mode files in this configuration, so it should work with RCS as well (really need a small RCS file corruption test case). Watch out for RCS file corruption carefully if you do try c:/twiki
pathnames with Cygwin, and do report your experiences...
- NOTE: Some recent versions of Cygwin (e.g. 1.3.10) seem to create 'symbolic links' from
fgrep
and egrep
to grep
, requiring the settings for these commands to point directly to grep
(with suitable flags to provide fgrep
and egrep
behaviour).
# variables that need to be changed when installing on a new server:
# ==================================================================
# http://your.domain.com/twiki : link of TWiki icon in upper left corner :
$wikiHomeUrl = "http://yourdomain.com/bin/view";
# Host of TWiki URL : (Example "http://myhost.com:123")
$defaultUrlHost = "http://yourdomain.com";
# /cgi-bin : cgi-bin path of TWiki URL:
$scriptUrlPath = "/bin";
# /twiki/pub : Public data path of TWiki URL (root of attachments) :
$pubUrlPath = "/pub";
# NOTE: Next three settings should be valid absolute pathnames using Cygwin; if using
# TWiki:Codev.ActiveState Perl, use z:/twiki format pathnames if your TWiki directory is not on C:.
# Public data directory, must match $pubUrlPath :
$pubDir = "/twiki/pub";
# Template directory :
$templateDir = "/twiki/templates";
# Data (topic files) root directory :
$dataDir = "/twiki/data";
....
# Set ENV{'PATH'} explicitly for taint checks ( #!perl -T option ) :
# (Note: PATH environment variable is not changed if set to "")
# On Windows, $safeEnvPath needs only one component, the directory where RCS is installed
# - used by 'rcsdiff' to run 'co' program, so PATH must be correct.
# Unix/Linux setting:
# $safeEnvPath = "/bin:/usr/bin";
# Using Cygwin perl, so can use Unix-like paths, with ':' as separator.
# Note that /usr/bin and /bin are identical due to default /usr/bin mount
# in Cygwin. Must NOT use 'c:/foo' type paths, as ':' is taken as separator
# meaning that 'c' is interpreted as a pathname, giving Perl taint error.
$safeEnvPath = "/bin";
# If using ActiveState perl, use Windows paths instead
# $safeEnvPath = "c:/cygwin/bin";
...
# RCS directory (find out by 'which rcs') :
$rcsDir = "c:/cygwin/bin";
...
# Unix egrep command :
$egrepCmd = "/bin/grep -E";
# Unix fgrep command :
$fgrepCmd = "/bin/grep -F";
For the cookbook install using Cygwin Perl, there's no more
TWiki.cfg
editing to be done, so you can get onto the next section.
# NOTE: When using ActiveState Perl, you must specify
# a full Windows-style pathname, using '\\' for backslashes,
# for the ls, egrep and fgrep commands, because Cygwin's shell
# is not used - forward slashes are OK in Windows everywhere
# except in the cmd.exe shell. Drive letters are OK - e.g.
# 'c:\\foo\\ls' will work. When using Cygwin perl, just
# use the default '/bin/ls' type settings.
#
# Unix ls command :
$lsCmd = "c:\\cygwin\\bin\\ls";
# Unix egrep command :
$egrepCmd = "c:\\cygwin\\bin\\grep";
# Unix fgrep command :
$fgrepCmd = "c:\\cygwin\\bin\\grep";
Editing the CGI scripts
4. Editing the Shebang lines
Now to edit the curiously named 'shebang lines' at the top of the TWiki CGI scripts...
- You must use the Cygwin shell to do this (unless you are a Perl expert) - don't use the Windows command shell, cmd.exe (aka DOS Prompt)
- Then do the following, which quickly edits the 19 or so files, using Perl - the important lines are in bold.
- Type the Perl line very carefully
- If you do mis-type the
perl
line, you can restore from the .backup
directory and re-run the command, as it will only edit the original files, not the backups with '~' suffixes.
$ cd /twiki/bin
$ ls
attach geturl oops rdiff save testenv viewfile
changes installpasswd passwd register search upload
edit mailnotify preview rename statistics view
$ mkdir .backup
$ cp * .backup
$ head -1 view
#!/usr/bin/perl -wT
$ perl -pi~ -e 's;#!/usr/bin/perl;#!c:/cygwin/bin/perl;' *[a-z]
$ head -1 view
#!c:/cygwin/bin/perl -wT
$ ls
attach geturl oops rdiff save testenv viewfile~
attach~ geturl~ oops~ rdiff~ save~ testenv~ view~
changes installpasswd passwd register search upload
changes~ installpasswd~ passwd~ register~ search~ upload~
edit mailnotify preview rename statistics view
edit~ mailnotify~ preview~ rename~ statistics~ viewfile
If for some reason the edit goes wrong, just type
cp .backup/* .
(while within the
bin
directory) to restore the original distribution files. Use
ls -a
to see the
.backup
directory, and
ls -a .backup
to view its contents.
Optional step: you can do
'rm *~'
to clean out the backups made by Perl, but that's not essential as all the original files cannot be executed. If you do this,
type the command very carefully, as a space after the '*' will wipe out all files in this directory!
5. Minor changes to TWiki scripts
TWiki Dec 2001 release only - fixed in Feb 2003 release
If using the Dec 2001 release, you now need to make some minor edits to files in the
c:/twiki/bin
directory, using a suitable editor (remember to use
nano -w filename
if you prefer
nano
to
vi
- or just use the Windows
PFE editor).
- Edit the
register
script in /twiki/bin
- change line 200 to read as follows (insert the MIME::Base64::
part):
return $user . ':{SHA}' . MIME::Base64::encode_base64(Digest::SHA1::sha1($passwd));
Perl module installation
6. Installing required Perl modules
Some additional Perl modules are needed for the
register
script to work properly. Fortunately, there is an automated tool that makes it easy to do this - it's called
cpan
, and goes to the Perl module archive site,
http://www.cpan.org/, to download all required modules, and then build and install them. Here's what you need to do:
First of all, you need to get the
cpan
tool configured and working - this is only necessary once. From the Cygwin shell, type the following (putting the
export
command in
~/.profile
is recommended to make this setting persistent). Without the TEMP variable, some modules may fail to install on Windows 2000 and higher.
$ export TEMP=/c/temp
$ cpan
Lots of questions about configuration and preferences - just hit Enter until you
get to the questions about mirror sites, but answer the questions about FTP proxies etc
if you are behind a proxy-based firewall. The CPAN tool will fetch a series of files,
some quite large, as part of this setup process, so be patient...
NOTE: If you are behind a non-proxy-based firewall that requires the use of passive FTP, the initial downloads of files using Net::FTP may appear to hang - just wait 5 or more minutes, however, and the CPAN tool should eventually hit on
ncftpget
, which is part of Cygwin and does work OK. If this doesn't work and you are behind a typical NAT-based firewall, try doing the following at the Cygwin shell before running
cpan
- this forces Net::FTP to use passive FTP, letting it get through such firewalls:
$ export FTP_PASSIVE=1
If this works, add this line to your
~/.profile
file for future use.
Once some initial files are downloaded, you are asked to select your continent and country, and then mirror sites - just type the number of the mirror sites you want to use (pick a few in case one is down):
...
(28) Turkey
(29) Ukraine
(30) United Kingdom
Select your country (or several nearby countries) [] 30
(1) ftp://cpan.teleglobe.net/pub/CPAN
(2) ftp://ftp.clockerz.net/pub/CPAN/
(3) ftp://ftp.demon.co.uk/pub/CPAN/
(4) ftp://ftp.flirble.org/pub/languages/perl/CPAN/
(5) ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
(6) ftp://ftp.plig.org/pub/CPAN/
(7) ftp://mirror.uklinux.net/pub/CPAN/
(8) ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
(9) ftp://usit.shef.ac.uk/pub/packages/CPAN/
Select as many URLs as you like,
put them on one line, separated by blanks [] 4 7 8
Enter another URL or RETURN to quit: []
New set of picks:
ftp://ftp.flirble.org/pub/languages/perl/CPAN/
ftp://mirror.uklinux.net/pub/CPAN/
ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
Eventually, you'll get to the CPAN tool's shell prompt, where you need to install a few modules - the tool will do all the work for you.
- NOTE: You will need to have previously installed the Cygwin
make
and gcc
packages, which are required by the CPAN installer (gcc
is required for modules that include C language code) - you can install them now by launching Cygwin's setup.exe
from c:/download/cygwin-dist
(no need to exit the CPAN installer).
cpan shell -- CPAN exploration and modules installation (v1.59_54)
cpan> install Net::SMTP
May already be installed - if it is, try 'force install', since it's useful to be able to set
firewall and passive FTP configuration when using Net::FTP. Make sure you answer 'Y' to the question
about whether you want to configure this package.
cpan> install Digest::SHA1
Lots of output about how CPAN finds, builds and installs the module - watch for
any errors, though it should work fine if you have installed the Cygwin packages listed above (particularly 'gcc' and 'make').
cpan> install MIME::Base64
May already be installed.
Re-locking RCS files
7. Re-locking files
First, some testing: in your browser, go to
http://yourdomain.com/bin/testenv - this provides a lot of detail, including warnings. Write down the Apache server's userid that is given by this script - typically either 'system' or 'administrator' - I'll assume 'system' from now on.
- If the
testenv
script doesn't work, go back and check the configuration of the Apache httpd.conf
file, and TWiki.cfg
. Have a look at the Apache error log, c:/apache/logs/error_log
, and the TWiki error log, /twiki/data/log*.txt
.
This 'system' user must own the locks on the RCS files, which are shipped with the lock held by 'nobody'. The reason this matters is that no revisions will be tracked by RCS unless the Apache userid matches that of the RCS file locks.
You can re-lock files using
rcs -u
and
rcs -l
, but it's a painfully manual process. Instead, just use Perl again to mass-edit all the RCS files, as follows:
- NOTE: The 'NR <= 10' part of the Perl command ensures that it only operates on the first 10 lines, to avoid editing the body of RCS files for topics that happen to include the text 'nobody:' (like this one...)
$ cd /twiki/data
$ : Make a backup of all files
$ tar czvf all-files.tar.gz */*
$ : Test edit a single file to check your typing
$ perl -pi~~~ -e 'NR <= 10 && s/nobody:/system:/ ' Main/WebIndex.txt,v
$ diff Main/WebIndex.txt,v Main/WebIndex.txt,v~~~
5c5
< system:1.2; strict;
---
> nobody:1.2; strict;
$ : Now edit all the RCS files at once - use cursor-up to recall previous command
$ perl -pi~~~ -e 'NR <= 10 && s/nobody:/system:/ ' */*,v
$ : Check for any remaining files not edited
$ grep 'strict;$' */*,v | grep -v system
$ : Clean up - type this very carefully
$ rm */*~~~
- If something goes wrong: to restore your existing files from the backup, just type
tar xzvf all-files.tar.gz
and all your files, both .txt and .txt,v, will be back as they were before the edits.
You have now re-locked all the RCS files and are almost ready to start using TWiki!
Email setup
8. Email setup for notification and registration
You need to set the
SMTPMAILHOST
in
TWikiPreferences to an SMTP email host that is reachable and currently working. Otherwise you'll get a confusing message from TWiki when registering new users or running
mailnotify
(for
WebNotify), along the lines of:
Software Error: Can't call method "mail" on an undefined value at ../lib/TWiki/Net.pm line 187.
There are other settings to be made in
TWikiPreferences, e.g. the
WIKIWEBMASTER
and (probably) the
SMTPSENDERHOST
(normally your mail server or TWiki server). See the
TWikiInstallationGuide for more details, what's listed here is just enough to let you run the basic tests.
Testing your TWiki installation
It is important to test your TWiki installation before you release it to other users or put any significant data into it.
Here are the main things to test:
- testenv - use
http://yourdomain.com/bin/testenv
and check for warnings
- Page viewing (
view
script) - click around a few pages and make sure the links are OK
- RCS diffs (
rdiff
script) - click on the Diffs link and on the '>' links at bottom of page
- Edit a page, and register as a new user - tests page creation, use of
register
script to create a new user entry in /twiki/data/.htpasswd
(the Apache password file), ability to send email via Net::SMTP, and whether SMTPMAILHOST
was set correctly in TWikiPreferences.
- If you get a failure to register or send email, check the Apache error log, and that all CPAN modules were installed correctly in Step 6, Installing required Perl modules.
- Try typing
tail -30 /c/apache/logs/error_log
to see last 30 errors from Apache
- Edit a page - check revision increased and set to current date/time
- Edit the same page using another browser or PC, logging in as a different user - check there's a lock message (which you can override) and no double lines
- Check the Apache
error_log
file to see if there are any RCS errors so far
- Index - tests whether
ls
and grep
are working
- Search - more tests for whether
ls
and grep
are working
- Attachments - tests access to
/twiki/pub
directory.
- Try a binary attachment upload and check the number of bytes in the file has not changed - if it has, see the Install Cygwin section's note on the default text file type.
- Check the Apache
error_log
file again
Troubleshooting
If anything doesn't work, go back and check the configuration of the Apache
httpd.conf
file, and
TWiki.cfg
. Have a look at the Apache error log,
c:/apache/logs/error_log
, and the TWiki error log,
/twiki/data/log*.txt
, and if necessary enable debugging on selected scripts (the commands are right at the top of each script) - the results go into
/twiki/data/debug.txt
. There is also a
/twiki/data/warning.txt
file that contains less serious messages.
See
TWiki:Codev.TWikiPatches in case there are patches (i.e. specific code changes) for particular problems that may affect you (e.g.
TWiki:Codev.ChangePasswordOnWin2K).
If you find that the Index feature doesn't work, or topic name searches fail, you should check you have set
$egrepCmd
and
$fgrepCmd
correctly, as mentioned above.
Permissions
TWiki:Codev.CygWin has several models for how it does security:
- By default, it only implements the Unix 'write' and 'execute' permissions bits - the former is controlled by the Windows Read-Only attribute, while the latter is automatically assigned to files named *.exe or *.com, and to files whose first line is a shebang (i.e.
#!/bin/something
). This is what has been used for this cookbook.
- You can enable the 'ntea' or 'ntsec' models, which will increase security but are also likely to introduce permission problems.
I have not had any problems with TWiki permissions on Windows, unlike Linux/Unix, which is probably because I'm using the default security model for Cygwin. If you use the other models, you may still be OK if you have local admin rights, and Apache is running as the SYSTEM user (which it uses if started as a service). If you do have trouble in this area, see the
TWikiInstallationGuide's advice, some of which will apply to
TWiki:Codev.CygWin, and log any issues in
TWiki:Codev.WindowsInstallCookbookComments.
Next Steps
See the
TWikiInstallationGuide for other setup. In particular, you'll probably want to refer to the
section on basic authentication - remember to use
c:/twiki
type filenames (i.e. Windows format) since you are using Apache for Windows.
Improved authentication
You may want to investigate
TWiki:Codev.WindowsInstallModNTLM, which describes how to add an Apache module so that
TWiki:Codev.InternetExplorer users are automatically authenticated based on their Windows domain login - this avoids
TWiki:Codev.GettingTheUsernameWrong and
TWiki:Codev.ForgettingPasswords, which are usually very common among TWiki users.
Improved performance
See
TWiki:Codev.WindowsModPerlInstallCookbook and
TWiki:Codev.ModPerl for information on installing TWiki under Apache's
mod_perl
- this is somewhat more complex and follows a different model, so it's best to get some experience with TWiki, Apache and Perl first.
Format of filenames
In your TWiki on Windows installation, it's worth remembering that:
- Apache configuration files (e.g. the
.htaccess
file and c:/apache/conf/httpd.conf
) always use Windows format paths, with forward slashes, e.g. c:/twiki
- The same is true for the first line of the TWiki Perl scripts (since this line is interpreted by Apache), e.g.
c:/cygwin/bin/perl
- All other lines in the Perl scripts use Unix format paths, e.g.
/twiki
(using Cygwin Perl as per this cookbook)
- Depending on the Perl version used (Cygwin or TWiki:Codev.ActivePerl), the TWiki.cfg file uses a mixture of Unix and Cygwin format paths - stick to the format used in the installation step for TWiki.cfg
- RCS always uses Unix format paths, e.g.
/twiki
Credits
Material in this cookbook is heavily based on the enormous number of contributions in
TWiki:Codev.TWikiOnWindowsArchive and related topics - too many people to thank, but have a look at the contributor list to
TWiki:Codev.TWikiOnWindowsArchive to get an idea!
People who've tested or reviewed this document and provided valuable feedback include:
Comments welcome at
TWiki:Codev.WindowsInstallCookbookComments
--
PeterThoeny - 30 Jan 2003
TWiki Upgrade Guide
Upgrade from the previous TWiki 01-Dec-2001 production release to TWiki 01-Feb-2003
Overview
This guide describes how to upgrade from TWiki 01-Dec-2001 to TWiki 01-Feb-2003. The new version involves several new features and numerous enhancements to the previous version.
Upgrade Requirements
- To upgrade from a 01-Dec-2001 standard installation to the latest 01-Feb-2003 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-Dec-2001
- Form and script to create new webs
- Enhanced Plugin API to manipulate topic data with new functions in TWikiFuncModule:
readTopicText
, saveTopicText
, setTopicEditLock
, checkTopicEditLock
- New Plugin hooks
registrationHandler
, beforeEditHandler
, afterEditHandler
, beforeSaveHandler
, writeHeaderHandler
, redirectCgiQueryHandler
, getSessionValueHandler
, setSessionValueHandler
- Internationalization ('I18N') support 8-bit character sets in WikiWords, such as ISO-8859-15, KOI8-R
- Possible to omit e-mail address in WebNotify, in which case the e-mail is taken from the user's home page; if the WikiName is a group name, a notification is sent to all members of the group
- New data storage framework that lets you use external RCS commands for revision control, or a new native Perl implementation that does not depend on the external RCS commands (not recommended yet for production use, see TWiki:Codev/RcsLite)
- New AND search; with regular expression enabled, use the semicolon ";" as the AND operator in
%SEARCH{}%
variable, FormattedSearch and WebSearch
- Many more enhancements, see the complete change log at TWikiHistory
Upgrade Procedure from 01-Dec-2001 to 01-Feb-2003 Release
The following steps describe the upgrade assuming that
$TWIKIROOT
is the root of your current 01-Dec-2001 release. As written this will require some downtime. A process for switching over without downtime is described at the end of this section.
- Back up and prepare:
- Back up all existing TWiki directories
$TWIKIROOT/bin
, $TWIKIROOT/pub
, $TWIKIROOT/data
, $TWIKIROOT/templates
, $TWIKIROOT/lib
.
- Create a temporary directory and unpack the ZIP file there.
- Update files in TWiki root:
- Overwrite all
*.html
and *.txt
files in $TWIKIROOT
with the new ones.
- Update template files:
- Overwrite all template files in
$TWIKIROOT/templates
with the new ones.
- If you have customized your templates, make sure to merge those changes to the new files.
- If you have customized skins or loaded new skins, make sure to merge or apply those changes to the new files.
- Specific changes to templates and skins:
- Replace
%WIKIHOMEURL%
with %WIKILOGOURL%
- Replace img tag's
src=%PUBURLPATH%/wikiHome.gif
with src=%WIKILOGOIMG%
- Replace img tag's
alt="TWiki Home"
with alt="%WIKILOGOALT%"
- Replace meta tag's
charset=iso-8859-1"
with charset=%CHARSET%"
- Add
%TOPIC%
to form action of GoBox
- For internationalized sites, URL encode webs and topics in all form actions, e.g. replace
.../view%SCRIPTSUFFIX%/%WEB%/%TOPIC%"
with .../view%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%/%TOPIC%"}%
- Update script files:
- Overwrite all script files in
$TWIKIROOT/bin
with the new ones.
- If necessary, change the script names to include the required extension, e.g.
.cgi
- Edit
$TWIKIROOT/bin/setlib.cfg
and point $twikiLibPath
to the absolute file path of $TWIKIROOT/lib
- Edit
$TWIKIROOT/bin/.htaccess
to include a directive for the new manage
script:
<Files "manage">
require valid-user
</Files>
- Pay attention to the file and directory permissions, the scripts need to be executable, e.g.
chmod 775 $TWIKIROOT/bin/*
- If on Non-Unix host, make sure the correct path to the perl interpreter is changed in the first line of every script file. See also WindowsInstallCookbook.
- Update library files:
- Overwrite the
TWiki.cfg
configuration file in $TWIKIROOT/lib
with the new one.
- Restore the configuration values from the backup. You typically need to configure just the ones in the section "variables that need to be changed when installing on a new server".
- Overwrite the
TWiki.pm
library in $TWIKIROOT/lib
with the new one.
- Copy and overwrite all subdirectories below
$TWIKIROOT/lib
with the new ones. Make sure to preserve any extra Plugins you might have in $TWIKIROOT/lib/TWiki/Plugins
- Pay attention to the file and directory permissions, the library files should not be executable, e.g.
chmod -R 664 $TWIKIROOT/lib/*
- Update data files:
- Run the
bin/testenv
script from the browser (e.g. http://localhost/bin/testenv
) to verify if the cgi-scripts are running as user nobody
.
- In case not: The
*,v
RCS repository files delivered with the installation package are locked by user nobody
and need to be changed to the user of your cgi-scripts, e.g. www-data
:
- Change the lock user in the temporary
twiki/data/*
directories where you unzipped the installation package: A simple way to switch the locker of the RCS files is to use sed in the :
for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done
- In the temporary
twiki/data/TWiki
directory where you unzipped the installation package:
- Remove the files you do not want to upgrade:
InterWikis.*
, TWikiRegistration.*
, TWikiRegistrationPub.*
, WebNotify.*
, WebPreferences.*
, WebStatistics.*
and all WebTopic*
files.
- Rename in the temporary directory the file
$TWIKIROOT/data/TWiki/TWikiPreferences.*
to TWikiPreferencesSave.*
.
- Move all remaining
*.txt
and *.txt,v
files from the temporary data/TWiki
directory to your $TWIKIROOT/data/TWiki
directory, overwriting the existing ones.
- Merge your original
TWikiPreferencesSave.txt
settings into $TWIKIROOT/data/TWiki/TWikiPreferences.txt
.
- Move the
data/_default
directory from the temporary location to your $TWIKIROOT/data
directory.
- Move the
data/Sandbox
directory from the temporary location to your $TWIKIROOT/data
directory
(The Test web has been renamed to Sandbox in this release.)
- There are now two webs in parallel (Test and Sandbox) for the purpose of testing (experimenting) TWiki.
Move all relevant topics from Test web to Sandbox web, or motivate the users to do.
- Make sure that the directories and files below
$TWIKIROOT/data
are writable by your cgi-script user.
- Adapt the other webs (all other than
TWiki
and _default
):
- Merge the new files
WebHome.txt
and WebPreferences.txt
of your other webs to make sure, you have the improvements applied also in your other webs.
- Update pub files:
- Move all subdirectories below
pub/TWiki
from your temporary directory into your $TWIKIROOT/pub/TWiki
directory.
- Make sure that the directories and files below
$TWIKIROOT/pub/TWiki
are writable by your cgi-script user.
- Move all files in
pub/icn
directory from the temporary location to your $TWIKIROOT/pub/icn
directory.
- Update TWikiPreferences to authorize users to create webs:
- Add
ALLOWWEBMANAGE
to the FINALPREFERENCES
list so that nobody can overwrite the setting:
- Set FINALPREFERENCES = WIKIWEBMASTER, PREVIEWBGIMAGE, SMTPMAILHOST, SMTPSENDERHOST, ALLOWWEBMANAGE
- Set users or groups allowed to create new webs:
- Verify installation:
- Execute the
$TWIKIROOT/bin/testenv
script from your browser (e.g. http://localhost/bin/testenv
) to see if it reports any issues; fix any potential problems.
- Test your updated TWiki installation to see if you can view, create, edit and rename topics; upload and move attachments; register users.
- Test if the installed Plugins work as expected. You should see the list of installed Plugins in TextFormattingRules.
Note: These steps assume a downtime during the time of upgrade. You could install the new version in parallel to the existing one and switch over in an instant without affecting the users. As a guideline, install the new version into
$TWIKIROOT/bin1
,
$TWIKIROOT/lib1
,
$TWIKIROOT/templates1
,
$TWIKIROOT/data/TWiki1
(from
data/TWiki
),
$TWIKIROOT/pub/TWiki1
(from
pub/TWiki
), and configure
TWiki.cfg
to point to the same data and pub directory like the existing installation. Once tested and ready to go, reconfigure
$TWIKIROOT/bin1/setlib.cfg
and
$TWIKIROOT/lib1/TWiki.cfg
, then rename
$TWIKIROOT/bin
to
$TWIKIROOT/bin2
,
$TWIKIROOT/bin1
to
$TWIKIROOT/bin
. Do the same with the
lib
,
templates
and
data/TWiki
directories.
Known Issues
--
PeterThoeny - 01 Feb 2002
--
MartinRaabe? - 15 Jan 2003
TWiki User Authentication
TWiki site access control and user activity tracking options
TWiki does not authenticate users internally, it depends on the
REMOTE_USER
environment variable. This variable is set when you enable Basic Authentication (.htaccess) or SSL "secure server" authentication (https protocol).
TWiki uses visitor identification to keep track of who made changes to topics at what time and to manage a wide range of personal site settings. This gives a complete audit trail of changes and activity.
Authentication Options
No special installation steps are required if the server is already authenticated. If it isn't, you have these options for controlling user access:
- No login at all: Forget about authentication to make your site completely public - anyone can browse and edit freely, in classic Wiki mode. All visitors are assigned the TWikiGuest default identity, so you can't track individual user activity.
- How: Default, no web server configuration necessary
- No login to view; require login to edit: Keeping track of who changed what and when, while keeping view access unrestricted is desirable in most TWiki deployments. This option is not suitable if you need TWikiAccessControl for view restricted content since TWiki does not know who a user is when looking at content.
- How: Use Basic Authentication (
.htaccess
) to control access by protecting key scripts: attach
, edit
, installpasswd
, manage
, preview
, rename
, save
, upload
using the .htaccess file
. The TWikiInstallationGuide has step-by-step instructions.
- No login to view unless necessary; require login to edit: You prefer not to bother the user with login for unrestricted content, but you need TWikiAccessControl for view restricted content. There are two ways to accomplish this:
- How 1: Use Basic Authentication with Partial Authentication (described below)
- How 2: Use one of the Session TWiki:Plugins where you give the user the option to login and logout.
- Require login to view and edit: Most restrictive, but TWiki knows who the user is at all times. There are two ways to accomplish this:
- How 1: Use Basic Authentication to authenticate the whole
twiki/bin
directory. Consult your web server documentation.
- How 1: Use SSL (Secure Sockets Layer; HTTPS) to authenticate and secure the whole server. Consult your web server documentation.
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.
- Copy the
view
script to viewauth
(or better, create a symbolic link)
- Add
viewauth
to the list of authenticated scripts in the twiki/bin/.htaccess
file. The view
script should not be listed in the .htaccess
file.
- 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:
TWiki Username vs. Login Username
This section applies only if your TWiki site is installed on a server that is both
authenticated and on an
intranet.
JCuckoo internally manages two usernames: Login Username and TWiki Username.
- Login Username: When you login to the intranet, you use your existing login username, ex:
pthoeny
. This name is normally passed to TWiki by the REMOTE_USER
environment variable, and used internally. Login Usernames are maintained by your system administrator.
- TWiki Username: Your name in WikiNotation, ex:
PeterThoeny
, is recorded when you register using TWikiRegistration; doing so also generates a personal home page in the Main web.
TWiki can automatically map an Intranet (Login) Username to a TWiki Username, provided that the username pair exists in the
TWikiUsers topic. This is also handled automatically when you register.
- In the original TWiki distribution, in
twiki/data
, there are two registration form topics, TWikiRegistration and TWikiRegistrationPub. The original form includes an intranet Login Username field. For Basic Authentication, the original form is replaced by the Pub version. If you started using TWiki on Basic Authentication and want to change, you have to switch back forms for future use, and manually correct the existing entries, by editing TWikiUsers, adding the Login Username for each member - PeterThoeny - pthoeny - 01 Jan 1999
- and also in the .htpasswd
file, where you can either replace the WikiNames or duplicate the entries and have both, so both usernames will work.
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 JCuckoo.Main web, where user registration pages are stored, no matter which web it's entered in. Without the web prefix, the name appears as a NewTopic? everywhere but in the Main web.
Changing Passwords
Change and reset passwords using forms on regular pages. Use
TWikiAccessControl to restrict use as required.
Forgot your old password? Then use ResetPassword instead. Please only use ResetPassword in case you really forgot your password. Thank you.
After submitting this form your password will be changed.
If you have questions please contact the TWiki webmaster rumcajs_78@users.sourceforgeNOSPAM.net.
Please only use this ResetPassword form in case you really forgot your password. Otherwise just change it using ChangePassword. Thank you.
After submitting this form you will see a page with your new password appearing encrypted.
You will have to e-mail this information to the Wiki webmaster, rumcajs_78@users.sourceforgeNOSPAM.net, who will set your account to use the new password.
-- TWiki.Main.MikeMannix - 19 May 2002
-- TWiki.Main.PeterThoeny - 25 Apr 2004
TWiki Access Control
Restricting read and write access to topics and webs, by Users and groups
TWikiAccessControl allows you restrict access to single topics and entire webs, by individual user and by user Groups, in three areas: view; edit & attach; and rename/move/delete. Access control, combined with
TWikiUserAuthentication, lets you easily create and manage an extremely flexible, fine-grained privilege system.
An Important Control Consideration
Open, freeform editing is the essence of
WikiCulture - what makes TWiki different and often more effective than other collaboration tools. For that reason, it is strongly recommended that decisions to restrict read or write access to a web or a topic are made with care - the more restrictions, the less Wiki in the mix. Experience shows that
unrestricted write access works very well because:
- Peer influence is enough to ensure that only relevant content is posted.
- Peer editing - the ability for anyone to rearrange all content on a page - keeps topics focussed.
- In TWiki, content is transparently preserved under revision control:
- Edits can be undone by the TWikiAdminGroup (the default administrators group; see #ManagingGroups).
- Users are encouraged to edit and refactor (condense a long topic), since there's a safety net.
As a
collaboration guideline:
- Create broad-based Groups (for more and varied input), and...
- Avoid creating view-only Users (if you can read it, you should be able to contribute to it).
Authentication vs. Access Control
Authentication: Identifies who a user is based on a login procedure. See
TWikiUserAuthentication.
Access control: Restrict access to content based on users and groups once a user is identified.
Users and Groups
Access control is based on the familiar concept of Users and Groups. Users are defined by their
WikiNames. They can then be organized in unlimited combinations by inclusion in one or more user Groups. For convenience, Groups can also be included in other Groups.
Managing Users
A user can create an account in
TWikiRegistration. The following actions are performed:
- WikiName and encrypted password are recorded in
.htpasswd
if authentication is enabled.
- A confirmation e-mail is sent to the user.
- A user home page with the WikiName of the user is created in the Main web.
- The user is added to the TWikiUsers topic.
Users can be authenticated using Basic Authentication (htaccess) or SSL (secure server). In either case,
TWikiUserAuthentication is required in order to track user identities, and use User and Group access control.
The default visitor name is
TWikiGuest. This is the non-authenticated user.
Managing Groups
Groups are defined by group topics created in the
Main
web, like the
TWikiAdminGroup. To create a new group:
-
Edit
TWikiGroups by entering a new topic with a name that ends in Group
. Example:
- Set Preferences for two Variables in the new group topic:
-
Set GROUP = < list of Users and/or Groups >
-
Set ALLOWTOPICCHANGE = < list of Users and/or Groups >
- The GROUP variable is a comma-separated list of Users and/or other Groups. Example:
-
Set GROUP = Main.SomeUser, Main.OtherUser, Main.SomeGroup
- ALLOWTOPICCHANGE defines who is allowed to change the group topic; it is a comma delimited list of Users and Groups. You typically want to restrict that to the members of the group itself, so it should contain the name of the topic. (This prevents Users not in the Group from editing the topic to give themselves or others access. For example, for the TWikiAdminGroup topic write:
-
Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup
Restricting Write Access
You can define who is allowed to make changes to a web or a topic.
Deny Editing by Topic
Denying editing of a topic also restricts file attachment; both privileges are assigned together.
- Define one or both of these variables in a topic, preferably at the end of the page:
-
Set DENYTOPICCHANGE = < list of Users and Groups >
-
Set ALLOWTOPICCHANGE = < list of Users and Groups >
- DENYTOPICCHANGE defines Users or Groups that are not allowed to make changes to the topic, with a comma-delimited list. Example:
-
Set DENYTOPICCHANGE = Main.SomeBadBoy, Main.SomeBadGirl, Main.SomeHackerGroup
- ALLOWTOPICCHANGE defines Users or Groups that are allowed to make changes to the topic. It is a comma delimited list of Users and Groups. Example:
-
Set ALLOWTOPICCHANGE = Main.SomeGoodGuy, Main.SomeGoodGirl, Main.TWikiAdminGroup
- DENYTOPICCHANGE is evaluated before ALLOWTOPICCHANGE. Access is denied if the authenticated person is in the DENYTOPICCHANGE list, or not in the ALLOWTOPICCHANGE list. Access is granted in case DENYTOPICCHANGE and ALLOWTOPICCHANGE is not defined.
Deny Editing by Web
Restricting web-level editing blocks creating new topics, changing topics or attaching files.
- Define one or both of these variable in the WebPreferences topic:
-
Set DENYWEBCHANGE = < list of Users and Groups >
-
Set ALLOWWEBCHANGE = < list of Users and Groups >
The same rules apply as for restricting topics, with these additions:
- DENYTOPICCHANGE (in topic) overrides DENYWEBCHANGE (in WebPreferences)
- ALLOWTOPICCHANGE (in topic) overrides ALLOWWEBCHANGE (in WebPreferences)
Restricting Rename Access
You can define who is allowed to rename, move or delete a topic, or rename a web.
Deny Renaming by Topic
To allow a user to rename, move or delete a topic, they also need write (editing) permission. They also need write access to change references in referring topics.
- Define one or both of these variables in a topic, preferably at the end of the topic:
-
Set DENYTOPICRENAME = < list of Users and Groups >
-
Set ALLOWTOPICRENAME = < list of Users and Groups >
- DENYTOPICCRENAME defines Users or Groups that are not allowed to rename the topic. It is a comma delimited list of Users and Groups. Example:
-
Set DENYTOPICRENAME = Main.SomeBadBoy, Main.SomeBadGirl, Main.SomeHackerGroup
- ALLOWTOPICRENAME defines Users or Groups that are allowed to rename the topic. It is a comma delimited list of Users and Groups. Example:
-
Set ALLOWTOPICRENAME = Main.SomeGoodGuy, Main.SomeGoodGirl, Main.TWikiAdminGroup
- DENYTOPICRENAME is evaluated before ALLOWTOPICRENAME. Access is denied if the authenticated person is in the DENYTOPICRENAME list, or not in the ALLOWTOPICRENAME list. Access is granted in case DENYTOPICRENAME and ALLOWTOPICRENAME is not defined.
Deny Renaming by Web
You can define restrictions of who is allowed to rename a JCuckoo web.
- Define one or both of these variable in the WebPreferences topic:
-
Set DENYWEBRENAME = < list of Users and Groups >
-
Set ALLOWWEBRENAME = < list of Users and Groups >
The same rules apply as for topics, with these additions:
- DENYTOPICRENAME (in topic) overrides DENYWEBRENAME (in WebPreferences)
- ALLOWTOPICRENAME (in topic) overrides ALLOWWEBRENAME (in WebPreferences)
Restricting Read Access
You can define who is allowed to see a web.
Deny Viewing by Topic
Technically it is possible to restrict read access to an individual topic based on
DENYTOPICVIEW
/
ALLOWTOPICVIEW
preferences variables, provided that the view script is authenticated. However this setup is not recommended since all content is searchable within a web - a search will turn up view restricted topics.
Deny Viewing by Web
You can define restrictions of who is allowed to view a JCuckoo web. You can restrict access to certain webs to selected Users and Groups, by:
- obfuscating webs: Insecure but handy method to hide new webs until content is ready for deployment.
- authenticating all webs and restricting selected webs: Topic access in all webs is authenticated, and selected webs have restricted access.
- authenticating and restricting selected webs only: Provide unrestricted viewing access to open webs, with authentication and restriction only on selected webs.
Obfuscate Webs
The idea is to keep a web hidden by not publishing its URL and by preventing the
all webs
search option from accessing obfuscated webs. Do so by enabling the
NOSEARCHALL
variable in
WebPreferences:
This setup can be useful to hide a new web until content its ready for deployment.
Obfuscating webs is insecure, as anyone who knows the URL can access the web.
Authenticate all Webs and Restrict Selected Webs
Use the following setup to authenticate users for topic viewing in all webs and to restrict access to selected webs:
- Restrict view access to selected Users and Groups. Set one or both of these variables in its WebPreferences topic:
-
Set DENYWEBVIEW = < list of Users and Groups >
-
Set ALLOWWEBVIEW = < list of Users and Groups >
- Note:
DENYWEBVIEW
is evaluated before ALLOWWEBVIEW
. Access is denied if the authenticated person is in the DENYWEBVIEW
list, or not in the ALLOWWEBVIEW
list. Access is granted in case DENYWEBVIEW
and ALLOWWEBVIEW
is not defined.
- Hide the web from an "all webs" search. Enable this restriction with the
NOSEARCHALL
variable in its WebPreferences topic:
- Add
view
to the list of authenticated scripts in the .htaccess
file.
This method only works if the
view
script is authenticated, which means that all Users have to login, even for read-only access. (An open guest account, like
TWikiGuest, can get around this, allowing anyone to login to a common account with, for example, view-only access for public webs.)
TWikiInstallationGuide has more on Basic Authentication, using the
.htaccess
file.
Authenticate and Restricting Selected Webs Only
Use the following setup to provide unrestricted viewing access to open webs, with authentication only on selected webs:
- Restrict view access to selected Users and Groups. Set one or both of these variables in its WebPreferences topic:
-
Set DENYWEBVIEW = < list of Users and Groups >
-
Set ALLOWWEBVIEW = < list of Users and Groups >
- Note:
DENYWEBVIEW
is evaluated before ALLOWWEBVIEW
. Access is denied if the authenticated person is in the DENYWEBVIEW
list, or not in the ALLOWWEBVIEW
list. Access is granted in case DENYWEBVIEW
and ALLOWWEBVIEW
is not defined.
- Hide the web from an "all webs" search. Enable this restriction with the
NOSEARCHALL
variable in its WebPreferences topic:
- Enable the
$doRememberRemoteUser
flag in lib/TWiki.cfg
as described in TWikiUserAuthentication. JCuckoo will now remember the IP address of an authenticated user.
- Copy the
view
script to viewauth
(or better, create a symbolic link)
- Add
viewauth
to the list of authenticated scripts in the .htaccess
file. The view
script should not be listed in the .htaccess
file.
When a user accesses a web where you enabled view restriction, JCuckoo will redirect from the
view
script to the
viewauth
script once (this happens only if the user has never edited a topic). Doing so will ask for authentication. The
viewauth
script shows the requested topic if the user could log on and if the user is authorized to see that web.
Authenticating webs is not very secure, as there is a way to circumvent the read access restriction. It can be useful in certain situations - for example, to simplify site organization and clutter, by hiding low traffic webs - but is not recommended for securing sensitive content.
Hiding Control Settings
To hide access control settings from normal browser viewing, place them in comment markers.
The SuperAdminGroup
By mistyping a user or group name in the ALLOWTOPICCHANGE setting, it's possible to lock a topic so that no-one can edit it from a browser. To avoid this, you can create Web-based
superusers:
- Set the
$superAdminGroup
variable in lib/TWiki.cfg
to the name of a group of Users who are always allowed to edit/view topics.
$superAdminGroup = "TWikiAdminGroup";
- The default setting is not to have superusers.
--
PeterThoeny - 04 May 2002
--
MikeMannix? - 12 May 2002
TWiki Text Formatting
Working in TWiki is as easy as typing in text -
exactly like email. You don't need to know HTML, though you can use it if you prefer. Links to topics are created automatically when you enter
WikiWords. And TWiki shorthand gives you all the power of HTML with a simple coding system that takes no time to learn. It's all laid out below - refer back to this page in a pop-up window from the
Edit screen.
TWiki Editing Shorthand
Formatting Command:
|
Example: You write:
|
You get:
|
Paragraphs:
Blank lines will create new paragraphs.
|
1st paragraph
2nd paragraph
|
1st paragraph
2nd paragraph
|
Headings:
At least three dashes at the beginning of a line, followed by plus signs and the heading text. One plus creates a level 1 heading (most important), two pluses a level 2 heading; the maximum is level 6. Note: A Table of Content can be created automatically with the %TOC% variable, see TWikiVariables. Any heading text after !! is excluded from the TOC; for example, write ---+!! text if you do not want to list a header in the TOC.
|
---++ Sushi
---+++ Maguro
|
Sushi
Maguro
|
Bold Text:
Words get bold by enclosing them in * asterisks.
|
*Bold*
|
Bold
|
Italic Text:
Words get italic by enclosing them in _ underscores.
|
_Italic_
|
Italic
|
Bold Italic:
Words get _bold italic by enclosing them in _ double-underscores.
|
__Bold italic__
|
Bold italic
|
Fixed Font:
Words get shown in fixed font by enclosing them in = equal signs.
|
=Fixed font=
|
Fixed font
|
Bold Fixed Font:
Words get shown in bold fixed font by enclosing them in double equal signs.
|
==Bold fixed==
|
Bold fixed
|
Note: Make sure there is no space between the text and the bold, italic, or other indicators (* _ __ = == ).
|
_This works_,
_this not _
|
This works,
_this not _
|
Verbatim Mode:
Surround code excerpts and other formatted text with <verbatim> and </verbatim> tags. Note: Use <pre> and </pre> tags instead if you want that HTML code is interpreted. Note: Each tag must be on a line by itself.
|
<verbatim>
class CatAnimal {
void purr() {
<code here>
}
}
</verbatim>
|
class CatAnimal {
void purr() {
<code here>
}
}
|
Separator:
At least three dashes at the beginning of a line.
|
-------
|
|
List Item:
Three spaces, an asterisk, and another space.
|
* bullet item
|
|
Nested List Item:
Six, nine, ... spaces, an asterisk, and another space.
|
* level 1
* level 2
|
|
Ordered List:
Three spaces, a number, a dot, and another space. Several types are available besides a number:
Type | Generated Style | Sample Sequence |
1. | Arabic numerals | 1, 2, 3, 4... |
A. | Uppercase letters | A, B, C, D... |
a. | Lowercase letters | a, b, c, d... |
I. | Uppercase Roman Numerals | I, II, III, IV... |
i. | Lowercase Roman Numerals | i, ii, iii, iv... |
|
1. Sushi
1. Dim Sum
A. Sushi
A. Dim Sum
i. Sushi
i. Dim Sum
|
- Sushi
- Dim Sum
- Sushi
- Dim Sum
- Sushi
- Dim Sum
|
Definition List:
Three spaces, a dollar sign, the term, a colon, a space, followed by the definition.
|
$ Sushi: Japan
$ Dim Sum: S.F.
|
- Sushi
- Japan
- Dim Sum
- S.F.
|
Table:
Any number of lines of text. Each line is one row of the table consisting of one or more cells. Each cell starts and ends with a vertical bar '|'. Any spaces at the beginning of a line are ignored.
Notes: •
| *bold* | cells are displayed as table headers. •
| center-spaced | cells are displayed center aligned. •
| right-spaced | cells are displayed right aligned. •
| 2 colspan || cells are displayed as multi-span columns (i.e., a cell with no text spans a column). •
|^| cells with a caret indicate follow-up rows of multi-span rows (this functionality is provided by TablePlugin). •
If a row contains a large amount of text, and you want it to be more readable while editing the table, split the row into multiple text lines by ending each line with a backslash character '\' . •
Table cells wrap automatically as determined by the browser.
|
| *L* | *C* | *R* |
| A2 | 2 | 2 |
| A3 | 3 | 3 |
| multi span |||
| A4-6 | four | four |
|^| five | five |
|^| six | six |
|
L | C | R |
A2 | 2 | 2 |
A3 | 3 | 3 |
multi span |
A4-6 | four | four |
five | five |
six | six |
|
WikiWord Links:
CapitalizedWordsStuckTogether (or WikiWords) will produce a link automatically. Note: In case you want to link to a topic in a different JCuckoo web write Otherweb.TopicName . (The link label is the the name of the web in case the is WebHome, else it is the topic name)
|
WebNotify
Main.TWikiUsers
|
WebNotify
TWikiUsers
|
Forced Links:
You can create a forced internal link by enclosing words in double square brackets.
Note: Text within the brackets may contain optional spaces; the topic name is formed by capitalizing the initial letter and by removing the spaces; for example, [[text formatting FAQ]] links to topic TextFormattingFAQ. You can also refer to a different web and use anchors.
Note: To "escape" double square brackets that would otherwise be a correct link, prefix the leading left square brackets with an exclamation point, that is, begin with ![[....
|
[[wiki syntax]]
[[Main.TWiki users]]
escaped:
![[wiki syntax]]
|
wiki syntax
Main.TWiki users
escaped:
[[wiki syntax]]
|
Specific Links:
Create a link where you can specify the link text and the link reference separately, using nested square brackets like [[reference][text]] . Internal link references (e.g. WikiSyntax) and external link references (e.g. http://TWiki.org/) are supported.
Note: The same Forced Links rules apply for internal link references.
Note: For external link references, you can simply use a space instead of ][ to separate the link URL from the descriptive text.
Note: Anchor names can be added as well, like [[WebHome#MyAnchor][go home]] and [[http://gnu.org/#Action][GNU Action]] .
|
[[WikiSyntax][syntax]]
[[http://gnu.org][GNU]]
[[http://xml.org XML]]
|
syntax
GNU
XML
|
Anchors:
You can define a link reference inside a JCuckoo topic (called an anchor name) and link to that. To define an anchor write #AnchorName at the beginning of a line. The anchor name must be a WikiWord. To link to an anchor name use the [[MyTopic#MyAnchor]] syntax. You can omit the topic name if you want to link within the same topic.
|
[[WikiWord#NotThere]]
[[#MyAnchor][Jump]]
#MyAnchor To here
|
WikiWord#NotThere
Jump
To here
|
Prevent a Link:
Prevent a WikiWord from being linked by prepending it with an exclamation point.
|
!SunOS
|
SunOS
|
Disable Links:
You can disable automatic linking of WikiWords by surrounding text with <noautolink> and </noautolink> tags.
Note: Each tag must be on a line by itself.
Note: This also works for TWiki tables, but only if you add a blank line between the end of the table and the closing </noautolink> tag (known issue of the TablePlugin).
|
<noautolink>
RedHat &
SuSE
</noautolink>
|
RedHat &
SuSE
|
Mailto: Links:
To create 'mailto:' links that have more descriptive link text, specify subject lines or message bodies, or omit the email address, you can write [[mailto:user@domain descriptive text]] .
|
[[mailto:a@z.com Mail]]
[[mailto:?subject=Hi Hi]]
|
Mail
Hi
|
Using HTML
You can use just about any HTML tag without a problem - however, there are a few usability and technical considerations to keep in mind.
HTML and TWiki Usability
- TIP: On collaboration pages, it's preferable NOT to use HTML, and to use TWiki shorthand instead - this keeps the text uncluttered and easy to edit.
- NOTE: TWiki is designed to work with a wide range of browsers and computer platforms, holding to HTML 4.0 and XHTML 1.0 compatibility in the standard installation - adding raw HTML, particularly browser-specific tags (or any other mark-up that doesn't degrade well) will reduce compatibility.
- Recommondations when using HTML:
- Use XHTML 1.0 Transitional syntax
- Do not span a tag over more then one line
- Remove all empty lines. TWiki inserts
<p />
paragraph tags on empty lines, which causes problems if done between tags that do not allow paragraph tags, like for example between table tags.
TWiki HTML Rendering
- TWiki converts shorthand notation to XHTML 1.0 for display. To copy a fully marked-up page, simply view source in your browser and save the contents.
- If you need to save HTML frequently, you may want to check out TWiki:Plugins/GenHTMLAddon - it will "generate a directory containing rendered versions of a set of TWiki pages together with any attached files."
- NOTE: The opening and closing angle brackets -
<...>
- of an HTML tag must be on the same line, or the tag will be broken.
- This feature allows you to enter an unclosed angle bracket - as a greater than or less than symbol - and have it automatically rendered as if you had entered its HTML character,
<
, ex: a < b
- If you're pasting in preformatted HTML text and notice problems, check the file in a text processor with no text wrap. Also, save without hard line breaks on text wrap, in your HTML editing program.
TWiki and JavaScript
You can use JavaScript for your TWiki applications. Since TWiki rendering might interfere with JavaScript code you need to escape it with HTML comments and
<pre>
tags:
<script type="text/javascript">
<!-- Hide JavaScript and <pre> escape TWiki rendering
... put your JavaScript code here...
// Stop hiding and stop </pre> escaping TWiki rendering -->
</script>
Hyperlinks
Being able to create links without any formatting required is a core TWiki feature, made possible with
WikiWords. New TWiki linking rules are a simple extension of the syntax that provide a new set of flexible options.
Internal Links
- GoodStyle is a WikiWord that links to the GoodStyle topic located in the current JCuckoo web.
- NotExistingYet? is a topic waiting to be written. Create the topic by clicking on the ?. (Try clicking, but then, Cancel - creating the topic would wreck this example!)
External Links
-
http://...
, https://...
, ftp://...
, gopher://...
, news://...
, file://...
, telnet://...
and mailto:...@...
are linked automatically.
- Email addresses like
name@domain.com
are linked automatically.
-
[[Square bracket rules]]
let you easily create non-WikiWord links.
- You can also write
[[http://yahoo.com Yahoo home page]]
as an easier way of doing external links with descriptive text for the link, such as Yahoo home page.
TWiki Variables
Variables are names that are enclosed in percent signs
%
that are expanded on the fly.
-
%TOC%
: Automatically generates a table of contents based on headings in a topic - see the top of this page for an example.
-
%WEB%
: The current web, is TWiki.
-
%TOPIC%
: The current topic name, is TextFormattingRules.
-
%ATTACHURL%
: The attachment URL of the current topic. Example usage: If you attach a file to a topic you can refer to it as %ATTACHURL%/image.gif
to show the URL of the file or the image in your text.
-
%INCLUDE{"SomeTopic"}%
: Server side include, includes another topic. The current JCuckoo web is the default web. Example: %INCLUDE{"TWiki.SiteMap"}%
-
%SEARCH{"sushi"}%
: Inline search showing the search result embedded in a topic. FormattedSearch gives you control over formatting, used to create web-based applications.
- TWikiPreferences defines site-wide variables. Among others:
- Line break: Write
%BR%
to start a new line.
- Colored text: Write:
%RED% Red %ENDCOLOR% and %BLUE% blue %ENDCOLOR% colors
to get: Red and blue colors.
- Documentation Graphics: Write:
%H% Help, %T% Tip, %X% Alert
to get: Help, Tip, Alert. For more info see TWikiDocGraphics.
- To "escape" a variable, prefix it with an exclamation point. Write:
!%SOMEVARIABLE%
to get: %SOMEVARIABLE%.
TWikiPlugin Formatting Extensions
Plugins provide additional text formatting capabilities and can extend the functionality of JCuckoo 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%
:
- DefaultPlugin: This plugin can be used to specify some simple custom rendering rules. It also renders depreciated
*_text_*
as bold italic text.
- SpreadSheetPlugin: Add spreadsheet calculation like
"$SUM( $ABOVE() )"
to tables located in JCuckoo topics.
- CommentPlugin: Allows users to quickly post comments to a page without an edit/preview/save cycle.
- EditTablePlugin: Edit TWiki tables using edit fields, date pickers and drop down boxes
- InterwikiPlugin: Link
ExternalSite:Page
text to external sites based on aliases defined in the InterWikis topic
- RenderListPlugin: Render bullet lists in a variety of formats
- SlideShowPlugin: Create web based presentations based on topics with headings.
- SmiliesPlugin: Render smilies as icons, like
:-)
for or :cool:
for
- TablePlugin: Control attributes of tables and sorting of table columns
Check on current Plugin status and settings for this site in
TWikiPreferences.
Common Editing Errors
TWiki formatting rules are fairly simple to use and quick to type. However, there are some things to watch out for, taken from the
TextFormattingFAQ:
- Q: Text enclosed in angle brackets like
<filename>
is not displayed. How can I show it as it is?
- A: The
'<'
and '>'
characters have a special meaning in HTML, they define HTML tags. You need to escape them, so write '<'
instead of '<'
, and '>'
instead of '>'
.
Example: Type 'prog <filename>'
to get 'prog <filename>'
.
- Q: Why is the
'&'
character sometimes not displayed?
- A: The
'&'
character has a special meaning in HTML, it starts a so called character entity, i.e. '©'
is the ©
copyright character. You need to escape '&'
to see it as it is, so write '&'
instead of '&'
.
Example: Type 'This & that'
to get 'This & that'
.
--
TWiki:Main.MikeMannix - 02 Dec 2001
--
TWiki:Main.PeterThoeny - 01 Aug 2004
TWiki Variables
Special text strings expand on the fly to display user data or system info
TWikiVariables are text strings -
%VARIABLE%
- that expand into content whenever a page is opened. When a topic is rendered for viewing,
VARIABLES
are replaced by data, either user-entered, or info automatically generated by TWiki (like the date, or the current username). There are predefined variables, and Preference variables that you configure. You can also define custom variables, with new names and values.
Note: To leave a variable unexpanded, preceed it with an exclamation point, e.g. type
!%TOPIC%
to get %TOPIC%.
Predefined Variables
Most predefined variables return values that were either set in the
lib/twiki.cfg
file, when TWiki was installed, or taken from server info (like current username, or date and time). Many of the variables let you format the appearance of the display results.
- Take the time to thoroughly read through ALL preference variables. If you actively configure your site, review variables periodically. They cover a wide range of functions, and it can be easy to miss the one perfect variable for something you have in mind. For example, see
%INCLUDINGTOPIC%
, %INCLUDE%
, and the mighty %SEARCH%
.
This version of TWiki - Alpha 30 Jul 2004 $Rev: 1701 $ - expands the following variables (enclosed in
%
percent signs):
ATTACHURL -- attachment URL of the current topic
ATTACHURLPATH -- path of the attachment URL of the current topic
BASETOPIC -- base topic where an INCLUDE started
- The name of the topic where a single or nested INCLUDE started - same as
%TOPIC%
if there is no INCLUDE
- Syntax:
%BASETOPIC%
- Related: BASEWEB, INCLUDINGTOPIC, INCLUDE, TOPIC
BASEWEB -- base web where an INCLUDE started
- The web name where the includes started, e.g. the web of the first topic of nested includes. Same as
%WEB%
in case there is no include.
- Syntax:
%BASEWEB%
- Related: BASETOPIC, INCLUDINGWEB, INCLUDE, WEB
DISPLAYTIME -- display time
DISPLAYTIME{"format"} -- formatted display time
- Formatted time - either GMT or Local server time, depending on setting in TWiki.cfg. Same format qualifiers as
%GMTIME%
- Syntax:
%DISPLAYTIME{"format"}%
- Example:
%DISPLAYTIME{"$hou:$min"}%
expands to 09:32
- Related: DISPLAYTIME, GMTIME, SERVERTIME
ENCODE{"string"} -- encodes a string
- Syntax:
%ENCODE{"string"}%
- Supported parameters:
Parameter: | Description: | Default: |
"string" | String to encode | required (can be empty) |
type="entity" | Encode special characters into HTML entities, like a double quote into " | URL encoding |
type="url" | Encode special characters for URL parameter use, like a double quote into %22 | (this is the default) |
- Example:
%ENCODE{"spaced name"}%
expands to spaced%20name
- Related: URLPARAM
GMTIME -- GM time
GMTIME{"format"} -- formatted GM time
- Syntax:
%GMTIME{"format"}%
- Supported variables:
Variable: | Unit: | Example |
$seconds | seconds | 59 |
$minutes | minutes | 59 |
$hours | hours | 23 |
$day | day of month | 31 |
$wday | day of the Week (Sun, Mon, Tue, Wed, Thu, Fri, Sat) | Thu |
$month | month in ISO format | Dec |
$mo | 2 digit month | 12 |
$year | 4 digit year | 1999 |
$ye | 2 digit year | 99 |
$tz | either "GMT" (if set to gmtime), or "Local" (if set to servertime) | GMT |
$iso | ISO format timestamp | 2024-04-20T09:32Z |
$rcs | RCS format timestamp | 2024/04/20 09:32:55 |
$http | E-mail & http format timestamp | Sat, 20 Apr 2024 09:32:55 GMT |
- Variables can be shortened to 3 characters
- Example:
%GMTIME{"$day $month, $year - $hour:$min:$sec"}%
expands to 20 Apr, 2024 - 09:32:55
- Related: DISPLAYTIME, GMTIME, SERVERTIME
HOMETOPIC -- home topic in each web
HTTP_HOST -- environment variable
ICON{"type"} -- small icon of common attachment types
- Small 16x16 pixel icon of common attachment types. Specify file type only, file name, or full path name
- Syntax:
%ICON{"type"}%
- Samples:
bmp
, doc
, gif
, hlp
, html
, mp3
, pdf
, ppt
, txt
, xls
, xml
, zip
- Example:
%ICON{"pdf"}%
expands to
- Related: TWikiPreferences, FileAttachments, TWikiDocGraphics
INCLUDE{"page"} -- include other topics or web pages
- Syntax:
%INCLUDE{"page" ...}%
- Supported parameters:
Parameter: | Description: | Default: |
"SomeTopic" | The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}% | |
"Web.Topic" | A topic in another web, i.e. %INCLUDE{"TWiki.SiteMap"}% | |
"http://..." | A full qualified URL, i.e. %INCLUDE{"http://twiki.org/"}% | |
pattern="..." | A RegularExpression pattern to include a subset of a topic or page | none |
rev="1.2" | Include a previous topic revision; N/A for URLs | top revision |
warn="off" | Warn if topic include fails: Fail silently (if off ); output default warning (if set to on ); else, output specific text (use $topic for topic name) | %INCLUDE- WARNING% preferences setting |
- Related: BASETOPIC, BASEWEB, INCLUDINGTOPIC, INCLUDINGWEB, IncludeTopicsAndWebPages
INCLUDINGTOPIC -- name of topic that includes current topic
- The name of the topic that includes the current topic - same as
%TOPIC%
in case there is no include
- Syntax:
%INCLUDINGTOPIC%
- Related: BASETOPIC, INCLUDINGWEB, INCLUDE, TOPIC
INCLUDINGWEB -- web that includes current topic
- The web name of the topic that includes the current topic - same as
%WEB%
if there is no INCLUDE.
- Syntax:
%INCLUDINGWEB%
- Related: BASEWEB, INCLUDINGTOPIC, INCLUDE, WEB
MAINWEB -- name of Main web
METASEARCH -- special search of meta data
- Syntax:
%METASEARCH{...}%
- Supported parameters:
Parameter: | Description: | Default: |
type="topicmoved" | What sort of search is required? "topicmoved" if search for a topic that may have been moved "parent" if searching for topics that have a specific parent i.e. its children | required |
web="%WEB%" | Wiki web to search: A web, a list of webs separated by whitespace, or all webs. | required |
topic="%TOPIC%" | The topic the search relates to | required |
title="Title" | Text that is prepended to any search results | required |
- Example:
%METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%
- Example: You may want to use this in WebTopicViewTemplate and WebTopicNonWikiTemplate:
%METASEARCH{type="parent" web="%WEB%" topic="%TOPIC%" title="Children: "}%
- Related: SEARCH
NOTIFYTOPIC -- name of the notify topic
PUBURL -- the base URL of attachments
- Syntax:
%PUBURL%
- Expands to:
http://jcuckoo.sourceforge.net/twiki/pub
- Example: You can refer to a file attached to another topic with
%PUBURL%/%WEB%/OtherTopic/image.gif
- Related: ATTACHURL, PUBURLPATH, SCRIPTURL, FileAttachments
PUBURLPATH -- the base URL path of attachments
REMOTE_ADDR -- environment variable
REMOTE_PORT -- environment variable
REMOTE_USER -- environment variable
SCRIPTURL -- script URL of JCuckoo
- Syntax:
%SCRIPTURL%
- Expands to:
http://jcuckoo.sourceforge.net/cgi-bin
- Example: To get the authenticated version of current topic write
%SCRIPTURL%/viewauth%SCRIPTSUFFIX%/%WEB%/%TOPIC%
which expands to http://jcuckoo.sourceforge.net/cgi-bin/viewauth/TWiki/TWikiVariables
- Related: PUBURL, SCRIPTSUFFIX, SCRIPTURLPATH
SCRIPTURLPATH -- script URL path of JCuckoo
SCRIPTSUFFIX -- script suffix
- Some JCuckoo installations require a file extension for CGI scripts like
.pl
or .cgi
- Syntax:
%SCRIPTSUFFIX%
- Expands to:
- Related: SCRIPTURL
SEARCH{"text"} -- search content
- Inline search, shows a search result embedded in a topic
- Syntax:
%SEARCH{"text" ...}%
- Supported parameters: [1]
Parameter: | Description: | Default: |
"text" | Search term. Is a keyword search, literal search or regular expression search, depending on the type parameter. SearchHelp has more | required |
search="text" | (Alternative to above) | N/A |
web="Name" web="Main, Know" web="all" | Wiki web to search: A web, a list of webs separated by comma, or all webs. [2] | Current web |
topic="WebPreferences" topic="*Bug" | Limit search to topics: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. | All topics in a web |
excludetopic="Web*" excludetopic="WebHome, WebChanges" | Exclude topics from search: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. | None |
type="keyword" type="literal" type="regex" | Do a keyword search like soap "web service" -shampoo ; a literal search like web service ; or RegularExpression search like soap;web service;!shampoo | %SEARCHVAR- DEFAULTTYPE% preferences setting (literal) |
scope="topic" scope="text" scope="all" | Search topic name (title); the text (body) of topic; or all (both) | "text" |
order="topic" order="created" order="modified" order="editby" order= "formfield(name)" | Sort the results of search by the topic names, topic creation time, last modified time, last editor, or named field of TWikiForms. The sorting is done web by web; in case you want to sort across webs, create a formatted table and sort it with TablePlugin's initsort | Sort by topic name |
limit="all" limit="16" | Limit the number of results returned. This is done after sorting in case order is specified | All results |
reverse="on" | Reverse the direction of the search | Ascending search |
casesensitive="on" | Case sensitive search | Ignore case |
nosummary="on" | Show topic title only | Show topic summary |
bookview="on" | BookView search, e.g. show complete topic text | Show topic summary |
nosearch="on" | Suppress search string | Show search string |
noheader="on" | Suppress search header Topics: Changed: By: | Show search header |
nototal="on" | Do not show number of topics found | Show number |
header="..." format="..." | Custom format results: see FormattedSearch for usage, variables & examples | Results in table |
expandvariables="on" | Expand variables before applying a FormattedSearch on a search hit. Useful to show the expanded text, e.g. to show the result of a SpreadSheetPlugin %CALC{}% instead of the formula | Raw text |
multiple="on" | Multiple hits per topic. Each hit can be formatted. The last token is used in case of a regular expression ";" and search | Only one hit per topic |
separator=", " | Line separator between hits | Newline "$n" |
- Example:
%SEARCH{"wiki" web="Main" scope="topic"}%
- Example with format:
%SEARCH{"FAQ" scope="topic" nosearch="on" nototal="on" header="| *Topic: * | *Summary: * |" format="| $topic | $summary |"%
(displays results in a table with header - details)
- If the TWiki:Plugins.TablePlugin is installed, you may set a
%TABLE{}%
variable just before the %SEARCH{}%
to alter the output of a search. Example: %TABLE{ tablewidth="90%" }%
- Related: METASEARCH, TOPICLIST, WEBLIST, FormattedSearch
- [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
SERVERTIME -- server time
SERVERTIME{"format"} -- formatted server time
- Same format qualifiers as
%GMTIME%
- Syntax:
%SERVERTIME{"format"}%
- Example:
%SERVERTIME{"$hou:$min"}%
expands to 09:32
- Related: DISPLAYTIME, GMTIME, SERVERTIME
SPACEDTOPIC -- topic name, spaced and encoded
- The current topic name with added spaces, for regular expression search of Ref-By
- Syntax:
%SPACEDTOPIC%
- Expands to:
TWiki%20*Variables
- Related: TOPIC
STARTINCLUDE -- start position of topic text if included
- If present in included topic, start to include text from this location up to the end, or up to the location of the
%STOPINCLUDE%
variable. A normal view of the topic shows everyting exept the %STARTINCLUDE%
variable itself.
- Syntax:
%STARTINCLUDE%
- Related: INCLUDE, STOPINCLUDE
STATISTICSTOPIC -- name of statistics topic
STOPINCLUDE -- end position of topic text if included
- If present in included topic, stop to include text at this location and ignore the remaining text. A normal view of the topic shows everyting exept the
%STOPINCLUDE%
variable itself.
- Syntax:
%STOPINCLUDE%
- Related: INCLUDE, STARTINCLUDE
TOC -- table of contents of current topic
TOC{"Topic"} -- table of contents
- Syntax:
%TOC{"SomeTopic" ...}%
- Table of Contents. Shows a TOC that is generated automatically based on headings of a topic. Headings in WikiSyntax (
"---++ text"
) and HTML ("<h2>text</h2>"
) are taken into account. Any heading text after "!!"
is excluded from the TOC; for example, write "---+!! text"
if you do not want to list a header in the TOC
- Supported parameters:
Parameter: | Description: | Default: |
"TopicName" | topic name | Current topic |
web="Name" | Name of web | Current web |
depth="2" | Limit depth of headings shown in TOC | 6 |
title="Some text" | Title to appear at top of TOC | none |
- Example:
%TOC{depth="2"}%
- Example:
%TOC{"TWikiDocumentation" web="TWiki" title="Contents:"}%
- Related: TOC
TOPIC -- name of current topic
TOPICLIST{"format"} -- topic index of a web
- The "format" defines the format of one topic item. It may include variables: The
$name
variable gets expanded to the topic name; the $web
variable gets expanded to the name of the web.
- Syntax:
%TOPICLIST{"format" ...}%
- Supported parameters:
Parameter: | Description: | Default: |
"format" | Format of one line, may include $name and $web variables | "$name" |
format="format" | (Alternative to above) | "$name" |
separator=", " | line separator | "\n" (new line) |
web="Name" | Name of web | Current web |
- Example:
%TOPICLIST{" * $web.$name"}%
creates a bullet list of all topics
- Example:
%TOPICLIST{separator=", "}%
creates a comma separated list of all topics
- Example:
%TOPICLIST{" <option>$name</option>"}%
creates an option list (for drop down menus)
- Related: SEARCH, WEBLIST
TWIKIWEB -- name of TWiki documentation web
- The web containing all documentation and site-wide preference settings for JCuckoo
- Syntax:
%TWIKIWEB%
- Expands to:
TWiki
- Related: MAINWEB
URLPARAM{"name"} -- get value of a URL parameter
- Returns the value of a URL parameter. Note that there is a risk that this variable could be misused for cross-scripting
- Syntax:
%URLPARAM{"name"}%
- Supported parameters:
Parameter: | Description: | Default: |
"name" | The name of a URL parameter | required |
default="..." | Default value in case parameter is empty or missing | empty string |
newline="<br />" | Convert newlines in textarea to other delimiters | no conversion |
encode="entity" | Encode special characters into HTML entities, like a double quote into " . This is needed if text is put into an HTML form field | no encoding |
encode="url" | Encode special characters for URL parameter use, like a double quote into %22 | no encoding |
multiple="on" multiple="[[$item]]" | If set, gets all selected elements of a <select multiple="multiple"> tag. A format can be specified, with $item indicating the element, e.g. multiple="Option: $item" | first element |
separator=", " | Separator between multiple selections. Only relevant if multiple is specified | "\n" (new line) |
- Example:
%URLPARAM{"skin"}%
returns print
for a .../view/TWiki/TWikiVariables?skin=print
URL. Test this:
- Related: SEARCH, FormattedSearch
USERNAME -- your login username
VAR{"NAME" web="Web"} -- get a preference value from another web
- Syntax:
%VAR{"NAME" web="Web"}%
- Example: To get
%WEBBGCOLOR%
of the Main web write %VAR{"WEBBGCOLOR" web="Main"}%
, which expands to #FFFFC0
- Related: WEBPREFSTOPIC
WEB -- name of current web
WEBLIST{"format"} -- index of all webs
- List of all webs. Hidden webs are excluded, e.g. webs with a
NOSEARCHALL=on
preference variable. The "format"
defines the format of one web item. The $name
variable gets expanded to the name of the web, $qname
gets expanded to double quoted name, $marker
to marker
where web matches selection
.
- Syntax:
%WEBLIST{"format" ...}%
- Supported parameters:
Parameter: | Description: | Default: |
"format" | Format of one line, may include $name variable | "$name" |
format="format" | (Alternative to above) | "$name" |
separator=", " | line separator | "\n" (new line) |
webs="public" | comma sep list of Web, public expands to all non-hidden | "public" |
marker="selected" | Text for $marker where item matches selection , otherwise equals "" | "selected" |
selection="%WEB%" | Current value to be selected in list | section="%WEB%" |
- Example:
%WEBLIST{" * [[$name.WebHome]]"}%
creates a bullet list of all webs.
- Example:
%WEBLIST{"<option $marker value=$qname>$name</option>" webs="Trash,public" selection="TWiki" separator=" "}%
Dropdown of all public Webs + Trash Web, current Web highlighted.
- Related: TOPICLIST, SEARCH
WEBPREFSTOPIC -- name of web preferences topic
WIKIHOMEURL -- site home URL
- The base URL of JCuckoo, is the link of the Home icon in the upper left corner, defined in TWiki.cfg
- Syntax:
%WIKIHOMEURL%
- Expands to:
http://your.domain.com/twiki
- Related: WIKITOOLNAME
WIKINAME -- your Wiki username
WIKIPREFSTOPIC -- name of site-wide preferences topic
WIKITOOLNAME -- name of your TWiki site
WIKIUSERNAME -- your Wiki username with web prefix
- Your %WIKINAME% with Main web prefix, useful to point to your JCuckoo home page
- Syntax:
%WIKIUSERNAME%
- Expands to:
Main.TWikiGuest
, renders as TWikiGuest
- Related: REMOTE_USER, USERNAME, WIKINAME
WIKIUSERSTOPIC -- name of topic listing all registers users
WIKIVERSION -- the version of the installed TWiki engine
- Syntax:
%WIKIVERSION%
- Expands to:
Alpha 30 Jul 2004 $Rev: 1701 $
- Related: WIKITOOLNAME
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: |
%ALLOWTOPICCHANGE% |
(any topic) |
List of users and groups who are allowed to change 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) |
%ALLOWWEBCHANGE% |
WL |
List of users and groups who are allowed to change topics in the JCuckoo web. (More in TWikiAccessControl) |
%ALLOWWEBRENAME% |
WL |
List of users and groups who are allowed to rename topics in the JCuckoo web. (More in TWikiAccessControl) |
%ATTACHLINKBOX% |
SL , UL |
Default state of the link check box in the attach file page. Check box is initially checked if value is set to CHECKED , unchecked if empty. If checked, a link is created to the attached file at the end of the topic. Value is: |
%DENYTOPICCHANGE% |
(any topic) |
List of users and groups who are not allowed to change the current topic. (More in TWikiAccessControl) |
%DENYTOPICRENAME% |
(any topic) |
List of users and groups who are not allowed to rename the current topic. (More in TWikiAccessControl) |
%DENYWEBCHANGE% |
WL |
List of users and groups who are not allowed to change topics in the JCuckoo web. (More in TWikiAccessControl) |
%DENYWEBRENAME% |
WL |
List of users and groups who are not allowed to rename topics in the JCuckoo web. (More in TWikiAccessControl) |
%DONTNOTIFYCHECKBOX% |
SL , UL |
Default state of the "Minor Changes, Don't Notify" (DontNotify) check box in preview. Check box is initially checked if Set DONTNOTIFYCHECKBOX = checked="checked" , or unchecked if empty. Value is: |
%EDITBOXHEIGHT% |
SL , UL |
Vertical size of edit box, is 50 |
%EDITBOXWIDTH% |
SL , UL |
Horizontal size of edit box, is 70 |
%EDITBOXSTYLE% |
SL , UL |
Style of text edit box. Set to width: 99% for full window width (default; overwrites the EDITBOXWIDTH setting), or width: auto to disable. Value is: width: 99% |
%FINALPREFERENCES% |
SL , WL |
List of preferences that are not allowed to be overridden by next level preferences |
%HTTP_EQUIV_ON_EDIT% |
SL , UL |
http-equiv meta tags for edit script. |
%HTTP_EQUIV_ON_PREVIEW% |
SL , UL |
http-equiv meta tags for preview script. |
%HTTP_EQUIV_ON_VIEW% |
SL |
http-equiv meta tags for view, rdiff, attach, search* scripts. |
%NEWTOPICBGCOLOR% |
SL , UL |
Background color of non existing topic. ( UL needs authentication for topic views ) |
%NEWTOPICFONTCOLOR% |
SL , UL |
Font color of non existing topic. ( UL needs authentication for topic views ) |
%NOSEARCHALL% |
WL |
Exclude web from a web="all" search (set variable to on for hidden webs) |
%RELEASEEDITLOCKCHECKBOX% |
SL , UL |
Default state of the "Release edit lock" (UnlockTopic) check box in preview. Checkbox is initially checked if Set RELEASEEDITLOCKCHECKBOX = checked="checked" , or unchecked if empty. If checked, make sure to click on Edit to do more changes; do not go back in your browser to the edit page, or you risk that someone else will edit the topic at the same time! Value is: |
%WEBBGCOLOR% |
WL |
Background color of web |
%WEBCOPYRIGHT% |
SL , WL |
Copyright notice (bottom right corner of topics) |
%WEBTOPICLIST% |
WL |
Common links of web (second line of topics) |
%WIKIWEBLIST% |
SL |
List of JCuckoo webs (in upper right corner of topics) |
%WIKIWEBMASTER% |
SL |
Webmaster email address (sender of email notifications) , is rumcajs_78@users.sourceforge.net |
Note: There are some more useful variables defined in the
TWikiPreferences like
%BR%
for line break, colors like
%RED%
for colored text and small icons like
%H%
for a
Help icon.
Setting Preferences
- The syntax for Preferences Variables is the same anywhere in TWiki (on its own TWiki bullet line, including nested bullets):
[multiple of 3 spaces] * [space] Set [space] VARIABLENAME [space] = [value]
Examples:
-
Set VARIABLENAME = value
Creating Custom Variables
- You can add your own Preference Variables for us across an entire site or a single web, using the standard Preferences syntax. Whatever you include in your Variable will be expanded on display, exactly as if it had been entered directly. You can place formatted text, page links, image paths.
Example: Create a custom logo variable the TWiki web
- To place a logo anywhere in a web by typing
%MYLOGO%
, define the Variable on the web's WebPreferences page, and upload a logo file, ex: mylogo.gif
. You can upload by attaching the file to WebPreferences, or, to avoid clutter, to any other topic in the same web, ex: LogoTopic
:
-
Set MYLOGO = %PUBURL%/TWiki/LogoTopic/mylogo.gif
--
TWiki:Main.PeterThoeny - 09 May 2004
--
TWiki:Main.MikeMannix - 12 May 2002
File Attachments
Each topic can have one or more files of any type attached to it by using the Attach screen to upload (or download) files from your local PC. Attachments are stored under revision control: uploads are automatically backed up; all previous versions of a modified file can be retrieved.
What Are Attachments Good For?
File Attachments can be used to create powerful customized groupware solutions, like file sharing and document management systems, and quick Web page authoring.
Document Management System
- 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 web and topic-level access control; create a central reference library that's easy to share with an user group spread around the world.
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 link to on a page) and place them on a single page, or use them across a web, or site-wide.
- NOTE: You can also add graphics - any files - directly, typically by FTP upload. This requires FTP access, and may be more convenient if you have a large number of files to load. FTP-ed files can't be managed using browser-based Attachment controls. You can use your browser to create TWikiVariables shortcuts, like this %H% = .
Uploading Files
- Click on the
Attach
link at the bottom of the page. The Attach
screen lets you browse for a file, add a comment, and upload it. The uploaded file will show up in the File Attachment table.
- NOTE: The topic must already exist. It is a two step process if you want to attach a file to a non-existing topic; first create the topic, then add the file attachment.
- Any type of file can be uploaded. Some files that might pose a security risk are renamed, ex:
*.php
files are renamed to *.php.txt
so that no one can place code that would be read in a .php file.
- 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.
- TWiki can limit the file size. This is defined by the
%ATTACHFILESIZELIMIT%
variable of the TWikiPreferences, currently set at 10000 KB.
- It's not recommended to upload files greater than a few hundred K through a browser. Large files can be extremely slow-loading, and often time out. Use an FTP site for large file uploads.
Downloading Files
- NOTE: There is no access control on individual attachments. If you need control over single files, create a separate topic per file and set topic-level access restrictions for each.
Moving Attachment Files
An attachment can be moved between topics.
- Click
Manage
on the Attachment to be moved.
- On the control screen, select the new web and/or topic.
- Click
Move
. The attachment and its version history are moved. The original location is stored as topic Meta Data.
Deleting Attachments
Move unwanted Attachments to web
Trash
, topic
TrashAttachment
.
Linking to Attached Files
- To reference an attachment located in another topic, enter:
-
%PUBURL%/%WEB%/OtherTopic/Sample.txt
(if it's within the same web)
-
%PUBURL%/Otherweb/OtherTopic/Sample.txt
(if it's in a different web)
- Attached HTML files and text files can be inlined in a topic. Example:
-
Attach
file: Sample.txt
-
Edit
topic and write text: %INCLUDE{"%ATTACHURL%/Sample.txt"}%
- GIF, JPG and PNG images can be attached and shown embedded in a topic. Example:
-
Attach
file: Smile.gif
-
Edit
topic and write text: %ATTACHURL%/Smile.gif
-
Preview
: text appears as , 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.
File Attachment Controls
Clicking on a
Manage
link takes you to a new page that looks like this:
- 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.
TWiki Forms
Form-based input in topics, with name/value pairs stored as Meta Data variables; choose one of multiple forms per web & topic
Overview
By adding form-based input to freeform content, you can structure topics with unlimited, easily searchable categories. When forms are enabled for a web and selected in a topic, a single form appears in edit mode, and the contents are rendered as a table when viewed on the display page. You can define unlimited forms per web. For each topic, you can select a template if more than one is defined, or remove forms entirely. Form input values are stored as
TWikiMetaData; all data is saved.
Form Templates replace TWikiCategoryTables from the 01-Dec-2000 version of TWiki. - see
#FormsVsCategoryTables
Defining a Form Template
A Form Template is simply a page containing your form, defined as a table where each row is one form field.
Form Template Elements
- 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 freeform TEXTAREA) that categorizes the content (replaces category table)
- Within a form-enabled web, individual topics can have a form or no form
- form field - a named item in a form (replaces category item name)
- field type - selects the INPUT type:
Input type | Type field | Size field | Value field |
A one-line text field | text | text box width in number of characters | (unused) |
A text box; size is 40x10 (columns x rows) | textarea | columns x rows, e.g. 40x6 | (unused) |
Drop-down menu or scrollable box | label | 1 for drop down, 2 and up for scrollable box | comma list of options |
One or more checkboxes | checkbox | number of checkboxes per line | comma list of checkbox labels |
One or more checkboxes, plus Set and Clear buttons | checkbox+buttons | (same) | (same) |
One or more radio buttons | radio | number of radio buttons per line | comma list of checkbox labels |
Read-only label text | label | 1 | (unused) |
- 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
- Create a new topic with your form name:
YourForm
, ExpenseReport
, InfoCategory
, RecordReview
, whatever you need.
- Create a TWiki table, with each column head representing one element of an entry field:
Name
, Type
, Size
, Values
, and Tooltip message
(see sample below).
- For each field, fill in a new line; for the type of field, select from the list.
- Save the topic (you can later choose to enable/disable individual forms).
Example: WebForm
| *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
Forms can also be defined by using form templates that retrieve field values from one or more separate topics:
- A
FormTemplate
topic defines the Form, ex: YourFormTemplate
.
- For each field that has a value list - select, radio, checkbox - can use separate topic to define the available values.
Example: WebFormTemplate
- Know.WebFormTemplate main definition:
Leave the Values
field blank.
- Know.TopicClassification field value definition:
- Implementation Notes: This format allows you to define field items with or without WikiNames, depending on your needs.
- Topics can be protected in the usual manner, using TWikiAccessControl, to limit who can change the form template and/or individual value lists.
-
[[...]]
links can be used to force a link (at present, the [[...][...]]
format is not supported).
- The
Tooltip message
column is used as a tooltip for the field name (only if field name is a WikiName) - you only see the tooltip In edit.
- The first item in the list is the default item. Alternative initial values can be set in a topic template, like
WebTopicEditTemplate
, with 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.
Including Forms in New Topics
- 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.
Setting Up Multiple Form Options
- The optional
WEBFORMS
variable defines alternative forms that can be selected by pressing Change in edit mode.
- A topic template can use any form.
- 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 Data Storage
The form topic name, fields and values are stored as
TWikiMetaData - the order of the field/value pairs is the same as in the template.
Using Form Data
TWikiForms accept user-input data, stored as
TWikiMetaData. Meta data also contains program-generated info about changes, attachments, etc. To find, format and display form and other meta data, see
TWikiMetaData,
SEARCH
and
METASEARCH
variables in
TWikiVariables, and
TWiki Formatted Search for various options.
Main Changes from Category Tables
The Form Template system is a more powerful, flexible replacement for the original TWikiCategoryTable. Data from existing category tables can be imported directly.
Form Templates | Category Tables |
defined in topics | defined in templates |
many forms per web | one table per web |
saved as Meta Data | saved as HTML |
Change & Add Form buttons | UseCategory radio button |
Importing Category Table Data
On upgrading from the previous TWiki, a Form Template topic has to be built for each web that used a Category Table, recreating the fields and values from the old
twikicatitems.tmpl
. The replacement Form Template must be set as the first item in the
WebPreferences variable
WEBFORMS
. If missing, pages will display, but attempting to edit results in an error message.
The new Form Template system should work with old Category Table data with no special conversion. Data is assigned to Meta variables the first time an imported topic is edited and saved in the new system.
NOTE: If things aren't working correctly, there may be useful entries in
data/warning.txt
.
--
TWiki:Main.JohnTalintyre - 16 Aug 2001
--
TWiki:Main.MikeMannix - 05 Jan 2002
--
TWiki:Main.PeterThoeny - 25 Apr 2004
TWiki Templates
Definition of the templates used to render all HTML pages displayed in TWiki
Overview
The new modular template system offers flexible, easy control over the layout of all TWiki pages. The master template approach groups parts that are shared by several templates - like headers and footers - in a common file. Special variables allow individual layouts to include parts from a master template - variables are mixed with regular HTML markup for template-specific content. Templates are used to define
page layout, and also to supply
default content for new pages.
Major changes from the previous template system
Where the old templates were each complete HTML documents, the new templates are defined using variables to include template parts from a master file. You can now change one instance of a common element to update all occurrences; previously, every affected template had to be updated. This simplifies the conversion of templates into XHTML format, and provides a more versatile solution for templates and for
TWikiSkins. The new system:
- separates a set of common template parts into a base template that is included by all of the related templates;
- defines common variables, like a standard separator (ex: "|"), in the base template;
- defines variable text in the individual templates and passes it back to the base template.
How Template Variables Work
- Special template directives (or preprocessor commands) are embedded in normal templates.
- All template preprocessing is done in
&TWiki::Store::readTemplate()
so that the caller simply gets an expanded template file (the same as before).
- Directives are of the form
%TMPL:<key>%
and %TMPL:<key>{"attr"}%
.
- Directives:
-
%TMPL:INCLUDE{"file"}%
: Includes a template file. The template directory of the current web is searched first, then the templates root (twiki/templates
).
-
%TMPL:DEF{"var"}%
: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
-
%TMPL:END%
: Ends variable definition.
-
%TMPL:P{"var"}%
: Prints a previously defined variable.
- Variables live in a global name space: there is no parameter passing.
- Two-pass processing lets you use a variable before or after declaring it.
- Templates and TWikiSkins work transparently and interchangeably. For example, you can create a skin that overloads only the
twiki.tmpl
master template, like twiki.print.tmpl
, that redefines the header and footer.
- Use of template directives is optional: templates work without them.
- NOTE: Template directives work only for templates: they do not get processed in topic text.
Types of Template
There are three types of template:
- Master Template: Stores common parts; included by other templates
- HTML Page Templates: Defines the layout of JCuckoo pages
- Template Topics: Defines default text when you create a new topic
Master Templates
Common parts, appearing in two or more templates, can be defined in a master template and then shared by others:
twiki.tmpl
is the default master template.
Template variable: | Defines: |
%TMPL:DEF{"sep"}% | "|" separator |
%TMPL:DEF{"htmldoctype"}% | Start of all HTML pages |
%TMPL:DEF{"standardheader"}% | Standard header (ex: view, index, search) |
%TMPL:DEF{"simpleheader"}% | Simple header with reduced links (ex: edit, attach, oops) |
%TMPL:DEF{"standardfooter"}% | Footer, excluding revision and copyright parts |
%TMPL:DEF{"oops"}% | Skeleton of oops dialog |
HTML Page Templates
JCuckoo uses HTML template files for all actions, like topic view, edit, and preview. This allows you to change the look and feel of all pages by editing just a few template files.
Templates are in the
twiki/templates
directory. As an example,
twiki/templates/view.tmpl
is the template file for the
twiki/bin/view
script. Templates can be overloaded by individual webs. The following search order applies:
-
twiki/templates/$webName/$scriptName.tmpl
-
twiki/templates/$scriptName.tmpl
-
$webName
is the name of the web (ex: Main
)
-
$scriptName
is the script (ex: view
).
NOTE: TWikiSkins can be defined to overload the standard templates.
Special variables are used in templates, especially in
view
, to display
meta data.
Template Topics
Template topics define the default text for new topics. There are three types of template topic:
All template topics are located in the TWiki web. The
WebTopicEditTemplate can be overloaded. When you create a new topic, TWiki locates a topic to use as a content template according to the following search order:
- A topic name specified by the
templatetopic
CGI parameter.
- WebTopicEditTemplate in the current web
- WebTopicEditTemplate in the TWiki web
Edit Template Topics and Variable Expansion
The following variables get expanded when a user creates a new topic based on a template topic:
Variable: | Description: |
%DATE% | Current date, e.g. 20 Apr 2024 |
%USERNAME% | Login name, e.g. jsmith |
%WIKINAME% | WikiName of user, e.g. JohnSmith |
%WIKIUSERNAME% | User name, e.g. Main.JohnSmith |
%URLPARAM{"name"}% | Value of a named URL parameter |
%NOP% | A no-operation variable that gets removed. Useful to prevent a SEARCH from hitting an edit template topic; also useful to escape a variable like %URLPARAM%NOP%{...}% |
%NOP{ ... }% | A no-operation text that gets removed. Useful to write-protect an edit template topic, but not the topics based this template topic. See notes below. Example: %NOP{ * Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup }% |
Notes:
- Unlike other variables,
%NOP{ ... }%
can span multiple lines.
- The scan for the closing
}%
pattern is "non-greedy", that is, it stops at the first occurance. That means, you need to escape variables with parameters located inside %NOP{ ... }%
: Insert a %NOP%
between }
and %
. Silly example: %NOP{ %GMTIME{"$year"}%NOP%% }%
.
All other variables are unchanged, e.g. are carried over "as is" into the new topic.
Template Topics in Action
Here is an example for creating new topics based on a specific template topic:
The above form asks for a topic name. A hidden input tag named
templatetopic
specifies
ExampleTopicTemplate as the template topic to use. Here is the HTML source of the form:
<form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%"}%/">
* New example topic:
<input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
<input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
<input type="hidden" name="topicparent" value="%TOPIC%" />
<input type="hidden" name="onlywikiname" value="on" />
<input type="hidden" name="onlynewtopic" value="on" />
<input type="submit" value="Create" />
(date format is <nop>YYYYxMMxDD)
</form>
The
edit
scipt understands the following parameters, typically supplied by HTML input fields:
Parameter: | Description: |
topic | Name of topic to create. Can be set in a text field, or is set programmatically (e.g. with a sequential number) |
onlywikiname | If set, TWiki will complain if the topic name is not a WikiWord |
onlynewtopic | If set, TWiki will complain if a topic of the same name already exists |
templatetopic | The name of the template topic, e.g. topic used to copy the initial content |
topicparent | Sets the parent topic |
TopicClassification | Assuming the template topic has a form with a field called "TopicClassification", it will set the value of the field |
anyname | Any parameter can passed to the new topic; if the template topic contains %URLPARAM{"anyname"}% , it will be replaced by its value |
TIP: You can use the
%WIKIUSERNAME%
and
%DATE%
variables in your topic templates to include the signature of the person creating a new topic. The variables are expanded into fixed text when a new topic is created. The standard signature is:
-- %WIKIUSERNAME% - %DATE%
Templates by Example
Attached is an example of an oops based template
oopsbase.tmpl
and an example oops dialog
oopstest.tmpl
based on the base template. %A%
NOTE: This isn't the release version, just a quick, simple demo.
Base template oopsbase.tmpl
The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing
%TMPL:P{"sep"}%
%TMPL:DEF{"sep"}% | %TMPL:END%
<html>
<head>
<title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title>
<base href="%SCRIPTURL%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%">
<meta name="robots" content="noindex">
</head>
<body bgcolor="#FFFFFF">
<table width="100%" border="0" cellpadding="3" cellspacing="0">
<tr>
<td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%">
<a href="%WIKIHOMEURL%">
<img src="%PUBURLPATH%/wikiHome.gif" border="0"></a>
</td>
<td>
<b>%WIKITOOLNAME% . %WEB% . </b><font size="+2">
<B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font>
</td>
</tr>
<tr bgcolor="%WEBBGCOLOR%">
<td colspan="2">
%TMPL:P{"webaction"}%
</td>
</tr>
</table>
--- ++ %TMPL:P{"heading"}%
%TMPL:P{"message"}%
<table width="100%" border="0" cellpadding="3" cellspacing="0">
<tr bgcolor="%WEBBGCOLOR%">
<td valign="top">
Topic <b>%TOPIC%</b> . {
%TMPL:P{"topicaction"}%
}
</td>
</tr>
</table>
</body>
|
Test template oopstest.tmpl
Each oops template basically just defines some variables and includes the base template that does the layout work.
%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END%
%TMPL:DEF{"webaction"}% test =webaction= %TMPL:END%
%TMPL:DEF{"heading"}%
Test heading %TMPL:END%
%TMPL:DEF{"message"}%
Test =message=. Blah blah blah blah blah blah blah blah blah blah blah...
* Some more blah blah blah blah blah blah blah blah blah blah...
* Param1: %PARAM1%
* Param2: %PARAM2%
* Param3: %PARAM3%
* Param4: %PARAM4%
%TMPL:END%
%TMPL:DEF{"topicaction"}%
Test =topicaction=:
[[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}%
[[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END%
%TMPL:INCLUDE{"oopsbase"}%
|
Sample screen shot of oopstest.tmpl
With URL:
.../bin/oops/Sandbox/TestTopic2?template=oopstest¶m1=WebHome¶m2=WebNotify
Known Issues
- A drawback of referring to a master template is that you can only test a template from within TWiki, where the include variables are resolved. In the previous system, each template was a structurally complete HTML document with a
.tmpl
filename extension - it contained unresolved %VARIABLES%
, but could still be previewed directly in a browser.
--
TWiki:Main.PeterThoeny - 25 Apr 2004
--
TWiki:Main.MikeMannix - 14 Sep 2001
--
TWiki:Main.DavidLeBlanc - 11 Mar 2002
TWiki Skins
Skins overlay regular templates with alternate header/footer layouts; topic text is not affected
Overview
Skins are customized
TWikiTemplates files. You can use skins to change the look of a JCuckoo topic, for example, the layout of the header and footer. Rendered text between header and footer does
not change. You can also use skins to define an alternate view, like a view optimized for printing.
Defining Skins
Skin files are located in the
twiki/templates
directory and are named with the syntax:
<scriptname>.<skin>.tmpl
. For example, the
Printable skin for the
view
template is
view.print.tmpl
.
Use the existing
TWikiTemplates (like
view.tmpl
) or skin files as a base for your own skin, name it for example
view.myskin.tmpl
.
Variables in Skins
You can use
template variables,
TWikiVariables, and other predefined variables to compose your skins. Some commonly used variables in skins:
Variable: | Expanded to: |
%WIKILOGOURL% | Link of page logo |
%WIKILOGOIMG% | Image URL of page logo |
%WIKILOGOALT% | Alt text of page logo |
%WEBBGCOLOR% | Web specific background color, defined in the WebPreferences |
%WIKITOOLNAME% | The name of your TWiki site |
%SCRIPTURL% | The script URL of TWiki |
%SCRIPTSUFFIX% | The script suffix, ex: .pl , .cgi |
%WEB% | The name of the current web. Note: It is recommended to URL-encode the variable in form actions with %INTURLENCODE{"%WEB%"}% for proper handling in an internationalized environment |
%TOPIC% | The name of the current topic. Note: It is recommended to URL-encode the variable in form actions with %INTURLENCODE{"%TOPIC%"}% for proper handling in an internationalized environment |
%WEBTOPICLIST% | Common links of current web, defined in the WebPreferences. It includes a #GoBox |
%TEXT% | The topic text, e.g. the content that can be edited |
%META{"form"}% | TWikiForm, if any |
%META{"attachments"}% | FileAttachment table |
%META{"parent"}% | The topic parent |
%EDITTOPIC% | Edit link |
%REVTITLE% | The revision title, if any, ex: (r1.6) |
%REVINFO% | Revision info, ex: r1.6 - 24 Dec 2002 - 08:12 GMT - TWikiGuest |
%WEBCOPYRIGHT% | Copyright notice, defined in the WebPreferences |
%BROADCASTMESSAGE% | Broadcast message at the beginning of your view template, can be used to alert users of scheduled downtimes; is set in TWikiPreferences |
The "Go" Box and Navigation Box
The
%WEBTOPICLIST%
includes a "Go" box to jump to a topic. The box also understand URLs, e.g. you can type
http://www.google.com/ to jump to an external web site. The feature is handy if you build a skin that has a select box of frequently used links, like Intranet home, employee database, sales database and such. A little JavaScript gets into action on the onSelect method of the select tag to fill the selected URL into the "Go" box field, then submits the form.
Here is an example form that has a select box and the "Go" box for illustration purposes. You need to have JavaScript enabled for this to work:
Using Cascading Style Sheets
Although work is underway at
TWiki:Codev.CssClassNames, the regular templates files currently do not use style sheets. Many skin developers, however, choose to use them; it helps in separating style from content.
Example: To use a style sheet for the broadcast message, add this to
view.myskin.tmpl
:
<style type="text/css">
.broadcastmessage {
background: yellow; display:block;
border-style:solid;border-width: 2px;border-color:red;
}
.broadcastmessage strong {color: red}
</style>
Then add a div tag to the
%BROADCASTMESSAGE%
variable located after the
#PageTop
anchor or after the opening form tag:
<div class="broadcastmessage"> %BROADCASTMESSAGE% </div>
Attachment Tables
Controlling the look and feel of attachment tables is a little bit more complex than for the rest of a skin. By default the attachment table is a standard TWiki table, and the look is controlled in the same ay as other tables. In a very few cases you may want to change the
content of the table as well.
The format of standard attachment tables is defined through the use of special
TWiki template macros which by default are defined in the
templates/twiki.tmpl
template using the
%TMPL:DEF
macro syntax described in
TWikiTemplates. These macros are:
Macro | Description |
ATTACH:files:header | Standard title bar |
ATTACH:files:row | Standard row |
ATTACH:files:footer | Footer for all screens |
ATTACH:files:header:A | Title bar for upload screens, with attributes column |
ATTACH:files:row:A | Row for upload screen |
ATTACH:files:footer:A | Footer for all screens |
The format of tables of file versions in the Upload screen are also formattable, using the macros:
Macro | Description |
ATTACH:versions:header | Header for versions table on upload screen |
ATTACH:versions:row | Row format for versions table on upload screen |
ATTACH:versions:footer | Footer for versions table on upload screen |
The
ATTACH:row
macros are expanded for each file in the attachment table, using the following special tags:
Tag | Description |
%A_URL% | URL that will recover the file |
%A_REV% | Revision of this file e.g. "1.1" |
%A_ICON% | A file icon suitable for representing the attachment content |
%A_FILE% | The name of the file |
%A_SIZE% | The size of the file |
%A_DATE% | The date the file was uploaded |
%A_USER% | The user who uploaded it |
%A_COMMENT% | The comment they put in when uploading it |
%A_ATTRS% | The attributes of the file as seen on the upload screen e.g "h" for a hidden file |
Note: it is easy to change the look and feel for an entire site by editing the
twiki.tmpl
template file. However, to simplify upgrading, you should avoid doing this. Instead, write a skin-specific template file e.g.
attach.myskin.tmpl
and use
%TMPL:INCLUDE{attach.myskin.tmpl}%
to include it in each of your skin files. As long as it it included
after twiki.tmpl, your macro definitions will override the defaults defined there.
Packaging and Publishing Skins
See
TWiki:Plugins/SkinPackagingHowTo and
TWiki:Plugins/SkinDeveloperFAQ
Browsing Installed Skins
You can try all installed skins in
TWikiSkinBrowser.
Activating Skins
A skin can be activated in two ways:
- Add
?skin=name
to the URL, for this example:
The
?skin=name
URL parameter overrides the SKIN Preference value.
--
TWiki:Main.PeterThoeny - 25 Jul 2004
--
TWiki:Main.CrawfordCurrie - 30 Jun 2004
TWiki Formatted Search Results
Inline search feature allows flexible formatting of search result
The
%SEARCH{...}%
variable documented in
TWikiVariables has a fixed format for the search result, that is, a table consisting of topic names and topic summaries. Use the
format="..."
parameter to specify a customized format of the search result. The string of the format parameter is typically a bullet list or table row containing variables (such as
%SEARCH{ "food" format="| $topic | $summary |" }%
).
Syntax
Two parameters can be used to specify a customized search result:
1.
header="..."
parameter
Use the header parameter to specify the header of a search result. It should correspond to the format of the format parameter. This parameter is optional.
Example:
header="| *Topic:* | *Summary:* |"
2.
format="..."
parameter
Use the format parameter to specify the format of one search hit.
Example:
format="| $topic | $summary |"
Variables that can be used in the format string:
Name: | Expands To: |
$web | Name of the web |
$topic | Topic name |
$topic(20) | Topic name, "- " hyphenated each 20 characters |
$topic(30, -<br />) | Topic name, hyphenated each 30 characters with separator "-<br />" |
$topic(40, ...) | Topic name, shortended to 40 characters with "..." indication |
$parent | Name of parent topic; empty if not set |
$parent(20) | Name of parent topic, same hyphenation/shortening like $topic() |
$text | Formatted topic text. In case of a multiple="on" search, it is the line found for each search hit. |
$locked | LOCKED flag (if any) |
$date | Time stamp of last topic update, e.g. 20 Apr 2024 - 09:32 |
$isodate | Time stamp of last topic update, e.g. 2024-04-20T09:32Z |
$rev | Number of last topic revision, e.g. 1.4 |
$username | Login name of last topic update, e.g. jsmith |
$wikiname | Wiki user name of last topic update, e.g. JohnSmith |
$wikiusername | Wiki user name of last topic update, like Main.JohnSmith |
$createdate | Time stamp of topic revision 1.1 |
$createusername | Login name of topic revision 1.1, e.g. jsmith |
$createwikiname | Wiki user name of topic revision 1.1, e.g. JohnSmith |
$createwikiusername | Wiki user name of topic revision 1.1, e.g. Main.JohnSmith |
$summary | Topic summary |
$formname | The name of the form attached to the topic; empty if none |
$formfield(name) | The field value of a form field; for example, $formfield(TopicClassification) would get expanded to PublicFAQ . This applies only to topics that have a TWikiForm |
$formfield(name, 10) | Form field value, "- " hyphenated each 10 characters |
$formfield(name, 20, -<br />) | Form field value, hyphenated each 20 characters with separator "-<br />" |
$formfield(name, 30, ...) | Form field value, shortended to 30 characters with "..." indication |
$pattern(reg-exp) | A regular expression pattern to extract some text from a topic (does not search meta data; use $formfield instead). In case of a multiple="on" search, the pattern is applied to the line found in each search hit. • Specify a RegularExpression that covers the whole text (topic or line), which typically starts with .* , and must end in .* • Put text you want to keep in parenthesis, like $pattern(.*?(from here.*?to here).*) • Example: $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the email address from a bullet of format * Email: ... • This example has non-greedy .*? patterns to scan for the first occurance of the Email bullet; use greedy .* patterns to scan for the last occurance • Limitation: Do not use .*) inside the pattern, e.g. $pattern(.*foo(.*)bar.*) does not work, but $pattern(.*foo(.*?)bar.*) does • Note: Make sure that the integrity of a web page is not compromised; for example, if you include an HTML table make sure to include everything including the table end tag |
$n or $n() | New line |
$nop or $nop() | Is a "no operation". This variable gets removed; useful for nested search |
$quot | Double quote (" ). Alternatively write \" to escape it |
$percnt | Percent sign (% ) |
$dollar | Dollar sign ($ ) |
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 TWiki 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
In a web where there is a form that contains a
TopicClassification
field, an
OperatingSystem
field and an
OsVersion
field we could write:
| *Topic:* | *OperatingSystem:* | *OsVersion:* |
%SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" scope="text" regex="on" nosearch="on" nototal="on" format="| [[$topic]] | $formfield(OperatingSystem) | $formfield(OsVersion) |" }%
To get this:
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...
- How do I delete or rename a file attachment? 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...
- How do you log off? Suppose I log in with the guest username but later I want to use another username, how do I log off from the guest user name? 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...
Nested Search
Search can be nested. For example, search for some topics, then form a new search for each topic found in the first search. The idea is to build the nested search string using a formatted search in the first search.
Here is an example. Let's search for all topics that contain the word "culture" (first search), and let's find out where each topic found is linked from (second search).
- First search:
-
%SEARCH{ "culture" format=" * $topic is referenced by: (list all references)" nosearch="on" nototal="on" }%
- Second search. For each hit we want this search:
-
%SEARCH{ "(topic found in first search)" format="$topic" nosearch="on" nototal="on" separator=", " }%
- Now let's nest the two. We need to escape the second search, e.g. the first search will build a valid second search string. Note that we escape the second search so that it does not get evaluated prematurely by the first search:
- Use
$percnt
to escape the leading percent of the second search
- Use
\"
to escape the double quotes
- Use
$dollar
to escape the $
of $topic
- Use
$nop
to escape the }%
sequence
Write this:
%SEARCH{ "culture" format=" * $topic is referenced by:$n * $percntSEARCH{ \"$topic\" format=\"$dollartopic\" nosearch=\"on\" nototal=\"on\" separator=\", \" }$nop%" nosearch="on" nototal="on" }%
To get this:
- ATasteOfTWiki is referenced by:
- FormattedSearch is referenced by:
- EditTablePlugin, EmptyPlugin, ManagingWebs, RenderListPlugin, SearchHelp, SpreadSheetPlugin, TWikiDocumentation, TWikiForms, TWikiFuncModule, TWikiHistory, TWikiMetaData, TWikiUpgradeGuide, TWikiUpgradeTo01Dec2001, TWikiVariables, TextFormattingRules, WelcomeGuest
- TWikiAccessControl is referenced by:
- CommentPlugin, EditTablePlugin, FileAttachment, MainFeatures, ManagingTopics, TWikiAccessControl, TWikiDocumentation, TWikiForms, TWikiFuncModule, TWikiHistory, TWikiPreferences, TWikiTopics, TWikiTutorial, TWikiUpgradeTo01Dec2000, TWikiUpgradeTo01Dec2001, TWikiUserAuthentication, TWikiVariables, WebPreferences, WebStatistics, WelcomeGuest, WikiCulture, WikiWord
- TWikiSite is referenced by:
- InstantEnhancements, InterwikiPlugin, ManagingWebs, StartingPoints, TWikiDocumentation, TWikiGlossary, TWikiInstallationGuide, TWikiPreferences, TWikiRegistration, TWikiRegistrationPub, TWikiSite, TWikiSiteTools, TWikiTopics, TWikiTutorial, TWikiUpgradeTo01Dec2000, WabiSabi, WebHome, WebSiteTools, WebStatistics, WelcomeGuest, WhatIsWikiWiki, WikiCulture, WikiReferences
- WabiSabi is referenced by:
- WelcomeGuest is referenced by:
- ATasteOfTWiki, NewUserTemplate, StartingPoints, TWikiSite, TWikiUpgradeTo01Dec2000, WebHome, WebPreferences, WebStatistics, WhatIsWikiWiki, WikiCulture, YouAreHere
- WikiCulture is referenced by:
Note: Nested search can be slow, especially if you nest more then 3 times. Nesting is limited to 16 levels. For each new nesting level you need to "escape the escapes", e.g. write
$dollarpercntSEARCH{
for level three,
$dollardollarpercntSEARCH{
for level four, etc.
Most recently changed pages
Write this:
%SEARCH{ "\.*" scope="topic" regex="on" nosearch="on" nototal="on" order="modified" reverse="on" format="| [[$topic]] | $wikiusername | $date |" limit="7" }%
To get this:
Search with conditional output
A regular expression search is flexible, but there are limitations. For example, you cannot show all topics that are up to exactly one week old, or create a report that shows all records with invalid form fields or fields within a certain range, etc. You need some additional logic to format output based on a condition:
- Specify a search which returns more hits then you need
- For each search hit apply a spreadsheet formula to determine if the hit is needed
- If needed, format and output the result
- Else supress the search hit
This requires the
TWiki:Plugins.SpreadSheetPlugin. The following example shows all topics that are up to exactly one week old.
Write this:
%CALC{$SET(weekold, $TIMEADD($TIME(), -7, day))}%
%SEARCH{ "." scope="topic" regex="on" nosearch="on" nototal="on" order="modified" reverse="on" format="$percntCALC{$IF($TIME($date) < $GET(weekold), <nop>, | [[$topic]] | $wikiusername | $date | $rev |)}$percnt" limit="100" }%
- The first line sets the
weekold
variable to the serialized date of exactly one week ago
- The SEARCH has a deferred CALC. The
$percnt
makes sure that the CALC gets executed once for each search hit
- The CALC compares the date of the topic with the
weekold
date
- If topic is older, a
<nop>
is returned, which gets removed at the end of the TWiki rendering process
- Otherwise, the search hit is formatted and returned
To get this:
Embedding search forms to return a formatted result
Use an HTML form and an embedded formatted search on the same topic. You can link them together with an
%URLPARAM{"..."}%
variable. Example:
Write this:
<form action="%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%">
Find Topics:
<input type="text" name="q" size="32" value="%URLPARAM{"q"}%" />
<input type="submit" value="Search" />
</form>
Result:
%SEARCH{ search="%URLPARAM{"q"}%" format=" * $web.$topic: %BR% $summary" nosearch="on" }%
To get this:
Result:
Number of topics:
0
--
TWiki:Main.PeterThoeny - 26 Jul 2004
TWiki Meta Data
Additional topic data, program-generated or from TWikiForms, is stored in META
variable name/value pairs
Overview
TWikiMetaData uses
META
variables to store topic data that's separate from the main free-form content. This includes program-generated info like
FileAttachment and topic movement data, and user-defined
TWikiForms info. Use
META
variables to format and display Meta Data.
Meta Data Syntax
- 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, unix time, seconds since start 1970 |
author | last to change topic, is the REMOTE_USER |
format | Format of this topic, will be used for automatic format conversion |
META:TOPICMOVED
This is optional, exists if topic has ever been moved. If a topic is moved more than once, only the most recent META:TOPICMOVED meta variable exists in the topic, older ones are to be found in the rcs history.
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%
Key | Comment |
from | Full name, i.e., web.topic |
to | Full name, i.e., web.topic |
by | Who did it, is the REMOTE_USER, not WikiName |
date | integer, unix time, seconds since start 1970 |
Notes:
- 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, unix time, seconds since start 1970 |
user | the REMOTE_USER, not WikiName |
comment | As supplied when file uploaded |
attr | h if hidden, optional |
Extra fields that are added if an attachment is moved:
Key | Comment |
movedfrom | full topic name - web.topic |
movedby | the REMOTE_USER, not WikiName |
movedto | full topic name - web.topic |
moveddate | integer, unix time, seconds since start 1970 |
META:FORM
Key | Comment |
name | A topic name - the topic represents one of the TWikiForms. Can optionally include the web name (i.e., web.topic), but doesn't normally |
META:FIELD
Should only be present if there is a META:FORM entry. Note that this data is used when viewing a topic, the form template definition is not read.
Key | Name |
name | Ties to entry in TWikiForms template, is title with all bar alphanumerics and . removed |
title | Full text from TWikiForms template |
value | Value user has supplied via form |
Recommended Sequence
There is no absolute need for Meta Data variables to be listed in a specific order within a topic, but it makes sense to do so a couple of good reasons:
- 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 (i.e., as seen when editing). This is done by adding
raw=on
to URL.
raw=debug
shows the meta data as well as the topic data, ex:
debug view for this topic
Rendering Meta Data
Meta Data is rendered with the %META% variable. This is mostly used in the
view
,
preview
and
edit
scripts.
Note: Rendering meta data is currently not supported in topic text. As a workaround, use
FormattedSearch on the current topic only to render form fields.
Current support covers:
Variable usage: | Comment: |
%META{"form"}% | Show form data, see TWikiForms. |
%META{"formfield"}% | Show form field value. Parameter: name="field_name" . Example: %META{ "formfield" name="TopicClassification" }% |
%META{"attachments"}% | Show attachments, except for hidden ones. Options: all="on" : Show all attachments, including hidden ones. |
%META{"moved"}% | Details of any topic moves. |
%META{"parent"}% | Show topic parent. Options: dontrecurse="on" : By default recurses up tree, at some cost. nowebhome="on" : Suppress WebHome. prefix="..." : Prefix for parents, only if there are parents, default "" . suffix="..." : Suffix, only appears if there are parents, default "" . separator="..." : Separator between parents, default is " > " . |
Known Issues
At present, there is no Meta Data support for Plugins. However, the format is readily extendable and the
Meta.pm
code that supports the format needs only minor alteration.
--
TWiki:Main.JohnTalintyre - 29 Aug 2001
--
TWiki:Main.MikeMannix - 03 Dec 2001
--
TWiki:Main.PeterThoeny - 10 Jan 2002
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 a set of 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: 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.
- EditTablePlugin: Edit TWiki tables using edit fields, date pickers and drop down boxes
- RenderListPlugin: Render bullet lists in a variety of formats
- SlideShowPlugin: Create web based presentations based on topics with headings.
- SmiliesPlugin: Render smilies as icons, like
:-)
for or :cool:
for
- SpreadSheetPlugin: Add spreadsheet calculation like
"$SUM( $ABOVE() )"
to tables located in TWiki topics.
- TablePlugin: Control attributes of tables and sorting of table columns
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:
- Download the zip file containing the Plugin, documentation, and any other required files, from TWiki:Plugins.
- 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.
- 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, and adjust the paths in the new lib/TWiki.cfg
. The following directories are shared: twiki/data
, twiki/templates
and twiki/pub
.
- Test Plugins and other new features in the Test installation until you're satisfied.
- 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 being tested in the
DISABLEDPLUGINS
variable in TWikiPreferences. Redefine the DISABLEDPLUGINS
variable in the Sandbox
web and do the testing there.
Checking that Plugins are Working on a Live Server
InstalledPlugins shows which Plugins are: 1) installed, 2) loading properly and 3) what
TWiki:Codev.PluginHandlers they invoke. Any failures are shown in the Errors section.
A Note on Plugin Performance
The performance of the system depends on the number of Plugins installed and on the Plugin implementation. Some Plugins impose no measurable performance decrease, some do. For example,
outsidePREHandler
is an expensive callback function, or a Plugin might use many Perl libraries that need to be initialized with each page view (unless you run mod_perl). It is recommended to measure the performance with and without a new Plugin. Example for Unix:
time wget -qO /dev/null http://jcuckoo.sourceforge.net/cgi-bin/view/TWiki/AbcPlugin
In case you need to install an "expensive" Plugin and you need its functionality only in one web you can place the Plugin topic into that web. TWiki will initialize the Plugin only if the Plugin topic is found (which won't be the case for other webs.)
Managing Plugins
When you finish
installing a Plugin, you should be able to read the user instructions and go. In fact, some Plugins require additional settings or offer extra options that you have to select. Also, you may want to make a Plugin available only in certain webs, or temporarily disable it. And may want to list all available Plugins in certain topics. You can handle all of these management tasks with simple procedures.
Setting Preferences
Installed Plugins can be
toggled on or off, site-wide or by web, through TWikiPreferences and individual WebPreferences:
- 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 JCuckoo 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:
- One line description, used to form the bullets describing the Plugins in the TextFormattingRules topic:
-
Set SHORTDESCRIPTION = Blah blah woof woof.
- Debug Plugin, output can be seen in
data/debug.txt
. Set to 0=off or 1=on:
- 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, SpreadSheetPlugin, CommentPlugin, EditTablePlugin, InterwikiPlugin, RenderListPlugin, SlideShowPlugin, SmiliesPlugin, TablePlugin.
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 depreciated
*_text_*
as bold italic text.
- SpreadSheetPlugin: Add spreadsheet calculation like
"$SUM( $ABOVE() )"
to tables located in JCuckoo topics.
- CommentPlugin: Allows users to quickly post comments to a page without an edit/preview/save cycle.
- EditTablePlugin: Edit TWiki tables using edit fields, date pickers and drop down boxes
- InterwikiPlugin: Link
ExternalSite:Page
text to external sites based on aliases defined in the InterWikis topic
- RenderListPlugin: Render bullet lists in a variety of formats
- SlideShowPlugin: Create web based presentations based on topics with headings.
- SmiliesPlugin: Render smilies as icons, like
:-)
for or :cool:
for
- TablePlugin: Control attributes of tables and sorting of table columns
The TWiki Plugin API
The Application Programming Interface (API) for TWikiPlugins provides the specifications for hooking into the core TWiki code from your external Perl Plugin module. The Plugin API is new to the Production version of TWiki with the 01-Sep-2001 release.
Available Core Functions
The
TWikiFuncModule (
lib/TWiki/Func.pm
) implements ALL official Plugin functions. Plugins should ONLY use functions published in this module.
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.
- All but the initPlugin are disabled. To enable a call back, remove
DISABLE_
from the function name.
- For best performance, enable only the functions you really need. NOTE:
outsidePREHandler
and insidePREHandler
are particularly expensive.
Most Plugins use either the
commonTagsHandler
or
startRenderingHandler
for rendering tasks:
-
commonTagsHandler:
Use it to expand %XYZPLUGIN%
and %XYZPLUGIN{...}%
variables
-
startRenderingHandler:
Use it for your own rendering rules or to overload TWiki's internal rendering like [[links]]
TWiki:Codev/StepByStepRenderingOrder helps you decide which rendering handler to use.
Hints on Writing Fast Plugins
- Delay the Plugin initialization to the actual function which is handling the tag. This way all the expensive initialization is done only when needed.
- For example, use an
eval
block like:
eval { require IPC::Run }
return "<font color=\"red\">SamplePlugin: Can't load required modules ($@)</font>" if $@;
- You could return errors as strings to show what happened
- You can use a flag to avoid running the initialization twice
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
. The
EmptyPlugin.pm
module contains mostly empty functions, so it does nothing, but it's ready to be used. Customize it. Refer to the
Plugin API specs for more information.
If your Plugin uses its own modules and objects, you must include the name of the Plugin in the package name. For example, write
Package MyFirstPlugin::Attrs;
instead of just
Package Attrs;
. Then call it using:
use TWiki::Plugins::MyFirstPlugin::Attrs;
$var = MyFirstPlugin::Attrs->new();
Writing the Documentation Topic
The Plugin documentation topic contains usage instructions and version details. It serves the Plugin files as
FileAttachments for downloading. (The doc topic is also included
in the
distribution package.) To create a documentation topic:
- Copy the Plugin topic template from TWiki.org. To copy the text, go to TWiki:Plugins/PluginPackage and:
- enter the Plugin name in the "How to Create a Plugin" section
- click Create
- select all in the Edit box & copy
- Cancel the edit
- go back to your site to the TWiki web
- In the GoBox enter your Plugin name, for example
MyFirstPlugin
, press enter and create the new topic
- paste & save new Plugin topic on your site
- Customize your Plugin topic.
- In case you plan to publish your Plugin at TWiki.org, use Interwiki names for author names, like TWiki:Main/TWikiGuest.
- Save your topic, for use in packaging and publishing your Plugin.
OUTLINE: Doc Topic Contents
Check the Plugins web on TWiki.org for the latest Plugin doc topic template. Here's a quick overview of what's covered:
Syntax Rules: <Describe any special text formatting that will be rendered.>"
Example: <Include an example of the Plugin in action. Possibly include a static HTML version of the example to compare if the installation was a success!>"
Plugin Settings: <Description and settings for custom Plugin %VARIABLES%, and those required by TWiki.>"
- Plugins Preferences <If user settings are needed, explain... Entering values works exactly like TWikiPreferences and WebPreferences: six (6) spaces and then:>"
- Set <EXAMPLE = value added>
Plugin Installation Instructions: <Step-by-step set-up guide, user help, whatever it takes to install and run, goes here.>"
Plugin Info: <Version, credits, history, requirements - entered in a form, displayed as a table. Both are automatically generated when you create or edit a page in the TWiki:Plugins web.>"
Packaging for Distribution
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
).
- 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]
- Create a zip archive with the Plugin name (
MyFirstPlugin.zip
) and add the entire directory structure from Step 1. The archive should look like this:
-
lib/TWiki/Plugins/MyFirstPlugin.pm
-
data/TWiki/MyFirstPlugin.txt
-
pub/TWiki/MyFirstPlugin/uparrow.gif
Publishing for Public Use
You can release your tested, packaged Plugin to the TWiki community through the
TWiki:Plugins web. All Plugins submitted to TWiki.org are available for download and further development in
TWiki:Plugins/PluginPackage. Publish your Plugin in these steps:
- Post the Plugin documentation topic in the TWiki:Plugins/PluginPackage:
- enter the Plugin name in the "How to Create a Plugin" section, for example
MyFirstPlugin
- paste in the topic text from Creating Plugin Documentation and save
- Attach the distribution zip file to the topic, ex:
MyFirstPlugin.zip
- 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.)
- Put the Plugin into the CVS repository, see TWiki:Plugins/ReadmeFirst (optional)
Thank you very much for sharing your Plugin with the TWiki community
Recommended Storage of Plugin Data
Plugins sometimes need to store data. This can be Plugin internal data like cache data, or generated data for the browser like images. The following is a recommendation where to store the data.
Where to store Plugin Internal Data
In case the Plugin generates data just for internal use, or data which is not specific to a topic, store it in the Plugin's attachment directory.
- The Plugin's attachment directory is
pubdir/Installweb/FooBarPlugin
-
Installweb
refers to the name of the web where the Plugin is installed
- The Plugin's attachment URL is
%PUBURL%/Installweb/FooBarPlugin
- The filename should start with an underscore, followed by an identifier, e.g.
_any_name.ext
- The leading underscore avoids a nameclash with files attached to the Plugin topic
- Use only alphanumeric characters, underscores and periods to avoid platform dependency issues and URL issues
- Do not use subdirectories (rename and delete would fail)
- Use Plugin API functions documented in TWikiFuncModule to ensure portability:
- Use
getPubDir()
to get the attachment root directory
- Use
getUrlHost()
and getPubUrlPath()
to build the URL in case you create content for the browser
- Use
$installWeb
to get the name of the web where the Plugin is installed
- Create the web directory and topic attachment directory if needed
- Hint: Package the Plugin at least with one file attachment. This ensures that the attachment directory already exists
Where to Store Data for Topics using the Plugin
In case the Plugin generates data which is specific to a topic, store it in the topic's attachment directory.
- The topic's attachment directory is
pubdir/Webname/TopicName
- The topic's attachment URL is
%PUBURL%/Webname/TopicName
- The filename should start with an underscore, followed by the Plugin name, an underscore and an identifier, e.g.
_FooBarPlugin_any_name.ext
- The leading underscore avoids a nameclash with files attached to the same topic
- Use only alphanumeric characters, underscores and periods to avoid platform dependency issues and URL issues
- Do not use subdirectories (rename and delete would fail)
- Use Plugin API functions documented in TWikiFuncModule to ensure portability:
- Use
getPubDir()
to get the attachment root directory
- Use
getUrlHost()
and getPubUrlPath()
to build the URL in case you create content for the browser
Example code to build the file name:
sub _make_filename
{
my ( $web, $topic, $name ) = @_;
# Create web directory "pub/$web" if needed
my $dir = TWiki::Func::getPubDir() . "/$web";
unless( -e "$dir" ) {
umask( 002 );
mkdir( $dir, 0775 );
}
# Create topic directory "pub/$web/$topic" if needed
$dir .= "/$topic";
unless( -e "$dir" ) {
umask( 002 );
mkdir( $dir, 0775 );
}
return "$dir/_FooBarPlugin_$name";
}
--
TWiki:Main/PeterThoeny - 18 May 2004
--
TWiki:Main/AndreaSterbini - 29 May 2001
--
TWiki:Main/MikeMannix - 03 Dec 2001
TWiki::Func Module Documentation
Official list of stable TWiki functions for Plugin developers
Description
This module defines official funtions that
Plugins
and add-on scripts can use to interact with the TWiki engine and content.
Plugins should
only use functions published in this module. If you use
functions in other TWiki libraries you might impose a security hole and
you will likely need to change your Plugin when you upgrade TWiki.
The "Since" field refers to the VERSION number of
the TWiki::Plugins module and the date that the function was addded.
Functions: CGI Environment
getSessionValue( $key ) ==> $value
Description: | Get a session value from the Session Plugin (if installed) |
Parameter: $key | Session key |
Return: $value | Value associated with key; empty string if not set; undef if session plugin is not installed |
Since: | TWiki::Plugins::VERSION 1.000 (27 Feb 2001) |
setSessionValue( $key, $value ) ==> $result
Description: | Set a session value via the Session Plugin (if installed) |
Parameter: $key | Session key |
Parameter: $value | Value associated with key |
Return: $result | "1" if success; undef if session plugin is not installed |
Since: | TWiki::Plugins::VERSION 1.000 (17 Aug 2001) |
getSkin( ) ==> $skin
Description: | Get the name of the skin, set by the SKIN preferences variable or the skin CGI parameter |
Return: $skin | Name of skin, e.g. "gnu" . Empty string if none |
Since: | TWiki::Plugins::VERSION 1.000 (29 Jul 2001) |
getUrlHost( ) ==> $host
Description: | Get protocol, domain and optional port of script URL |
Return: $host | URL host, e.g. "http://example.com:80" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
getScriptUrl( $web, $topic, $script ) ==> $url
Description: | Compose fully qualified URL |
Parameter: $web | Web name, e.g. "Main" |
Parameter: $topic | Topic name, e.g. "WebNotify" |
Parameter: $script | Script name, e.g. "view" |
Return: $url | URL, e.g. "http://example.com:80/cgi-bin/view.pl/Main/WebNotify" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
getScriptUrlPath( ) ==> $path
Description: | Get script URL path |
Return: $path | URL path of TWiki scripts, e.g. "/cgi-bin" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
getViewUrl( $web, $topic ) ==> $url
Description: | Compose fully qualified view URL |
Parameter: $web | Web name, e.g. "Main" . The current web is taken if empty |
Parameter: $topic | Topic name, e.g. "WebNotify" |
Return: $url | URL, e.g. "http://example.com:80/cgi-bin/view.pl/Main/WebNotify" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) ==> $url
Description: | Compose fully qualified "oops" dialog URL |
Parameter: $web | Web name, e.g. "Main" . The current web is taken if empty |
Parameter: $topic | Topic name, e.g. "WebNotify" |
Parameter: $template | Oops template name, e.g. "oopslocked" |
Parameter: $param1 ... $param4 | Parameter values for %PARAM1% ... %PARAM4% variables in template, optional |
Return: $url | URL, e.g. "http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked¶m1=joe" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
getPubUrlPath( ) ==> $path
Description: | Get pub URL path |
Return: $path | URL path of pub directory, e.g. "/pub" |
Since: | TWiki::Plugins::VERSION 1.000 (14 Jul 2001) |
getCgiQuery( ) ==> $query
Description: | Get CGI query object. Important: Plugins cannot assume that scripts run under CGI, Plugins must always test if the CGI query object is set |
Return: $query | CGI query object; or 0 if script is called as a shell script |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
writeHeader( $query )
Description: | Prints a basic content-type HTML header for text/html to standard out |
Parameter: $query | CGI query object |
Return: | none |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
redirectCgiQuery( $query, $url )
Description: | Redirect to URL |
Parameter: $query | CGI query object |
Parameter: $url | URL to redirect to |
Return: | none, never returns |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Functions: Preferences
extractNameValuePair( $attr, $name ) ==> $value
Description: | Extract a named or unnamed value from a variable parameter string |
Parameter: $attr | Attribute string |
Parameter: $name | Name, optional |
Return: $value | Extracted value |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
- Example:
- Variable:
%TEST{ "nameless" name1="val1" name2="val2" }%
- First extract text between
{...}
to get: "nameless" name1="val1" name2="val2"
- Then call this on the text:
my $noname = TWiki::Func::extractNameValuePair( $text );
my $val1 = TWiki::Func::extractNameValuePair( $text, "name1" );
my $val2 = TWiki::Func::extractNameValuePair( $text, "name2" );
getPreferencesValue( $key, $web ) ==> $value
Description: | Get a preferences value from TWiki or from a Plugin |
Parameter: $key | Preferences key |
Parameter: $web | Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics |
Return: $value | Preferences value; empty string if not set |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
- Example for Plugin setting:
- MyPlugin topic has:
* Set COLOR = red
- Use
"MYPLUGIN_COLOR"
for $key
-
my $color = TWiki::Func::getPreferencesValue( "MYPLUGIN_COLOR" );
- Example for preferences setting:
- WebPreferences topic has:
* Set WEBBGCOLOR = #FFFFC0
-
my $webColor = TWiki::Func::getPreferencesValue( "WEBBGCOLOR", "Sandbox" );
getPluginPreferencesValue( $key ) ==> $value
Description: | Get a preferences value from your Plugin |
Parameter: $key | Plugin Preferences key w/o PLUGINNAME_ prefix. |
Return: $value | Preferences value; empty string if not set |
Since: | TWiki::Plugins::VERSION 1.021 (27 Mar 2004) |
getPreferencesFlag( $key, $web ) ==> $value
Description: | Get a preferences flag from TWiki or from a Plugin |
Parameter: $key | Preferences key |
Parameter: $web | Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics |
Return: $value | Preferences flag "1" (if set), or "0" (for preferences values "off" , "no" and "0" ) |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
- Example for Plugin setting:
- MyPlugin topic has:
* Set SHOWHELP = off
- Use
"MYPLUGIN_SHOWHELP"
for $key
-
my $showHelp = TWiki::Func::getPreferencesFlag( "MYPLUGIN_SHOWHELP" );
getPluginPreferencesFlag( $key ) ==> $flag
Description: | Get a preferences flag from your Plugin |
Parameter: $key | Plugin Preferences key w/o PLUGINNAME_ prefix. |
Return: $flag | Preferences flag "1" (if set), or "0" (for preferences values "off" , "no" and "0" , or values not set at all) |
Since: | TWiki::Plugins::VERSION 1.021 (27 Mar 2004) |
getWikiToolName( ) ==> $name
Description: | Get toolname as defined in TWiki.cfg |
Return: $name | Name of tool, e.g. "TWiki" |
Since: | TWiki::Plugins::VERSION 1.000 (27 Feb 2001) |
getMainWebname( ) ==> $name
Description: | Get name of Main web as defined in TWiki.cfg |
Return: $name | Name, e.g. "Main" |
Since: | TWiki::Plugins::VERSION 1.000 (27 Feb 2001) |
getTwikiWebname( ) ==> $name
Description: | Get name of TWiki documentation web as defined in TWiki.cfg |
Return: $name | Name, e.g. "TWiki" |
Since: | TWiki::Plugins::VERSION 1.000 (27 Feb 2001) |
Functions: User Handling and Access Control
getDefaultUserName( ) ==> $loginName
Description: | Get default user name as defined in TWiki.cfg's $defaultUserName |
Return: $loginName | Default user name, e.g. "guest" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
getWikiName( ) ==> $wikiName
Description: | Get Wiki name of logged in user |
Return: $wikiName | Wiki Name, e.g. "JohnDoe" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
getWikiUserName( $text ) ==> $wikiName
Description: | Get Wiki name of logged in user with web prefix |
Return: $wikiName | Wiki Name, e.g. "Main.JohnDoe" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
wikiToUserName( $wikiName ) ==> $loginName
Description: | Translate a Wiki name to a login name based on Main.TWikiUsers topic |
Parameter: $wikiName | Wiki name, e.g. "Main.JohnDoe" or "JohnDoe" |
Return: $loginName | Login name of user, e.g. "jdoe" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
userToWikiName( $loginName, $dontAddWeb ) ==> $wikiName
Description: | Translate a login name to a Wiki name based on Main.TWikiUsers topic |
Parameter: $loginName | Login name, e.g. "jdoe" |
Parameter: $dontAddWeb | Do not add web prefix if "1" |
Return: $wikiName | Wiki name of user, e.g. "Main.JohnDoe" or "JohnDoe" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
isGuest( ) ==> $flag
Description: | Test if logged in user is a guest |
Return: $flag | "1" if yes, "0" if not |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
permissionsSet( $web ) ==> $flag
Description: | Test if any access restrictions are set for this web, ignoring settings on individual pages |
Parameter: $web | Web name, required, e.g. "Sandbox" |
Return: $flag | "1" if yes, "0" if no |
Since: | TWiki::Plugins::VERSION 1.000 (27 Feb 2001) |
checkAccessPermission( $type, $wikiName, $text, $topic, $web ) ==> $flag
Description: | Check access permission for a topic based on the TWiki.TWikiAccessControl rules |
Parameter: $type | Access type, e.g. "VIEW" , "CHANGE" , "CREATE" |
Parameter: $wikiName | WikiName of remote user, i.e. "Main.PeterThoeny" |
Parameter: $text | Topic text, optional. If empty, topic $web.$topic is consulted |
Parameter: $topic | Topic name, required, e.g. "PrivateStuff" |
Parameter: $web | Web name, required, e.g. "Sandbox" |
Return: $flag | "1" if access may be granted, "0" if not |
Since: | TWiki::Plugins::VERSION 1.000 (27 Feb 2001) |
Functions: Content Handling
webExists( $web ) ==> $flag
Description: | Test if web exists |
Parameter: $web | Web name, required, e.g. "Sandbox" |
Return: $flag | "1" if web exists, "0" if not |
Since: | TWiki::Plugins::VERSION 1.000 (14 Jul 2001) |
topicExists( $web, $topic ) ==> $flag
Description: | Test if topic exists |
Parameter: $web | Web name, optional, e.g. "Main" |
Parameter: $topic | Topic name, required, e.g. "TokyoOffice" , or "Main.TokyoOffice" |
Return: $flag | "1" if topic exists, "0" if not |
Since: | TWiki::Plugins::VERSION 1.000 (14 Jul 2001) |
getRevisionInfo($theWebName, $theTopic, $theRev, $attachment ) ==> ( $date, $user, $rev, $comment )
Description: | Get revision info of a topic |
Parameter: $theWebName | Web name, optional, e.g. "Main" |
Parameter: $theTopic | Topic name, required, e.g. "TokyoOffice" |
Parameter: $theRev | revsion number, or tag name (can be in the format 1.2, or just the minor number) |
Parameter: $attachment | attachment filename |
Return: ( $date, $user, $rev, $comment ) | List with: ( last update date, login name of last user, minor part of top revision number ), e.g. ( 1234561, "phoeny", "5" ) |
$date | in epochSec |
$user | |
$rev | |
$comment | WHAT COMMENT? |
Since: | TWiki::Plugins::VERSION 1.000 (29 Jul 2001) |
checkTopicEditLock( $web, $topic ) ==> ( $oopsUrl, $loginName, $unlockTime )
Description: | Check if topic has an edit lock by a user |
Parameter: $web | Web name, e.g. "Main" , or empty |
Parameter: $topic | Topic name, e.g. "MyTopic" , or "Main.MyTopic" |
Return: ( $oopsUrl, $loginName, $unlockTime ) | The $oopsUrl for calling redirectCgiQuery(), user's $loginName , and estimated $unlockTime in minutes. The $oopsUrl and $loginName is empty if topic has no edit lock. |
Since: | TWiki::Plugins::VERSION 1.010 (31 Dec 2002) |
setTopicEditLock( $web, $topic, $lock ) ==> $oopsUrl
Description: | Lock topic for editing, or unlock when done |
Parameter: $web | Web name, e.g. "Main" , or empty |
Parameter: $topic | Topic name, e.g. "MyTopic" , or "Main.MyTopic" |
Parameter: $lock | Set to 1 to lock topic, 0 to unlock |
Return: $oopsUrl | Empty string if OK; the $oopsUrl for calling redirectCgiQuery() in case lock is already taken when trying to lock topic |
Since: | TWiki::Plugins::VERSION 1.010 (31 Dec 2002) |
readTopicText( $web, $topic, $rev, $ignorePermissions ) ==> $text
Description: | Read topic text, including meta data |
Parameter: $web | Web name, e.g. "Main" , or empty |
Parameter: $topic | Topic name, e.g. "MyTopic" , or "Main.MyTopic" |
Parameter: $rev | Topic revision to read, optional. Specify the minor part of the revision, e.g. "5" , not "1.5" ; the top revision is returned if omitted or empty. |
Parameter: $ignorePermissions | Set to "1" if checkAccessPermission() is already performed and OK; an oops URL is returned if user has no permission |
Return: $text | Topic text with embedded meta data; an oops URL for calling redirectCgiQuery() is returned in case of an error |
Since: | TWiki::Plugins::VERSION 1.010 (31 Dec 2002) |
saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) ==> $oopsUrl
Description: | Save topic text, typically obtained by readTopicText(). Topic data usually includes meta data; the file attachment meta data is replaced by the meta data from the topic file if it exists. |
Parameter: $web | Web name, e.g. "Main" , or empty |
Parameter: $topic | Topic name, e.g. "MyTopic" , or "Main.MyTopic" |
Parameter: $text | Topic text to save, assumed to include meta data |
Parameter: $ignorePermissions | Set to "1" if checkAccessPermission() is already performed and OK |
Parameter: $dontNotify | Set to "1" if not to notify users of the change |
Return: $oopsUrl | Empty string if OK; the $oopsUrl for calling redirectCgiQuery() in case of error |
Since: | TWiki::Plugins::VERSION 1.010 (31 Dec 2002) |
- Example:
my $oopsUrl = TWiki::Func::setTopicEditLock( $web, $topic, 1 );
if( $oopsUrl ) {
TWiki::Func::redirectCgiQuery( $query, $oopsUrl ); # assuming valid query
return;
}
my $text = TWiki::Func::readTopicText( $web, $topic ); # read topic text
# check for oops URL in case of error:
if( $text =~ /^http.*?\/oops/ ) {
TWiki::Func::redirectCgiQuery( $query, $text );
return;
}
# do topic text manipulation like:
$text =~ s/old/new/g;
# do meta data manipulation like:
$text =~ s/(META\:FIELD.*?name\=\"TopicClassification\".*?value\=\")[^\"]*/$1BugResolved/;
$oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text
TWiki::Func::setTopicEditLock( $web, $topic, 0 ); # unlock topic
if( $oopsUrl ) {
TWiki::Func::redirectCgiQuery( $query, $oopsUrl );
return;
}
getPublicWebList( ) ==> @webs
Description: | Get list of all public webs, e.g. all webs that do not have the NOSEARCHALL flag set in the WebPreferences |
Return: @webs | List of all public webs, e.g. ( "Main", "Know", "TWiki" ) |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
getTopicList( $web ) ==> @topics
Description: | Get list of all topics in a web |
Parameter: $web | Web name, required, e.g. "Sandbox" |
Return: @topics | Topic list, e.g. ( "WebChanges", "WebHome", "WebIndex", "WebNotify" ) |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Functions: Rendering
expandCommonVariables( $text, $topic, $web ) ==> $text
Description: | Expand all common %VARIABLES% |
Parameter: $text | Text with variables to expand, e.g. "Current user is %WIKIUSER%" |
Parameter: $topic | Current topic name, e.g. "WebNotify" |
Parameter: $web | Web name, optional, e.g. "Main" . The current web is taken if missing |
Return: $text | Expanded text, e.g. "Current user is TWikiGuest" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
renderText( $text, $web ) ==> $text
Description: | Render text from TWiki markup into XHTML as defined in TWiki.TextFormattingRules |
Parameter: $text | Text to render, e.g. "*bold* text and =fixed font=" |
Parameter: $web | Web name, optional, e.g. "Main" . The current web is taken if missing |
Return: $text | XHTML text, e.g. "<b>bold</b> and <code>fixed font</code>" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) ==> $text
Description: | Render topic name and link label into an XHTML link. Normally you do not need to call this funtion, it is called internally by renderText() |
Parameter: $pre | Text occuring before the TWiki link syntax, optional |
Parameter: $web | Web name, required, e.g. "Main" |
Parameter: $topic | Topic name to link to, required, e.g. "WebNotify" |
Parameter: $label | Link label, required. Usually the same as $topic , e.g. "notify" |
Parameter: $anchor | Anchor, optional, e.g. "#Jump" |
Parameter: $createLink | Set to "1" to add question linked mark after topic name if topic does not exist; set to "0" to suppress link for non-existing topics |
Return: $text | XHTML anchor, e.g. "<a href="/cgi-bin/view/Main/WebNotify#Jump">notify</a>" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
search text( $text ) ==> $text
Description: | This is not a function, just a how-to note. Use: expandCommonVariables("%SEARCH{...}%" ); |
Parameter: $text | Search variable |
Return: $text | Search result in TWiki.FormattedSearch format |
formatTime( $time, $format, $timezone ) ==> $text
Description: | Format the time in seconds into the desired time string |
Parameter: $time | Time in epoc seconds |
Parameter: $format | Format type, optional. Default e.g. " TWiki::Plugins::VERSION 1.010 (31 Dec 2002) - 19:30" , can be "iso" (e.g. "2002-12-31T19:30Z" ), "rcs" (e.g. "2001/12/31 23:59:59" , "http" for HTTP header format (e.g. "Thu, 23 Jul 1998 07:21:56 GMT" ) |
Parameter: $timezone | either not defined (uses the displaytime setting), "gmtime", or "servertime" |
Return: $text | Formatted time string |
Note: | if you used the removed formatGmTime, add a third parameter "gmtime" |
Since: | TWiki::Plugins::VERSION 1.020 (26 Feb 2004) |
formatGmTime( $time, $format ) ==> $text
NOTE: | The following function is deprecated and should not be used. Use formatTime() instead |
Description: | Format the time to GM time |
Parameter: $time | Time in epoc seconds |
Parameter: $format | Format type, optional. Default e.g. "31 Dec 2002 - 19:30" , can be "iso" (e.g. "2002-12-31T19:30Z" ), "rcs" (e.g. "2001/12/31 23:59:59" , "http" for HTTP header format (e.g. "Thu, 23 Jul 1998 07:21:56 GMT" ) |
Return: $text | Formatted time string |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Functions: File I/O
getDataDir( ) ==> $dir
Description: | Get data directory (topic file root) |
Return: $dir | Data directory, e.g. "/twiki/data" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
getPubDir( ) ==> $dir
Description: | Get pub directory (file attachment root). Attachments are in $dir/Web/TopicName |
Return: $dir | Pub directory, e.g. "/htdocs/twiki/pub" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
readTopic( $web, $topic ) ==> ( $meta, $text )
NOTE: | The following function is deprecated and should not be used. Use readTopicText() instead |
Description: | Read topic text and meta data, regardless of access permissions. |
Parameter: $web | Web name, required, e.g. "Main" |
Parameter: $topic | Topic name, required, e.g. "TokyoOffice" |
Return: ( $meta, $text ) | Meta data object and topic text |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
readTemplate( $name, $skin ) ==> $text
Description: | Read a template or skin file. Embedded template directives get expanded |
Parameter: $name | Template name, e.g. "view" |
Parameter: $skin | Skin name, optional, e.g. "print" |
Return: $text | Template text |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
readFile( $filename ) ==> $text
Description: | Read text file, low level. NOTE: For topics use readTopicText() |
Parameter: $filename | Full path name of file |
Return: $text | Content of file |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
saveFile( $filename, $text )
Description: | Save text file, low level. NOTE: For topics use saveTopicText() |
Parameter: $filename | Full path name of file |
Parameter: $text | Text to save |
Return: | none |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
TODO: | This should return an error for the different failure modes. |
writeWarning( $text )
Description: | Log Warning that may require admin intervention to data/warning.txt |
Parameter: $text | Text to write; timestamp gets added |
Return: | none |
Since: | TWiki::Plugins::VERSION 1.020 (16 Feb 2004) |
writeDebug( $text )
Description: | Log debug message to data/debug.txt |
Parameter: $text | Text to write; timestamp gets added |
Return: | none |
Since: | TWiki::Plugins::VERSION 1.020 (16 Feb 2004) |
Functions: I18N related
getRegularExpression( $regexName ) ==> $pattern
Description: | Retrieves a TWiki predefined regular expression |
Parameter: $regexName | Name of the regular expression to retrieve. See notes below |
Return: | String or precompiled regular expression matching as described below |
Since: | TWiki::Plugins::VERSION 1.020 (9 Feb 2004) |
Notes: TWiki internally precompiles several regular expressions to represent various string entities
in an I18N-compatible manner. Plugins are encouraged to use these in matching where appropriate.
The following are guaranteed to be present; others may exist, but their use is unsupported and
they may be removed in future TWiki versions. Those which are marked "CC" are for use within
character classes and may not produce the desired results outside of them.
Name | Matches | CC |
upperAlpha | Upper case characters | Y |
lowerAlpha | Lower case characters | Y |
mixedAlpha | Alphabetic characters | Y |
mixedAlphaNum | Alphanumeric charactecs | Y |
wikiWordRegex | WikiWords | N |
Example:
my $upper = TWiki::Func::getRegularExpression("upperAlpha");
my $alpha = TWiki::Func::getRegularExpression("mixedAlpha");
my $capitalized = qr/[$upper][$alpha]+/;
setTopicRevisionTag( $web, $topic, $rev, $tag ) ==> $success
Description: | sets a names tag on the specified revision |
Parameter: $web | webname |
Parameter: $topic | topic name |
Parameter: $rev | the revision we are taging |
Parameter: $tag | the string to tag with |
Return: $success | |
TODO: | we need an error mechanism! |
Since: | TWiki::Plugins::VERSION 1.022 (20 April 2004) |
checkDependencies
Description: | checks a list of Perl dependencies at runtime |
Parameter: $context | Context description e.g. name of the module being checked |
Parameter: $deps | List of hashes containing dependency information |
Returns: | undef if dependencies are OK, an error message otherwise |
Since: | TWiki::Plugins::VERSION 1.025 (01 Aug 2004) |
The dependencies are expressed as a list of hashes. Each hash contains
the name of a package and (optionally) a boolean constraint on the VERSION
variable in that package. It is usually used from the
initPlugin
method
like this:
if( $TWiki::Plugins::VERSION >= 1.025 ) {
my @deps = (
{ package => 'TWiki::Plugins::CalendarPlugin', constraint => '>= 5.030' },
{ package => 'Time::ParseDate' },
{ package => 'Apache::VMonitor' }
);
my $err = TWiki::Func::checkDependencies( $pluginName, \@deps );
if( $err ) {
TWiki::Func::writeWarning( $err );
print STDERR $err; # print to webserver log file
return 0; # plugin initialisation failed
}
}
Copyright and License
Copyright (C) 2000-2004 Peter Thoeny,
Peter@ThoenyNOSPAM.com
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details, published at
http://www.gnu.org/copyleft/gpl.html
NOTE: Above text is copied from the TWiki::Plugins/PerlDocPlugin output of
TWiki::Func
in
twiki
format. In case you want to get dynamically updated documentation based on the actual Perl module, install the PerlDocPlugin and replace above text with
%PERLDOC{"TWiki::Func"}%
.
--
PeterThoeny - 31 Dec 2002
TWiki Site Tools
Utilities for searching, navigation, and monitoring site activity
TWikiSiteTools include utilities for navigating, searching and keeping up with site activity. Preferences can be configured by web or site-wide. You are currently in the
TWiki web. In particular, TWiki provides two highly configurable, automated site monitoring tools,
WebNotify, to email alerts when topics are edited, and
WebStats, to generate detailed activity reports.
WebNotify Recent Changes Alert
Each TWiki web has an automatic email alert service that sends a list of recent changes on a preset schedule, like once a day. Users can subscribe and unsubscribe using
WebNotify in each web. The Perl script
mailnotify
is called by a background process at regular intervals. The script sends an automated email to subscribed users if topics were changed in a web since the script was last run.
TWiki handles WebNotify entries that include the
WikiName of a user or a
TWikiGroup and an optional e-mail address. Example entries in WebNotify:
* Main.FredBloggs
* Main.FredBloggs - secondary@home.com
* Main.EngineeringGroup
The first entry is the default form, the notification gets sent to the e-mail address specified in the user's home page. The second entry lists an alternative e-mail address. The third entry specifies a group, the notification gets sent to each member of the group.
You can also use
%MAINWEB%
instead of
Main
, but this is not necessary even if you have renamed the main web by configuring
$mainWebname
in
TWiki.cfg
.
Configuring Outgoing Mail
JCuckoo will use the
Net::SMTP
module if it is installed on your system. Set this with the
SMTPMAILHOST
variable in
TWikiPreferences.
The notify e-mail uses the default
changes.tmpl
template, or a skin if activated in the
TWikiPreferences.
mailnotify also relies on two hidden files in each
TWiki/data/[web]
directory:
.changes
and
.mailnotify.
Make sure both are writable by your web server process.
.changes
contains a list of changes; go ahead and make this empty.
.mailnotify
contains a timestamp of the last time notification was done.
You can use an external mail program, like
sendmail
, if the
Net::SMTP
module is not installed. Set the program path in
$mailProgram
in
TWiki.cfg
.
- Net::SMTP can be easily disabled (ex: if there is an installation error) by setting
SMTPMAILHOST
in TWikiPreferences to an empty value.
- You can set a separate
SMTPSENDERHOST
variable to define the mail sender host (some SMTP installations require this).
Setting the Automatic Email Schedule
For Unix platforms: Edit the
cron
table so that
mailnotify
is called in an interval of your choice. Please consult
man crontab
of how to modify the table that schedules program execution at certain intervals. Example:
% crontab -e
0 2 * * * (cd /path/to/twiki/bin; ./mailnotify -q)
The above line will run mailnotify nightly at 02:00. The
-q
switch suppresses all normal output.
For ISP installations: Many ISPs don't allow hosted accounts direct cron access, as it's often used for things that can heavily load the server. Workaround scripts are available.
On Windows NT/2000: You can use a scheduled task if you have administrative privileges.
Note: AT on an NT machine is pretty limited.
Microsoft lists several third-party
replacements.
TWiki:Codev/CronTabWin is a free scheduler for Windows.
WebStatistics Site Usage Log
You can generate a listing manually, or on an automated schedule, of visits to individual pages, on a per web basis. Compiled as a running total on a monthly basis. Includes totals for Topic Views, Topic Saves, Attachment Uploads, Most Popular Topics with number of views, and Top Contributors showing total of saves and attachment uploads. Previous months are saved.
Configuring for Automatic Operation
- You can automatically generate usage statistics for all webs. To enable this:
- Make sure variable
$doLogTopicView, $doLogTopicSave and $doLogTopicUpload
in TWiki.cfg
are set. This will generate log file entries (see below).
- The WebStatistics topic 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 many 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)
Generating Statistics Manually by URL
- 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
Log File Details
TWiki generates monthly log files which are used by the statistics
- The log directory is defined by the
$logDir
variable in TWiki.cfg
- The file name is
log<year><month>.txt
- Example path name:
twiki/data/log202404.txt
- Each access gets logged as:
| <time> | <wikiusername> | <action> | <web>.<topic> | <extra info> | <IP address> |
- Example log entry:
| 20 Apr 2024 - 09:32 | Main.TWikiGuest | view | TWiki.WebRss | | 66.124.232.02 |
- Actions are logged if enabled in TWiki.cfg by the
$doLogTopic<action>
flags
- Logged actions:
Script | Action name | Extra info |
attach | attach | when viewing attach screen of previous uploaded attachment: filename |
changes | changes | |
edit | edit | when editing non-existing topic: (not exist) |
register | register | E-mail address |
save | save | when replacing existing revision: repRev 1.3 when user checks the minor changes box: dontNotify |
search | search | search string |
rdiff | rdiff | 1.4 1.3 |
rename | rename | when moving topic: moved to Newweb.NewTopic |
rename | move | when moving attachment: Attachment filename moved to Newweb.NewTopic |
upload | upload | filename |
view | view | when viewing non-existing topic: (not exist) when viewing previous topic revision: r1.3 |
WebSearch
WebSearch is an extremely fast and flexible search facility, part of the core TWiki feature set. Options include:
- topic title or full-text search
- regular expressions
- search within web or site-wide
- index-style A-Z alphabetical listing sorted topic title
- many more
See also:
TWikiVariables for including hard-coded searches in text.
WebChanges
To check for the most recently edited topics while on-site, use the
WebChanges link, usually located on the upper toolbar. It lists the most recently modified topics, newest first, along with the first couple of lines of the page content.
This is simply a preset
SEARCH
. The number of topics listed by the
limit
parameter.:
%SEARCH{".*" web="TWiki" regex="on" nosearch="on" order="modified"
reverse="on" limit="50"}%
WebIndex
WebIndex lists all web topics in alphabetical order, with the first couple of lines of text. This is simply a preset
SEARCH
:
%SEARCH{"\.*" scope="topic" regex="on" nosearch="on"}%
--
TWiki:Main.MikeMannix - 01 Dec 2001
--
TWiki:Main.PeterThoeny - 24 Apr 2004
Managing Topics
Browser-based rename, move, and delete for individual topics
Overview
You can use browser-based controls to change a topic's name, move it to another TWiki web, or delete it to a hidden
Trash
web.
How to Rename/Move/Delete a Topic
- Click on
[More]
(bottom right of page) on the topic to be changed, then, in the new screen, on [Rename/move]
. You can now rename and/or move/delete in one operation:
- Move/Delete: Select the target web if other than the current web - choose
Trash
to delete a topic.
- Rename: Enter the new topic name - default is current name
NOTE: You'll be warned if any of the topics to be affected are locked (being edited), or if there is a name conflict.
- Prevent updates by unchecking individual items on the list of referring links - these topics will NOT to be updated with the new name (by default, all referring links will be updated).
- Click on
[Rename/Move]
: the topic will be renamed and links to the topic updated as requested.
- If any of the referring pages are locked then they will be listed: you can correct these later by again pressing
[Rename/Move]
.
- There is a Put back feature that allows you to undo a
Rename/Move/Delete
- an instruction line and undo link will appear at the bottom of the modified topic. This allows you to revert from the last modification only.
Deleted Topics: How to Clear the Trash
Deleted topics are moved to a special
Trash
web - they are NOT physically erased from the server. All webs share
Trash
- in case of a name conflict with a topic already
Trash
, the user is alerted and asked to choose a new name.
The
Trash
web should be be cleared periodically, by archiving (saving) the text and RCS files if required (recommended), then deleting them from the
Trash
directory.
- This can only be done from on the server, not through the browser.
- Since simple FTP access to the
Trash
directory is all that's required for maintenance, it's possible to grant Trash
admin privileges to multiple users, while strictly limiting server access.
Redirecting from an Old Topic
You can use
TWikiMetaData to place a command in the
WebTopicViewTemplate and
WebTopicNonWikiTemplate that will indicate that a topic has been moved by searching for the tag %META:TOPICMOVED{...}%. Customize something like this:
%<nop>METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%"
title="This topic used to exist and was moved to: "}%
How Rename/Move Works
- %SEARCH%, with a special template, finds and displays all occurrences of the topic name in other topics, site-wide. These referring links are by default automatically changed to the new topic and/or web name. This includes relevant TWikiMetaData definitions.
- User can omit one or more topics from the update list by unchecking them.
-
<pre>
and <verbatim>
are honoured - no changes are made to text within these areas.
- The topic is moved (if locks allow).
- References are changed (locks and permissions permitting).
- Any referring topics that can't be changed due to locks are listed - user can take note and change them at another time.
How Referring Topics Are Found
Referring topics are found using the %SEARCH% variable - see the template
searchrenameview.tmpl
. First, matching topics in the current web are listed - matches are to
topic
. Next, all webs (including the current one) are listed that match
web.topic
. Because %SEARCH% is used, webs marked in
WebPreferences as
NOSEARCHALL
will not show up in the search for references to the
topic
being changed.
Changed references are kept are as short as possible, ex:
topic
is used in preference to
web.topic
.
Effect of User Access Settings
User permissions affect the Rename function in various ways. To rename a topic, you need both
ALLOWTOPICCHANGE
and
ALLOWTOPICRENAME
permission for that topic. To alter referring topics, you need change permission. See
TWikiAccessControl for information on setting up access permissions.
Special Considerations
Consider carefully whether to make browser-based
Rename/Move/Delete widely available, or to restrict it to an administrator/moderator group. Allowing all users to easily manipulate topics can be extremely useful in refactoring a busy web or site. However, there are at least two significant potential drawbacks to take into account:
- When referring links are updated, the modified topics appear in WebChanges, creating the impression that editorial changes were made. This can undermine the usefulness of WebChanges.
- Due to current limitations, fairly heavy use of Rename/Move/Delete functions can lead to an accumulation of minor technical problems (ex: broken links) and usability issues (ex: user confusion). If Rename... is used heavily, these negatives will obviously increase, in number and effect.
Ultimately, the size, objectives, and policies of your TWiki site, the real-world behavior of your user group, and most importantly, the initial TWiki site management leadership, will determine the most effective implementation of this feature, and the success of the site overall.
Known Issues
Rename/Move is fairly complicated due to the dynamic generation of links. Ideally, it would be possible to run the required part of rendering in a way that would allow identification of the text to be changed. Unfortunately, these hooks don't exist in TWiki at present. Instead, %SEARCH% is used with a special template to show the text to be changed, and the selected topics are then altered. One drawback is that
search
can show matches that will not be updated due to case differences. Other mismatches with actual rendered output are also possible as the approaches are so different.
The following shows some limitations of square bracket processing.
[[Old Topic]] => [[NewTopic][Old Topic]]
[[old topic]] => [[NewTopic][old topic]]
[[old t opic]] => not changed
[[OldTopic]] => [[NewTopic]]
--
MikeMannix? - 27 Dec 2001
Managing Webs
Adding webs is a web based operation; renaming and deleting webs are manual operations done directly on the server
Overview
A
TWikiSite is divided into webs; each one represents one subject, one area of collaboration. Administrators can add/rename/delete webs.
Choose Web Template
There are two methods used to create a new web. First you can use a specially designed
TemplateWeb. This is an invisible web that begins with an underscore "_" character. All topics in the _default template web will be copied into your new web.
The second method is to use an existing web as a template web. This may be useful if you already have a web that you like to use as a starting point. Only topics that have names beginning with
Web... (like "WebHome", "WebNotify", etc.) are copied.
In either case you will want to be sure to verify that your new web has all the custom modifications that you desire.
Adding a New Web
Note: Attachments will NOT get copied over along with their topics. This will be a feature added for the
TWiki:Codev/CairoRelease.
Note: This script does not yet edit the
TWiki.TWikiPreferences file to update the
WIKIWEBLIST
. This must be done by hand.
The manage script while creating the new web will update the following variables in the
WebPreferences:
WEBBGCOLOR
,
SITEMAPLIST
,
SITEMAPWHAT
,
SITEMAPUSETO
and
NOSEARCHALL
. These variables are now used to dynamically generate the
SiteMap.
Renaming or Deleting a Web
Renaming or deleting a web requires direct access to the installation files on the host server. There are currently no browser-based equivalents of the Rename/move/delete topic tools for working with webs.
NOTE: If you plan to rename the JCuckoo.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).
- 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
.
- Edit the TWikiPreferences topic: Rename or delete the web from the
WIKIWEBLIST
variable.
- Login to the JCuckoo server, via Telnet or FTP.
- Go to
twiki/data
and rename or remove the web directory.
- Go to
twiki/templates
and rename or remove the web directory if present.
- Go to
twiki/pub
and rename or remove the web directory if present.
--
MikeMannix? - 14 Sep 2001
--
PeterThoeny - 07 Apr 2002
--
GrantBow? - 16 Jan 2003
Appendix A: TWiki Filesystem
Annotated directory and file listings, for the 01-Feb-2003 TWiki production release.
Who and What is This Good For?
Interested
Users and
Site Administrators can find out in simple terms what each part of TWiki actually does. Adventurous
Adminstrators with server access to files (via telnet, ssh or ftp) can also figure out where to look to make minor modifications, like changing hardcode text or color.
Software Developers can get an at-a-glance overview of TWiki code architecture.
Directory Structure
You can rename the root TWiki directory -
twiki
- to whatever you like by changing it in the
TWiki.cfg
configuration file. However, to keep the current installation and future upgrades simple, you should leave the five main subdirectories intact:
Directory: | Files: | Used for: |
twiki | list | Start-up info |
twiki/bin | list | Perl scripts |
twiki/lib | list | Configuration file, main library, Perl system modules, Plugins directory |
twiki/pub | list | Public files (eg: images) and FileAttachments and their RCS histories |
twiki/data | list | Individual topics (page content) and their RCS histories |
twiki/templates | list | HTML templates, used by TWiki scripts |
File Descriptions
A rundown of the individual files included in the current distribution, organized by TWiki root directories.
Files in twiki
Application info and the current reference documentation.
Full file list:
File: | Used for: |
index.html | Links to launch TWiki after install and for files in this directory |
license.txt | GNU General Public License and TWiki-specific info |
readme.txt | General TWiki start-up info with relevant URLs |
TWikiDocumentation.html | All documentation packaged as a single page |
TWikiHistory.html | TWiki development timeline: versions, features, developers |
Files in twiki/bin
Perl CGI scripts.
Full file list:
File: | Used for: |
.htaccess.txt | Authentication. Rename to .htaccess and customize if used |
attach | Shows the attach file page (FileAttachment) |
edit | Edit a topic |
geturl | Fetch URL data |
installpasswd | Install new password by admin |
mailnotify | Script called by cron job to notify users of changes |
manage | Manage script to create new webs |
oops | Shows an OK or oops dialog |
passwd | Reset and change password |
preview | Preview topic after edit |
rdiff | See differences of topics |
register | Register new users |
rename | Rename/move topics and move attachments |
save | Saves a topic, called by preview |
search | Displays search results |
setlib.cfg | Location of the TWiki libraries. Customize if needed |
statistics | Create statistics topic |
testenv | Test CGI environment variables |
upload | Does file upload (FileAttachment) |
view | View a topic ( the script ) |
viewfile | View a file attachment |
Files under twiki/lib
The new
lib/TWiki/Plugins
directories contain configuration, library and function files, and
TWikiPlugins.
Full file list:
File: | Used for: |
TWiki.cfg | Main configuration, used by TWiki.pm |
TWiki.pm | Main TWiki library |
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/Store/RcsFile.pm | Generic file handling code, a class |
TWiki/Store/RcsWrap.pm | Wrappers around RCS executables, a class that inherits from RcsFile |
TWiki/Store/RcsLite.pm | A Perl RCS implemention, a class that inherits from RcsFile |
TWiki/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 topic-related files, including images used by TWiki and
FileAttachments. Attachments are stored in subdirectories created with the related topic name. You can also upload files directly for and link manually (but not through
Attach
)
Partial file list:
File: | Used for: |
favicon.ico | ICO file |
wikiHome.gif | GIF file |
icn/_filetypes.txt | Lookup table to translate file extension to file type |
icn/bat.gif | GIF file for file type |
icn/bmp.gif | GIF file for file type |
... | ... |
TWiki/FileAttachment/Sample.txt | TEXT file: sample |
TWiki/FileAttachment/Smile.gif | GIF image: sample |
TWiki/FileAttachment/Smile.gif,v | RCS repository for GIF file |
TWiki/PreviewBackground/blankltgraybg.gif | GIF image |
TWiki/PreviewBackground/blankwhitebg.gif | GIF image |
TWiki/PreviewBackground/previewbg.gif | GIF image: Preview view background |
TWiki/PreviewBackground/preview2bg.gif | GIF image: Alternate preview view background |
TWiki/TWikiLogos/twikiRobot121x54.gif | GIF image: TWiki logo |
... | ... |
TWiki/TWikiTemplates/testscreen.gif | GIF image: Screen shot |
TWiki/WabiSabi/wabisabi.gif | GIF image: illustration |
Know/IncorrectDllVersionW32PTH10DLL/W32PTH10.DLL | DLL file: sample |
Files under twiki/data
TWiki topics: data stored as individual text files and rendered by TWiki for display as regular Web pages. Each active web has its own subdirectory. The TWiki distribution includes four start-up webs -
Main
,
TWiki
,
Know
,
Sandbox
- with documentation and demo content, a
Trash
web for browser-based, recoverable topic deletion, and a
_default
directory containing a core topic set required to start a new web.
Partial file list:
File: | Used for: |
.htpasswd | Basic Authentication (htaccess) users file with username and encrypted password pairs |
debug.txt | Program-generated messages useful for debugging |
mime.types | Recognized file formats |
warning.txt | Diagnostic messages for identifying problems |
_default/.changes | Per web record of topic changes |
_default/.mailnotify | Per web timestamp of most recent email notification |
_default/WebChanges.txt | Display most recent topic changes in web |
_default/WebChanges.txt,v | Revisions history (RCS) |
_default/WebHome.txt | Default web home page |
_default/WebHome.txt,v | Revisions history (RCS) |
_default/WebIndex.txt | Lists all topics in a web |
_default/WebIndex.txt,v | Revisions history (RCS) |
_default/WebNotify.txt | Subscribe/unsubscribe to web changes email alert |
_default/WebNotify.txt,v | Revisions history (RCS) |
_default/WebPreferences.txt | Per web Preference Settings |
_default/WebPreferences.txt,v | Revisions history (RCS) |
_default/WebSearch.txt | Per web search options |
_default/WebSearch.txt,v | Revisions history (RCS) |
_default/WebStatistics.txt | Generates web usage statistics |
_default/WebStatistics.txt,v | Revisions history (RCS) |
_default/WebTopicList.txt | Lists all topics in a web in compact format |
_default/WebTopicList.txt,v | Revisions history (RCS) |
... | ... |
Files in twiki/templates
Templates and skins used to control appearance of topics rendered as Web pages.
Full file list:
File: | Used for: |
attach.tmpl | Attach (FileAttachments) control screen |
attachagain.tmpl | Attachment control screen |
attachnew.tmpl | Attachment control screen |
changeform.tmpl | Control screen to change the form in edit mode |
changes.tmpl | Displays list of recently changed topics |
edit.iejs.tmpl | Edit window with IE-specific JavaScript |
edit.tmpl | Main edit window |
mailnotify.tmpl | Email notification |
moveattachment.tmpl | Move attachment control screen |
oopsaccesschange.tmpl | Error message |
oopsaccesscreateweb.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 |
oopsmanage.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 |
oopsregemail.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 |
oopsrenamenotwikiword.tmpl | Error message |
oopsresetpasswd.tmpl | Error message |
oopsrev.tmpl | Error message |
oopssave.tmpl | Error message |
oopssaveerr.tmpl | Error message |
oopssendmailerr.tmpl | Error message |
oopstopicexists.tmpl | Error message |
oopsupload.tmpl | Error message |
oopswrongpassword.tmpl | Error message |
preview.tmpl | Preview Changes screen |
rdiff.tmpl | Displays text changes before & after Diffs |
registernotify.tmpl | Registration notification |
rename.tmpl | Rename/move control screen (choose web & new topic tile |
renamebase.tmpl | Used by other rename templates |
renameconfirm.tmpl | Confirms a pre-specified rename, ex: undoing a rename |
renamerefs.tmpl | Display if rename done, but some references not changed (topics were locked) |
search.tmpl | Search screen |
searchbookview.tmpl | Search results with full topic content |
searchformat.tmpl | Search screen for formatted search |
searchmeta.tmpl | Search screen |
searchrenameview.tmpl | Used by rename to list references to topic being renamed |
twiki.tmpl | Master template: definitions are used by other templates |
view.plain.tmpl | Skin for bare bone topic view without header/footer |
view.print.tmpl | Skin for printable topic view with a simple header/footer |
view.rss.tmpl | Skin for topic view in RDF XML format |
view.tmpl | Main topic view - the standard regular Web page |
TWiki File System Snapshot
The following partial directory listings from a Linux installation show typical file permissions and ownership. This is provided for general debugging use only and isn't an exact representation of the current distribution.
- On an ISP installation... The user and group -
twiki twiki
- will probably be your domain or login name, eg: yourdomain yourdomain
and can't be changed; same for nobody nobody
files further down. Also, in the bin
directory, scripts might need a .cgi
(sometimes .pl
) extension._
Directory
twiki/bin
:
drwxrwxr-x 2 twiki twiki 4096 Jan 7 23:56 .
drwxrwxr-x 5 twiki twiki 4096 Nov 18 12:21 ..
-rw-rw-r-- 1 twiki twiki 979 Aug 3 19:36 .htaccess
-rw-rw-r-- 1 twiki twiki 1598 Jun 1 2002 .htaccess.txt
-rwxrwxr-x 1 twiki twiki 4986 Jan 4 17:27 attach
-rwxrwxr-x 1 twiki twiki 3734 Jan 4 17:27 changes
-rwxrwxr-x 1 twiki twiki 9362 Jan 4 18:04 edit
-rwxrwxr-x 1 twiki twiki 1878 Jan 4 17:28 geturl
-rwxrwxr-x 1 twiki twiki 4587 Jan 4 17:28 installpasswd
-rwxrwxr-x 1 twiki twiki 7231 Jan 6 09:04 mailnotify
-rwxrwxr-x 1 twiki twiki 6000 Dec 11 01:26 makedistrib
-rwxrwxr-x 1 twiki twiki 8228 Jan 4 18:25 manage
-rwxrwxr-x 1 twiki twiki 2445 Jan 4 18:08 oops
-rwxrwxr-x 1 twiki twiki 6936 Jan 4 18:08 passwd
-rwxrwxr-x 1 twiki twiki 5820 Jan 4 17:30 preview
-rwxrwxr-x 1 twiki twiki 9235 Jan 4 17:31 rdiff
-rwxrwxr-x 1 twiki twiki 10584 Jan 4 18:09 register
-rwxrwxr-x 1 twiki twiki 14746 Jan 5 00:14 rename
-rwxrwxr-x 1 twiki twiki 4800 Jan 4 18:09 save
-rwxrwxr-x 1 twiki twiki 4729 Jan 4 17:32 search
-rw-rw-r-- 1 twiki twiki 1446 Jan 8 01:03 setlib.cfg
-rwxrwxr-x 1 twiki twiki 19261 Jan 4 17:33 statistics
-rwxrwxr-x 1 twiki twiki 30626 Jan 4 17:33 testenv
-rwxrwxr-x 1 twiki twiki 14306 Jan 4 18:11 upload
-rwxrwxr-x 1 twiki twiki 11414 Jan 5 01:12 view
-rwxrwxr-x 1 twiki twiki 2944 Jan 5 00:36 viewfile
Directory
twiki/templates/
:
drwxrwxr-x 2 twiki twiki 4096 Dec 11 00:38 .
drwxrwxr-x 4 twiki twiki 4096 Jan 8 01:03 ..
-rw-rw-r-- 1 twiki twiki 2590 Jan 7 22:53 attach.tmpl
-rw-rw-r-- 1 twiki twiki 1604 Aug 3 2001 attachagain.tmpl
-rw-rw-r-- 1 twiki twiki 449 Aug 3 2001 attachnew.tmpl
-rw-rw-r-- 1 twiki twiki 1276 Dec 9 21:48 changeform.tmpl
-rw-rw-r-- 1 twiki twiki 1620 Dec 9 21:48 changes.tmpl
-rw-rw-r-- 1 twiki twiki 12777 Jan 7 22:54 edit.iejs.tmpl
-rw-rw-r-- 1 twiki twiki 2801 Jan 7 22:54 edit.tmpl
-rw-rw-r-- 1 twiki twiki 975 Dec 9 21:48 mailnotify.tmpl
-rw-rw-r-- 1 twiki twiki 1606 Jan 7 22:54 moveattachment.tmpl
-rw-rw-r-- 1 twiki twiki 570 Aug 1 2001 oopsaccesschange.tmpl
-rw-rw-r-- 1 twiki twiki 596 Apr 13 2002 oopsaccesscreateweb.tmpl
-rw-rw-r-- 1 twiki twiki 586 Aug 1 2001 oopsaccessgroup.tmpl
-rw-rw-r-- 1 twiki twiki 573 Aug 1 2001 oopsaccessrename.tmpl
-rw-rw-r-- 1 twiki twiki 573 Aug 1 2001 oopsaccessview.tmpl
-rw-rw-r-- 1 twiki twiki 997 Nov 11 22:21 oopsauth.tmpl
-rw-rw-r-- 1 twiki twiki 405 Aug 1 2001 oopsbadpwformat.tmpl
-rw-rw-r-- 1 twiki twiki 344 Jul 31 2001 oopschangepasswd.tmpl
-rw-rw-r-- 1 twiki twiki 624 Jul 31 2001 oopsempty.tmpl
-rw-rw-r-- 1 twiki twiki 891 Dec 30 15:51 oopslocked.tmpl
-rw-rw-r-- 1 twiki twiki 589 Dec 30 15:55 oopslockedrename.tmpl
-rw-rw-r-- 1 twiki twiki 678 Apr 12 2002 oopsmanage.tmpl
-rw-rw-r-- 1 twiki twiki 328 Jul 31 2001 oopsmissing.tmpl
-rw-rw-r-- 1 twiki twiki 2352 Apr 13 2002 oopsmngcreateweb.tmpl
-rw-rw-r-- 1 twiki twiki 2322 Jan 7 22:55 oopsmore.tmpl
-rw-rw-r-- 1 twiki twiki 407 Aug 1 2001 oopsmoveerr.tmpl
-rw-rw-r-- 1 twiki twiki 1132 Nov 30 2001 oopsnoformdef.tmpl
-rw-rw-r-- 1 twiki twiki 520 Jan 4 18:21 oopsnotwikiuser.tmpl
-rw-rw-r-- 1 twiki twiki 1495 Apr 7 2002 oopsnoweb.tmpl
-rw-rw-r-- 1 twiki twiki 393 Aug 1 2001 oopspreview.tmpl
-rw-rw-r-- 1 twiki twiki 340 Dec 10 14:14 oopsregemail.tmpl
-rw-rw-r-- 1 twiki twiki 475 Jun 10 2002 oopsregexist.tmpl
-rw-rw-r-- 1 twiki twiki 345 Aug 1 2001 oopsregpasswd.tmpl
-rw-rw-r-- 1 twiki twiki 356 Aug 1 2001 oopsregrequ.tmpl
-rw-rw-r-- 1 twiki twiki 540 Aug 1 2001 oopsregthanks.tmpl
-rw-rw-r-- 1 twiki twiki 679 Aug 1 2001 oopsregwiki.tmpl
-rw-rw-r-- 1 twiki twiki 502 Mar 24 2002 oopsrenameerr.tmpl
-rw-rw-r-- 1 twiki twiki 433 May 19 2002 oopsrenamenotwikiword.tmpl
-rw-rw-r-- 1 twiki twiki 506 Jun 10 2002 oopsresetpasswd.tmpl
-rw-rw-r-- 1 twiki twiki 957 Jan 7 22:55 oopsrev.tmpl
-rw-rw-r-- 1 twiki twiki 774 Aug 1 2001 oopssave.tmpl
-rw-rw-r-- 1 twiki twiki 477 Aug 1 2001 oopssaveerr.tmpl
-rw-rw-r-- 1 twiki twiki 465 Jun 10 2002 oopssendmailerr.tmpl
-rw-rw-r-- 1 twiki twiki 379 Aug 1 2001 oopstopicexists.tmpl
-rw-rw-r-- 1 twiki twiki 342 Jul 31 2001 oopsupload.tmpl
-rw-rw-r-- 1 twiki twiki 364 Aug 1 2001 oopswrongpassword.tmpl
-rw-rw-r-- 1 twiki twiki 2603 Jan 7 22:55 preview.tmpl
-rw-rw-r-- 1 twiki twiki 1719 Jan 7 22:56 rdiff.tmpl
-rw-rw-r-- 1 twiki twiki 1160 Dec 9 21:48 registernotify.tmpl
-rw-rw-r-- 1 twiki twiki 993 Jun 23 2002 rename.tmpl
-rw-rw-r-- 1 twiki twiki 2369 Jan 7 22:56 renamebase.tmpl
-rw-rw-r-- 1 twiki twiki 471 May 31 2002 renameconfirm.tmpl
-rw-rw-r-- 1 twiki twiki 595 May 31 2002 renamerefs.tmpl
-rw-rw-r-- 1 twiki twiki 1818 Jan 7 22:56 search.tmpl
-rw-rw-r-- 1 twiki twiki 1676 Jan 7 22:57 searchbookview.tmpl
-rw-rw-r-- 1 twiki twiki 980 Jan 7 22:57 searchformat.tmpl
-rw-rw-r-- 1 twiki twiki 149 Sep 13 2001 searchmeta.tmpl
-rw-rw-r-- 1 twiki twiki 2071 Jan 7 22:57 searchrenameview.tmpl
-rw-rw-r-- 1 twiki twiki 2284 Dec 9 21:48 twiki.tmpl
-rw-rw-r-- 1 twiki twiki 419 Dec 9 21:48 view.plain.tmpl
-rw-rw-r-- 1 twiki twiki 827 Dec 9 21:48 view.print.tmpl
-rw-rw-r-- 1 twiki twiki 300 Dec 14 17:16 view.rss.tmpl
-rw-rw-r-- 1 twiki twiki 1629 Jan 7 22:58 view.tmpl
Directory
twiki/data/
:
drwxrwxr-x 8 nobody nobody 4096 Jan 3 23:50 .
drwxrwxr-x 4 twiki twiki 4096 Jan 8 01:03 ..
-rw-rw-rw- 1 twiki twiki 210 Jan 11 15:58 .htpasswd
drwxrwxr-x 2 nobody nobody 4096 Dec 11 02:15 Know
drwxrwxr-x 2 nobody nobody 4096 Jan 11 17:45 Main
drwxrwxr-x 2 nobody nobody 4096 Dec 11 02:15 Sandbox
drwxrwxr-x 2 nobody nobody 8192 Jan 11 22:45 TWiki
drwxrwxr-x 2 nobody nobody 4096 Dec 11 02:15 Trash
drwxrwxr-x 2 nobody nobody 4096 Dec 11 01:01 _default
-rw-rw-rw- 1 twiki twiki 0 Aug 2 14:16 debug.txt
-rw-rw-r-- 1 nobody nobody 36630 Jan 11 22:26 log200301.txt
-rw-rw-r-- 1 twiki twiki 3419 Aug 13 2001 mime.types
-rw-rw-rw- 1 twiki twiki 1320 Dec 11 00:18 warning.txt
Partial file list for
twiki/data/Main
:
- Included files come with their RCS versions histories
.txt,v
.
drwxrwxr-x 2 nobody nobody 4096 Jan 11 17:45 .
drwxrwxr-x 8 nobody nobody 4096 Jan 3 23:50 ..
-rw-rw-rw- 1 twiki twiki 3662 Jan 11 16:29 .changes
-rw-rw-rw- 1 twiki twiki 9 Oct 25 2001 .mailnotify
-rw-r--r-- 1 nobody nobody 280 Dec 15 2000 TokyoOffice.txt
-rw-r--r-- 1 nobody nobody 774 Dec 15 2000 TokyoOffice.txt,v
-rw-r--r-- 1 nobody nobody 124 Aug 16 2001 WebChanges.txt
-r--r--r-- 1 nobody nobody 526 Aug 16 2001 WebChanges.txt,v
-rw-r--r-- 1 nobody nobody 1721 Jun 28 2002 WebHome.txt
-r--r--r-- 1 nobody nobody 11314 Jun 28 2002 WebHome.txt,v
-rw-r--r-- 1 nobody nobody 176 Nov 24 2001 WebIndex.txt
-r--r--r-- 1 nobody nobody 483 Nov 24 2001 WebIndex.txt,v
-rw-r--r-- 1 nobody nobody 729 Mar 24 2001 WebNotify.txt
-r--r--r-- 1 nobody nobody 2981 Mar 24 2001 WebNotify.txt,v
-rw-r--r-- 1 nobody nobody 3670 Apr 12 2002 WebPreferences.txt
-r--r--r-- 1 nobody nobody 8203 Apr 12 2002 WebPreferences.txt,v
-rw-r--r-- 1 nobody nobody 158 Aug 7 2001 WebSearch.txt
-r--r--r-- 1 nobody nobody 18332 Aug 7 2001 WebSearch.txt,v
-rw-r--r-- 1 nobody nobody 850 Dec 11 00:58 WebStatistics.txt
-r--r--r-- 1 nobody nobody 1690 Dec 11 00:58 WebStatistics.txt,v
-rw-r--r-- 1 nobody nobody 182 Nov 24 2001 WebTopicList.txt
-r--r--r-- 1 nobody nobody 371 Nov 24 2001 WebTopicList.txt,v
Directory
twiki/pub/
:
drwxrwxr-x 8 nobody nobody 4096 Nov 18 12:31 .
drwxrwxr-x 3 twiki twiki 4096 Nov 18 12:31 ..
drwxrwxr-x 3 nobody nobody 4096 Nov 18 12:31 Know
drwxrwxr-x 2 nobody nobody 4096 Apr 7 2002 Main
drwxrwxr-x 2 nobody nobody 4096 Apr 20 2002 Sandbox
drwxrwxr-x 8 nobody nobody 4096 Nov 18 12:31 TWiki
drwxrwxr-x 2 nobody nobody 4096 Dec 3 2001 Trash
-rw-rw-r-- 1 twiki twiki 1078 Jan 14 2000 favicon.ico
drwxrwxr-x 2 twiki twiki 4096 Nov 18 12:31 icn
-rw-rw-r-- 1 twiki twiki 2877 Jun 7 1999 wikiHome.gif
Partial file list for
twiki/pub/icn/
:
drwxrwxr-x 2 twiki twiki 4096 Nov 18 12:31 .
drwxrwxr-x 8 nobody nobody 4096 Nov 18 12:31 ..
-rw-rw-r-- 1 twiki twiki 801 Mar 26 1999 _filetypes.txt
-rw-rw-r-- 1 twiki twiki 143 Mar 9 1999 bat.gif
-rw-rw-r-- 1 twiki twiki 926 Mar 9 1999 bmp.gif
-rw-rw-r-- 1 twiki twiki 141 Mar 25 1999 c.gif
-rw-rw-r-- 1 twiki twiki 144 Mar 9 1999 dll.gif
-rw-rw-r-- 1 twiki twiki 152 Mar 9 1999 doc.gif
Directory
twiki/pub/TWiki
:
drwxrwx--x 8 nobody nobody 4096 Nov 18 12:31 .
drwxrwxr-x 8 nobody nobody 4096 Nov 18 12:31 ..
drwxrwxr-x 2 nobody nobody 4096 Nov 18 12:31 FileAttachment
drwxrwxr-x 2 nobody nobody 4096 Nov 18 12:31 PreviewBackground
drwxrwxr-x 2 nobody nobody 4096 Nov 18 12:31 TWikiDocGraphics
drwxrwxr-x 2 nobody nobody 4096 Nov 18 12:31 TWikiLogos
drwxrwxr-x 2 nobody nobody 4096 Nov 18 12:31 TWikiTemplates
drwxrwxr-x 2 nobody nobody 4096 Nov 18 12:31 WabiSabi
Directory
twiki/pub/TWiki/FileAttachment
:
drwxrwxr-x 2 nobody nobody 4096 Nov 18 12:31 .
drwxrwx--x 8 nobody nobody 4096 Nov 18 12:31 ..
-rw-rw-r-- 1 nobody nobody 30 Jul 22 1999 Sample.txt
-rw-rw-r-- 1 nobody nobody 94 Jun 7 1999 Smile.gif
-r--r--r-- 1 nobody nobody 81 Aug 15 10:14 Smile.gif,v
--
PeterThoeny - 11 Jan 2003
--
MikeMannix? - 16 May 2002
Appendix B: TWiki Development Timeline
01-Feb-2003 Release (Beijing)
- 18 Jan 2003 - PeterThoeny
- 31 Dec 2002 - PeterThoeny
- Enhanced Plugin API to manipulate topic data with new functions in TWikiFuncModule:
readTopicText
, saveTopicText
, setTopicEditLock
, checkTopicEditLock
- 31 Dec 2002 - PeterThoeny
- 29 Dec 2002 - AndreaSterbini?, PeterThoeny, RichardDonkin?, SvenDowideit?
- New Plugin hooks
registrationHandler
, beforeEditHandler
, afterEditHandler
, beforeSaveHandler
, writeHeaderHandler
, redirectCgiQueryHandler
, getSessionValueHandler
, setSessionValueHandler
- 30 Nov 2002 - RichardDonkin?
- Internationalization ('I18N') support for international characters in WikiWords, such as ISO-8859-15, KOI8-R - also supports Chinese, Japanese, etc.
- 25 Nov 2002 - PeterThoeny
- Include previous topic revision with
%INCLUDE{ "OtherTopic" rev="1.2" }%
- 15 Nov 2002 - PeterThoeny
- The Go box understands also URLs, useful for special TWikiSkins handling
- 08 Nov 2002 - ColasNahaboo?, RichardDonkin?
- In WebNotify, if only the WikiName is specified, the e-mail is taken from the user's home page; if the WikiName is a group name, a notification is sent to all members of the group
- 30 Oct 2002 - PeterThoeny
- New
%NOP{}%
variable in TWikiTemplates topic gets removed at topic creation time; useful to write protect template topics
- 28 Sep 2002 - PeterThoeny
- The
%URLPARAM{}%
variable in TWikiTemplates topic gets expanded at topic creation time; useful for dynamic content creation
- 28 Sep 2002 - PeterThoeny
- New
$logDir
introduced in TWiki.cfg to set the log directory
- 13 Sep 2002 - PeterThoeny
- Renamed the Test web to Sandbox
- 03 Aug 2002 - RichardDonkin?
- New
setlib.cfg
file in the bin directory to set the TWiki library path
- 02 Aug 2002 - PeterThoeny, RyanFreebern?
- Support for outbound HTTP proxy when including URLs based on new
%PROXYHOST
and %PROXYPORT%
settings in the TWikiPreferences
- 12 Jul 2002 - PeterThoeny
- The page logo is configurable with new
%WIKILOGOIMG%
, %TWIKILOGOURL%
and %WIKILOGOALT%
variables in TWikiPreferences; replacing $wikiHomeUrl
in TWiki.cfg
- 12 Jun 2002 - PeterThoeny
- New
%WIKITOOLNAME%
variable in TWikiPreferences; replacing $wikiToolName
in TWiki.cfg
- 31 May 2002 - PeterThoeny
- New
%EDITBOXSTYLE%
preferences variable which sets the edit box width automatically to the window width
- 17 May 2002 - PeterThoeny
- New
%URLENCODE{}%
variable to encodes a string for using in a URL parameter, e.g. %URLENCODE{"spaced name"}%
returns spaced%20name
- 17 May 2002 - PeterThoeny
- 05 May 2002 - PeterThoeny
- New user home pages are now based on the NewUserTemplate, replacing the
/twiki/templates/register.tmpl
template file
- 26 Apr 2002 - PeterThoeny
- New markup to exclude heading from a
%TOC%
table of content, e.g. ---+!! This heading
is not shown in a TOC
- 13 Apr 2002 - PeterThoeny
- 01 Apr 2002 - JohnTalintyre?
- New data storage framework that lets you use external RCS commands for revision control, or a new native Perl implementation that does not depend on the external RCS commands
- 28 Mar 2002 - RichardDonkin?
- Fixed IE5/IE6-specific problem whereby going back from preview sometimes removes all edit changes
- 23 Mar 2002 - JohnTalintyre?
- New AND search; with regular expression enabled, use the semicolon ";" as the AND operator in
%SEARCH{}%
variable, FormattedSearch and WebSearch
- 21 Mar 2002 - ColasNahaboo?, RichardDonkin?
- Fixed cache issue where the edit page showed outdated content
- 06 Mar 2002 - RichardDonkin?
- Improved statistics script which uses less memory to process large log files
- 09 Jan 2002 - JohnTalintyre?
- Variables inside
<verbatim>
tags are no longer expanded
01-Dec-2001 Release (Athens)
01-Sep-2001 Release
- 30 Aug 2001 - JohnTalintyre?
- Easier install for Windows, including auto detection in
TWiki.cfg
- 30 Aug 2001 - JohnTalintyre?
- 21 Aug 2001 - PeterThoeny
- Convert to XHTML 1.0 function: first step to XHTML-ifying TWiki
- 26 Jun 2001 - JohnTalintyre?
- 07 Jun 2001 - PeterThoeny
- New topic templates as topics instead of templates. Customize by editing the topic. Retired
notedited.tmpl
, notext.tmpl
and notwiki.tmpl
templates. More in TWikiTemplates.
- 07 Jun 2001 - PeterThoeny
- New
%TOPICLIST{"format"}%
and %WEBLIST{"format"}%
variables to get a formatted topic index and web index, respectively. More in TWikiVariables.
- 01 Jun 2001 - PeterThoeny
- New
%URLPARAM{"name"}%
variable to query URL parameters. More in TWikiVariables.
- 01 Jun 2001 - AndreaSterbini?
- 01 Jun 2001 - KlausWriessnegger?, AndreaSterbini?
- 01 May 2001 - AndreaSterbini?
- 01 May 2001 - JohnTalintyre?
- 01 May 2001 - JohnTalintyre?
- 01 May 2001 - JohnTalintyre?
- 27 Mar 2001 - PeterThoeny
- The table syntax has been enhanced to (i) render
| *bold* |
cells as table headers, (ii) render space padded cells | center aligned |
and | right aligned |
, (iii) span multiple columns using | empty cells |||
. More in TextFormattingRules.
- 25 Mar 2001 - PeterThoeny
- 28 Feb 2001 - AndreaSterbini?, PeterThoeny
- New Wiki rule for headings, i.e.
---++ My Title
; and new %TOC%
variable to build a table of content from headings in a topic. More in TWikiVariables.
- 28 Feb 2001 - PeterThoeny
- New Wiki rule to specify arbitrary text for external links (i.e.
[[http://TWki.org][TWiki]]
) and internal links (i.e [[WikiSyntax][syntax]]
). More in TWikiVariables.
- 28 Feb 2001 - PeterThoeny
- New Wiki rule for named anchors, e.g. links within a topic. Define a named anchor with
#MyAnchor
at the beginning of a line, and link to it with [[#MyAnchor]]
. More in TWikiVariables.
- 25 Feb 2001 - NicholasLee?, PeterThoeny
- Use
Net::SMTP
module instead of sendmail
if installed.
- 01 Feb 2001 - PeterThoeny
- Added
<verbatim>
... </verbatim>
tags to show source code "as is". Unlike the <pre>
... </pre>
tags, it also shows <
, >
, &
characters "as is".
- 01 Feb 2001 - PeterThoeny
- 21 Jan 2001 - PeterThoeny
- Added a "Minor change, don't notify" checkbox in preview. More in DontNotify.
- 21 Jan 2001 - PeterThoeny
- Added Bold Fixed formatting using double-equal signs, e.g. write
==Bold Fixed==
to get Bold Fixed
.
- 20 Jan 2001 - PeterThoeny
- Format changed of
%GMTIME{"..."}%
and %SERVERTIME{"..."}%
variables. Format is now "$hour:$min"
instead of "hour:min"
. More in TWikiVariables. Attention: Check your existing topics when you upgrade TWiki!
- 18 Jan 2001 - PeterThoeny
- WebChanges, WebSearch and e-mail notification indicate also the revision number of a topic (i.e. 18 Jan 2001 16:43 r1.5), or NEW for a new topic (i.e. i.e. 18 Jan 2001 16:43 NEW).
- 16 Jan 2001 - PeterThoeny
- New variable
%STARTINCLUDE%
and %STOPINCLUDE%
variables to control what gets included of a topic. More in TWikiVariables.
- 16 Jan 2001 - PeterThoeny
- TWiki skins Define a different page layout with a customized header and footer layout, i.e. a
print
skin for a printable view of a topic. More in TWikiSkins and TWiki:Codev/TWikiSkins.
- 07 Jan 2001 - StanleyKnutson?
- Better error handling when saving a topic.
- 05 Jan 2001 - PeterThoeny
- 05 Dec 2000 - PeterThoeny
- 03 Dec 2000 - PeterThoeny
- New
noheader="on"
switch in %SEARCH{...}%
to suppress table header. More in TWikiVariables.
01-Dec-2000 Release
- 03 Nov 2000 - PeterThoeny
- Flag
$doHidePasswdInRegistration
in wikicfg.pm
to hide plain text password in registration email.
- 01 Nov 2000 - PeterThoeny
- New variable
%VAR{"NAME" web="Web"}%
to get web specific preferences. More in TWikiVariables.
- 01 Nov 2000 - PeterThoeny
- Added a "Cancel" link in edit that releases the edit lock.
- 23 Oct 2000 - PeterThoeny
- 05 Oct 2000 - PeterThoeny
- Remember user by IP address so that
view
"knows" the user once authenticated in edit
. More in TWikiUserAuthentication.
- 26 Sep 2000 - AlWilliams?, PeterThoeny
- 26 Sep 2000 - HaroldGottschalk?, AndreaSterbini?, PeterThoeny
- 20 Sep 2000 - ManpreetSingh?
- New -q switch in
mailnotify
to suppress all normal output.
- 19 Sep 2000 - PeterThoeny
- 18 Sep 2000 - ManpreetSingh?, PeterThoeny
- 19 Aug 2000 - PeterThoeny
- Ref-By link searches all webs (not just the current web.)
- 16 Aug 2000 - PeterThoeny
- New TWikiPreferences variables
%HTTP_EQUIV_ON_VIEW%
, %HTTP_EQUIV_ON_EDIT%
and %HTTP_EQUIV_ON_PREVIEW%
that define the <meta http-equiv="...">
meta tags for the TWiki templates. This can be used for example to set a document expiration time.
- 29 Jul 2000 - PeterThoeny
- New variables
%GMTIME{"..."}%
and %SERVERTIME{"..."}%
. More in TWikiVariables.
- 23 Jul 2000 - PeterThoeny
- Changed include syntax from
%INCLUDE{"Web/TopicName.txt"}%
to %INCLUDE{"Web.TopicName"}%
. Legacy syntax still supported.
- 23 Jul 2000 - PeterThoeny
- BookView search allows you show a set of topics for easy printing.
- 22 Jul 2000 - PeterThoeny
- More forgiving syntax for
*bold*, italic, __bold italic__
and fixed
, where it is not necessary anymore to have a trailing space before .,;:?!
characters.
- 22 Jul 2000 - PeterThoeny
- Split the TWiki.Main web into TWiki.Main (users, company data) and TWiki.TWiki (TWiki related documentation, registration)
- 07 Jul 2000 - PeterThoeny
- Added an "Release edit lock" checkbox in preview to let other people edit the topic immediately without the one hour lock.
- 07 Jul 2000 - PeterThoeny
- Fixed problem of losing carriage returns when editing topics with KDE KFM browser or W3M browser.
- 21 Jun 2000 - PeterThoeny
- Fixed problem that a page redirect on some server environments is not working (host name is needed in URL).
- 21 Jun 2000 - CrisBailiff?, PeterThoeny
- Fixed security issue to prevent a server side
%INCLUDE%
of arbitrary files.
- 29 May 2000 - PeterThoeny
- New
%GMTIME%
variable that shows the current GM time.
- 28 May 2000 - PeterThoeny
- Lock warning shows remaining lock time in minutes.
- 15 May 2000 - PeterFokkinga?
- 02 May 2000 - KevinKinnell?, PeterThoeny
- Advanced search features like search multiple webs; sort by topic name / modified time / author; limit the number of results returned. More in TWikiVariables.
01-May-2000 Release
- 21 Apr 2000 - PeterThoeny
- New TWikiVariables
%HTTP_HOST%
, %REMOTE_ADDR%
, %REMOTE_PORT%
and %REMOTE_USER%
.
- 21 Apr 2000 - JohnAltstadt?, PeterThoeny
- TWikiRegistration is done separately for Intranet use (depends on remote_user) or Internet use (depends on .htpasswd file).
- 20 Mar 2000 - PeterThoeny
- Uploading a file (topic file attachment) will optionally create a link to the uploaded file at the end of the topic. The preference variable
%ATTACHLINKBOX%
controls the default state of the link check box in the attach file page.
- 11 Mar 2000 - PeterThoeny
- Better security with taint checking (
Perl -T
option )
- 25 Feb 2000 - PeterThoeny
- New preference variables
%EDITBOXWIDTH%
and %EDITBOXHEIGHT%
to specify the edit box size.
- 25 Feb 2000 - PeterThoeny
- Edit preferences topics to set TWiki variables. There are three level of preferences Site-level (TWikiPreferences), web-level (WebPreferences in each web) and user-level preferences (for each of the TWikiUsers). With this, discontinue use of server side include of
wikiwebs.inc
, wikiwebtable.inc
, weblist.inc
, webcopyright.inc
and webcolors.inc
files.
- 11 Feb 2000 - PeterThoeny
- New variable
%SCRIPTSUFFIX%
/ $scriptSuffix containing an optional file extension of the TWiki Perl script. Templates have been changed to use this variable. This allows you to rename the Perl script files to have a file extension like for example ".cgi".
- 11 Feb 2000 - PeterThoeny
- New variable
%SCRIPTURLPATH%
/ $scriptUrlPath containing the script URL without the domain name. Templates have been changed to use this variable instead of %SCRIPTURL%
. This is for performance reasons.
- 07 Feb 2000 - PeterThoeny
- Changed the syntax for server side include variable from
%INCLUDE:"filename.ext"%
to %INCLUDE{"filename.ext"}%
. (Previous syntax still supported. Change was done because of inline search syntax)
- 07 Feb 2000 - PeterThoeny
- Inline search. New variable
%SEARCH{"str" ...}%
to show a search result embedded in a topic text. TWikiVariables has more on the syntax. Inline search combined with the category table feature can be used for example to create a simple bug tracking system.
- 04 Feb 2000 - PeterThoeny
- Access statistics. Each web has a WebStatistics topic that shows monthy statistics with number of topic views and changes, most popular topics, and top contributors. (It needs to be enabled, TWikiDocumentation has more.)
- 29 Jan 2000 - PeterThoeny
- Fixed bug where TWiki would not initialize correctly under certain circumstances, i.e. when running it under mod_perl. Sub
initialize
in wiki.pm
did not handle $thePathInfo
correctly.
- 24 Jan 2000 - PeterThoeny
- 10 Jan 2000 - PeterThoeny
- No more escaping for '%' percent characters. (Number of consecutive '%' entered and displayed is identical.)
- 03 Oct 1999 - PeterThoeny
- Limit the number of revisions shown at the bottom of the topic. Example
Topic TWikiHistory . { ..... Diffs r1.10 > r1.9 > r1.8 > r1.7 >... }
Additional revisions can be selected by pressing the >...
link.
01-Sep-1999 Release
- 31 Aug 1999 - PeterThoeny
- Fixed Y2K bug. (Date in year 2000 had wrong format.)
- 08 Aug 1999 - PeterThoeny
- New text formatting rule for creating tables. Text gets rendered as a table if enclosed in " " vertical bars. Example line as it is written and how it shows up
- 03 Aug 1999 - PeterThoeny
- Online registration of new user using web form in TWikiRegistration. Authentication of users.
- 22 Jul 1999 - PeterThoeny
- Flags
$doLogTopic*
in wikicfg.pm to selectively log topic view, edit, save, rdiff, attach, search and changes to monthly log file.
- 21 Jul 1999 - PeterThoeny
- Flag
$doRemovePortNumber
in wikicfg.pm to optionally remove the port number from the TWiki URL. Example www.some.domain:1234/twiki
gets www.some.domain/twiki
.
- 15 Jul 1999 - PeterThoeny
- Search path for include files in
%INCLUDE:"file.inc"%
variable. Search first in the current web, then in parent data directory. Useful to overload default include text in the data directory by web-specific text, like for example webcopyright.inc
text.
- 07 Jul 1999 - ChristopheVermeulen?
- Link a plural topic to a singular topic in case the plural topic does not exist. Example
TestVersion
/ TestVersions
, TestPolicy
/ TestPolicies
, TestAddress
/ TestAddresses
, TestBox
/ TestBoxes
.
01-Jul-1999 Release
- 23 Jun 1999 - PeterThoeny
- New TextFormattingRules to write bold italic text by enclosing words with double underline characters.
- 23 Jun 1999 - PeterThoeny
- Separate wiki.pm into configuration (wikicfg.pm) and TWiki core (wiki.pm) . This is to ease the upgrade of TWiki installations, it also allows customized extensions to TWiki without affecting the TWiki core.
- 21 May 1999 - DavidWarman?
- Externalize copyright text at the bottom of every page into a web-specific
webcopyright.inc
file. This is to easily customize the copyright text.
- 20 May 1999 - PeterThoeny
- Added meta tag so that robots index only /view/ of topics, not /edit/, /attach/ e.t.c. Tag <META NAME="ROBOTS" CONTENT="NOINDEX">
- 20 May 1999 - PeterThoeny
- New variables
%WIKIHOMEURL%
(link when pressing the icon on the upper left corner) and %WIKITOOLNAME%
(the name of the wiki tool JCuckoo
).
- 15 Apr 1999 - PeterThoeny
- Topic locking Warn user if a topic has been edited by an other person within one hour. This is to prevent contention, e.g. simultaneous topic updates.
- 26 Mar 1999 - PeterThoeny
- File attachments Upload and download any file as a topic attachment by using the browser. FileAttachment has more.
- 26 Mar 1999 - PeterThoeny
- New variables
%PUBURL%
(Public directory URL) and %ATTACHURL%
(URL of topic file attachment).
- 09 Feb 1999 - PeterThoeny
- New text formatting rule for creating
fixed font text
. Words get showns in fixed font
by enclosing them in "=" equal signs. Example Writing =fixed font= will show up as fixed font
.
- 09 Feb 1999 - PeterThoeny
- No new topic revision is created if the same person saves a topic again within one hour.
- 03 Feb 1999 - PeterThoeny
- Possible to view complete revision history of a topic on one page. Access at the linked date in the Changes page, or the
Diffs
link at the bottom of each topic, e.g.
Topic TWikiHistory . { Edit Ref-By Diffs r1.3 > r1.2 > r1.1 }
Revision r1.3 1998/11/10 01:34 by PeterThoeny
- 04 Jan 1999 - PeterThoeny
- Fixed bug when viewing differences between topic revisions that include HTML table tags like <table>, <tr>, <td>.
1998 Releases
- 08 Dec 1998 - PeterThoeny
- Signature is shown below the text area when editing a topic. Use this to easily copy & paste your signature into the text.
- 07 Dec 1998 - PeterThoeny
- Possible to add a category table to a TWiki topic. 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. TWikiDocumentation has more on setup. The TWiki.Know web uses this category table to set classification, platform and OS version.
- 18 Nov 1998 - PeterThoeny
- Internal log of topic save actions to the file
data/logYYYYMM.txt
, where YYYYMM
the year and month in numeric format is. Intended for auditing only, not accessible from the web.
- 10 Nov 1998 - PeterThoeny
- The email notification and the Changes topic have now a topic date that is linked. Clicking on the link will show the difference between the two most recent topic revisions.
- 10 Nov 1998 - PeterThoeny
- View differences between topic revisions. Each topic has a list of revisions (e.g.
r1.3
) and differences thereof (e.g. >
) at the bottom
Topic TWikiHistory . { Edit Ref-By r1.3 > r1.2 > r1.1 }
Revision r1.3 1998/11/10 01:34 by PeterThoeny
- 26 Oct 1998 - PeterThoeny
- Added preview of topic changes before saving the topic. This was necessary to prevent unneeded revisions.
- 26 Oct 1998 - PeterThoeny
- Added revision control using RCS. Each topic has now a list of revisions at the bottom and a revision info, e.g.
Topic TWikiHistory . { Edit Ref-By r1.3 r1.2 r1.1 }
Revision r1.3 1998/10/26 01:34:00 by PeterThoeny
- 14 Oct 1998 - PeterThoeny
- Refered-By Find out which topics have a link to the current topic. Each topic has a Ref-By link for that. Note Only references from the current web are shown, not references from other webs.
- 13 Oct 1998 - PeterThoeny
- 24 Sep 1998 - PeterThoeny
- Corrected templates for automatic email notification so that MS Outlook can display attachment as an HTML file.
- 13 Aug 1998 - PeterThoeny
- WikiNotation allows also numbers after the
AaA
sequence, e.g. AaA1
is a valid WikiTopic name, but not Aa1
.
- 07 Aug 1998 - PeterThoeny
- Automatic email notification when something has changed in a TWiki web. Each web has a topic WebNotify where one can subscribe and unsubscribe.
- 06 Aug 1998 - PeterThoeny
- Added server side include of files. Syntax is
%INCLUDE:"filename.ext"%
- 05 Aug 1998 - PeterThoeny
- Signature and date is inserted automatically when creating a new topic.
- 04 Aug 1998 - PeterThoeny
- Separate templates for text of non existing topic and default text of new topic. (template file templates/Web/notedited.tmpl)
- 04 Aug 1998 - PeterThoeny
- Warn user if new topic name is not a valid Wiki name. (template file templates/Web/notwiki.tmpl)
- 31 Jul 1998 - PeterThoeny
- Support for quoted text with a '>' at the beginning of the line.
- 28 Jul 1998 - PeterThoeny
- Added TWiki variables, enclosed in % signs
%TOPIC%
(Topic name), %WEB%
(web name), %SCRIPTURL%
(script URL), %DATE%
(current date), %WIKIWEBMASTER%
(Wiki webmaster address), %WIKIVERSION%
(Wiki version), %USERNAME%
(user name), %WIKIUSERNAME%
(Wiki user name).
- 28 Jul 1998 - PeterThoeny
- Topic WebChanges shows Wiki username instead of Intranet username, e.g.
PeterThoeny
instead of thoeny
in case the Wiki username exists. Implementation Automatic lookup of Wiki username in topic TWikiUsers.
- 28 Jul 1998 - PeterThoeny
- Topic index. (Technically speaking a simple '.*' search on topic names.)
- 28 Jul 1998 - PeterThoeny
- Topic WebSearch allows full text search and and topic search with/without regular expressions.
- 27 Jul 1998 - PeterThoeny
- Added automatic links to topics in other TWiki webs by specifying <web name>.<topic name>, e.g.
Know.WebSeach
.
- 23 Jul 1998 - PeterThoeny
- Installed initial version, based on the JOS Wiki. See WikiWikiClones for details.
Dev Flow
The typical TWiki development flow...