configure
Resource | Required Server Environment * |
---|---|
Perl | 5.8.0 or higher (5.8.4 or higher is recommended) |
RCS | 5.7 or higher (including GNU diff ) Optional, TWiki includes a pure perl implementation of RCS that can be used instead (although it's slower) |
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 |
GNU df |
Used by the site statistics to record disk usage statistics, optional. The df command is pre-installed on Linux and OS-X. On Windows install the CoreUtils for Windows. |
GNU patch |
For upgrades only: GNU patch is required when using the TWiki:Codev.UpgradeTWiki script |
GNU fgrep , egrep |
Modify command line parameters in configure if you use non-GNU grep programs |
zip |
Zip archive command line utility. Used by the BackupRestorePlugin to create and restore from backups. |
Cron/scheduler | • Unix: cron • Windows: cron equivalents |
Web server | Apache is well supported; see TWiki:TWiki.InstallingTWiki#OtherWebServers for other servers |
Module | Preferred version | Comment |
---|---|---|
Algorithm::Diff |
Included in TWiki distribution | |
CGI |
>=3.18 | Versions 2.89 and 3.37 must be avoided. Most version from 3.15 and onwards should work. |
CGI::Carp |
>=1.26 | |
Config |
>=0 | |
Cwd |
>=3.05 | |
Data::Dumper |
>=2.121 | |
Encode |
>=2.1 | |
Error |
Included in TWiki distribution | |
File::Copy |
>=2.06 | |
File::Find |
>=1.05 | |
File::Spec |
>=3.05 | |
File::Temp |
>=0.18 | Included with perl 5.6 and later |
FileHandle |
>=2.01 | |
HTML::Parser |
>=3.28 | Needed by the WysiwygPlugin for WYSIWYG editing |
HTML::Entities |
>=1.25 | Needed by the WysiwygPlugin for WYSIWYG editing |
IO::File |
>=1.10 | |
Net::SMTP |
>=2.29 | Used for sending mail |
Text::Diff |
Included in TWiki distribution | |
Time::Local |
>=1.11 |
Module | Preferred version | Description |
---|---|---|
Archive::Tar |
May be required by the Extensions Installer in configure if command line tar or unzip is not available | |
Authen::SASL |
Used for SMTP Authentication | |
CGI::Cookie |
>=1.24 | Used for session support |
CGI::Session |
>=3.95 | Used for session support |
Crypt::SMIME |
>=0.09 | Required if S/MIME-signed administrative e-mail is enabled. |
Digest::base |
||
Digest::SHA1 |
||
Locale::Maketext::Lexicon |
>=0 | Used for I18N support |
Net::SMTP |
>=2.29 | Used for sending mail |
URI |
Used for configure |
configure
script, or if you're still trying to get to that point, check from the command line like this:
perl -e 'use FileHandle; print $FileHandle::VERSION."\n"'
TWiki-5.0.0.tgz
for Linux)
twiki
which contains the TWiki package. In the rest of this document we assume this directory is called twiki
. chmod -R 770 twiki
. The access rules have different meaning for files and directories. This is the most common mistake installers make.
chown -R user:group /path/to/twiki
. The webserver username varies from Distributions. Examples for some major distributions: chown -R apache:apache /path/to/twiki
chown -R www-data:www-data /path/to/twiki
chown -R wwwrun:www /path/to/twiki
/usr/bin/perl
. If it's somewhere else, change the path to Perl in the first line of each script in the twiki/bin
directory.
.cgi
or .pl
). This is normally only needed under Windows and only where perl scripts are only recognized by file extension. Linux and Unix users should normally never need to do this. If necessary, rename all files in twiki/bin
(i.e. rename view
to view.pl
etc). If you do this, make sure you set the ScriptSuffix
option in configure
(Step 6).
twiki/bin/LocalLib.cfg
twiki/bin/LocalLib.cfg.txt
. Simply copy LocalLib.cfg.txt to LocalLib.cfg. Make sure the ownership and access rights of the copy are the same as LocalLib.cfg.txt
twiki/bin/LocalLib.cfg
must contain a setting for $twikiLibPath
, which must point to the absolute file path of your twiki/lib
e.g. /var/www/twiki/lib
.
$CPANBASE
to point to your personal CPAN install. Don't forget that the webserver user has to be able to read those files as well.
twiki.conf
). Performance is much better with a config file, and one file gives the best overview and ensures that you get a safe installation . However using a config file requires that you can restart Apache which again means that you need root or sudo access to stop and start Apache. The TWiki apache config file is included from the main Apache config file http.conf. Most distributions have a directory from which any file that ends with .conf
gets included when you restart Apache (Example RedHat/Fedora/Centos: /etc/httpd/conf.d). If you use a virtual host setup in Apache you should include the twiki.conf file from inside the desired virtual host config in your Apache configuration.
twiki_httpd_conf.txt
twiki/bin
directory you find example .htaccess
files you can copy and modify. The files contains help text explaining how to set them up. In twiki/bin
you find .htaccess.txt
which can be copied to .htaccess
and defined access to the CGI scripts. In the root of TWiki you find pub-htaccess.txt
which you can copy to pub/.htaccess
, subdir-htaccess.txt
which you can copy to all directories as .htaccess
except bin and pub, and you find root-htaccess.txt
which you can copy to .htaccess
in the twiki root directory. But again only use .htaccess files if you do not have root priviledges.
configure
script open to the public. Limit access to the twiki/bin/configure
script to either localhost, an IP address or a specific user using basic Apache authentication. The TWiki:TWiki.ApacheConfigGenerator lets you setup who has access to the configure script. Also the example twiki-httpd-conf.txt and bin/.htaccess.txt files includes the needed setting to protect the configure script.
twiki/data/.htpasswd
but this file does not exist until you have TWiki running and have registered the first user. You therefore have two options. Either limit the access to localhost or an IP address, or make a .htpasswd file. To make a .htpasswd file change directory to twiki/data
and issue the command htpasswd -c .htpasswd username
and enter your password when asked. The username must match the Require user username
directive in the Apache config file or .htaccess file. Do not use a username you will later use to register in TWiki because TWiki will then claim that you are already registered.
configure
script from your browser (enter http://yourdomain/twiki/bin/configure
into your browser address bar) admin
user password once TWiki is running. $TWiki::cfg{Password}
from LocalSite.cfg
file from {TWIKI_ROOT}/lib
directory.
configure
for the first time, you can only edit the General Path Settings
section. Save these settings, and then return to configure
to continue configuration.
{PermittedRedirectHostUrls}
{WebMasterEmail}
, and {SMTP}{MAILHOST}
must be defined to enable TWiki to send administrative emails, such as for registration and notification of topic changes. Many ISPs have introduced authentication when sending emails to fight spam so you may also have to set {SMTP}{Username}
and {SMTP}{Password}
. If you do not want to enable mailing or want to enable it later you can uncheck {EnableEmail}
.
http://yourdomain.com/twiki/bin/view
and start TWiki-ing away!
pub
directory. TWiki has some built-in protection which renames files with dangerous filenames by appending .txt to the filename. But this is a secondary security measure. The essential action that you must take is to turn off any possible execution of any of the attached files.bin
and pub
directories. When you have access to the Apache config files the twiki_httpd_conf.txt
file mentioned above also contains protection of these directories.subdir-htaccess.txt
file can be copied as .htaccess
to the data, lib, locale, templates, tools and working directories.
twiki_httpd_conf.txt
and example htaccess.txt
files include the needed settings that protect against all 4 security elements.
TWiki.TWikiSkins
refers to the TWikiSkins
topic in your TWiki web. Easy way to jump directly to view the pages is to open your own TWiki in your browser and write TWiki.TWikiSkins
in the Jump test box to the right in the top bar and hit Enter. You can find these topics in the on-line reference copy at the official TWiki website: TWiki Release 5.0
Security Settings
pane of configure
: TWiki::LoginManager::TemplateLogin
for {LoginManager}
.
TWiki::Users::HtPasswdUser
for {PasswordManager}
.
configure
settings.
data/.htpasswd
file. If not, you probably got a path wrong, or the permissions may not allow the webserver user to write to that file.
Edit
link at beginning or end of topic) to check if authentication works.
LoginManager
option TWiki::LoginManager::ApacheLogin
uses a basic Apache type authentication where the browser itself prompts you for username and password. Most will find the TemplateLogin looking nicer. But ApacheLogin is required when you use Apache authentication methods like mod_ldap where all authentication is handled by an Apache module and not by the TWiki perl code. When you use ApacheLogin the apache configuration must be set up to require authentication of the some but not all the scripts in the bin directory. This section in the Apache config (or .htaccess) controls this
<FilesMatch "(attach|edit|manage|rename|save|upload|mail|logon|rest|.*auth).*"> require valid-user </FilesMatch>The TWiki:TWiki.ApacheConfigGenerator includes this section when you choose ApacheLogin. In the example
twiki_httpd_conf.txt
and bin/.htaccess.txt
files this section is commented out with #. Uncomment the section when you use ApacheLogin. It is important that this section is commented out or removed when you use TemplateLogin.
data/Main/TWikiPreferences.txt
file and all your settings will be kept. Settings in Main.TWikiPreferences overrides settings in both TWiki.TWikiPreferences and any settings defined in plugin topics. See notes at the top of TWiki.TWikiPreferences for more information.
tools/mailnotify
script as described in the MailerContrib topic.
{WebMasterEmail}
email account. Obtain these as you would for any other S/MIME e-mail user.
To enable TWiki to sign administrative e-mails: /etc/pki/tls/certs
configure
script, change the following settings under Mail and Proxies: {MailProgram}
to enable an external mail program such as sendmail. Net::SMTP is not supported.
{SmimeCertificateFile}
configuration variable
{SmimeKeyFile}
configuration variable
configure
script an resolve any errors that it identifies
configure
for {Sessions}{ExpireAfter}
(turn on expert mode to see it), and install a crjob to run the tools/tick_twiki.pl
script. Read The topic TWikiScripts#tick_twiki_pl for details how to do this.
Localisation
section of configure
. For more information about these features, see TWiki:TWiki.InternationalizationSupplement.
configure
. In this section you also find a Find More Extensions button which opens an application which can install additional plugins from the TWiki.org website. If you are behind a firewall or your server has no access to the Internet it is also possible to install plugins manually. Manual installation instructions for the plugins can be found in the plugin topics on TWiki.org. Additional documentation on TWiki plugins can be found at TWiki:TWiki.TWikiPluginsSupplement.
Some plugins require that you define their settings in configure
. You fill find these under the Extensions section of configure.
configure
script and make sure you have resolved all errors, and are satisfied that you understand any warnings.
If by any chance you forgot the "admin" password, the same is used in "configure" script, then please login to the server. Delete $TWiki::cfg{Password}= ' ...';
. Set the new password using "configure" script.
Failing that, please check TWiki:TWiki.InstallingTWiki on TWiki.org, the supplemental documentation that help you install TWiki on different platforms, environments and web hosting sites. For example: Resource | Required Server Environment * |
---|---|
Perl | 5.8.0 or higher (5.8.4 or higher is recommended) |
RCS | 5.7 or higher (including GNU diff ) Optional, TWiki includes a pure perl implementation of RCS that can be used instead (although it's slower) |
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 |
GNU df |
Used by the site statistics to record disk usage statistics, optional. The df command is pre-installed on Linux and OS-X. On Windows install the CoreUtils for Windows. |
GNU patch |
For upgrades only: GNU patch is required when using the TWiki:Codev.UpgradeTWiki script |
GNU fgrep , egrep |
Modify command line parameters in configure if you use non-GNU grep programs |
zip |
Zip archive command line utility. Used by the BackupRestorePlugin to create and restore from backups. |
Cron/scheduler | • Unix: cron • Windows: cron equivalents |
Web server | Apache is well supported; see TWiki:TWiki.InstallingTWiki#OtherWebServers for other servers |
Module | Preferred version | Comment |
---|---|---|
Algorithm::Diff |
Included in TWiki distribution | |
CGI |
>=3.18 | Versions 2.89 and 3.37 must be avoided. Most version from 3.15 and onwards should work. |
CGI::Carp |
>=1.26 | |
Config |
>=0 | |
Cwd |
>=3.05 | |
Data::Dumper |
>=2.121 | |
Encode |
>=2.1 | |
Error |
Included in TWiki distribution | |
File::Copy |
>=2.06 | |
File::Find |
>=1.05 | |
File::Spec |
>=3.05 | |
File::Temp |
>=0.18 | Included with perl 5.6 and later |
FileHandle |
>=2.01 | |
HTML::Parser |
>=3.28 | Needed by the WysiwygPlugin for WYSIWYG editing |
HTML::Entities |
>=1.25 | Needed by the WysiwygPlugin for WYSIWYG editing |
IO::File |
>=1.10 | |
Net::SMTP |
>=2.29 | Used for sending mail |
Text::Diff |
Included in TWiki distribution | |
Time::Local |
>=1.11 |
Module | Preferred version | Description |
---|---|---|
Archive::Tar |
May be required by the Extensions Installer in configure if command line tar or unzip is not available | |
Authen::SASL |
Used for SMTP Authentication | |
CGI::Cookie |
>=1.24 | Used for session support |
CGI::Session |
>=3.95 | Used for session support |
Crypt::SMIME |
>=0.09 | Required if S/MIME-signed administrative e-mail is enabled. |
Digest::base |
||
Digest::SHA1 |
||
Locale::Maketext::Lexicon |
>=0 | Used for I18N support |
Net::SMTP |
>=2.29 | Used for sending mail |
URI |
Used for configure |
configure
script, or if you're still trying to get to that point, check from the command line like this:
perl -e 'use FileHandle; print $FileHandle::VERSION."\n"'
pub
directory.)
twiki/bin
directory (e.g. because CGI bin directories can't be under your home directory and you don't have root access). You can create this directory elsewhere and configure the twiki/bin/setlib.cfg
file (done in Step 2). 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/locale | language files | dir secure from public access | /home/smith/twiki/locale |
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 |
twiki/tools | TWiki utlilities | dir secure from public access | /home/smith/twiki/tools |
twiki/working | Temporary and internal files | dir secure from public access | /home/smith/twiki/working |
755
(or 775
) and file permissions should be set to 644
(or 664
). If you can run a chmod
command, you can accomplish this in two quick steps by running these commands from the root direct: chmod -R 755 pub
chmod 644 `find pub -type f -print`
.htaccess
file in the pub directory, using the template included in the root level of the distribution entitled pub-htaccess.txt
.
.htaccess
in the bin directory that includes the following single line: SetHandler cgi-script
. This informs the server to treat all the perl scripts in the bin directory as scripts.
lib/TWiki.spec
to lib/LocalSite.cfg
$TWiki::cfg{DefaultUrlHost}
, $TWiki::cfg{ScriptUrlPath}
, $TWiki::cfg{PubUrlPath}
, $TWiki::cfg{PubDir}
, $TWiki::cfg{TemplateDir}
, $TWiki::cfg{DataDir}
, $TWiki::cfg{LocalesDir}
, and $TWiki::cfg{OS}
and make sure these settings have the correct values.
$TWiki::cfg{LoginManager}
, $TWiki::cfg{WebMasterEmail}
, $TWiki::cfg{SMTP}{MAILHOST}
, $TWiki::cfg{SMTP}{SENDERHOST}
.
twiki/lib/LocalSite.cfg
as a reference. This way you will not have old obsolete settings in the new LocalSite.cfg
.
LocalSite.cfg
file and re-run configure.
lib/TWiki.cfg
from the old TWiki installation is a good resource for some of the settings you will need but you cannot reuse the old TWiki.cfg.
DEFAULT_TYPE
setting of the CommentPlugin, create a COMMENTPLUGIN_DEFAULT_TYPE
setting in Main.TWikiPreferences.
twiki/data/Engineering
(for page content) and twiki/pub/Engineering
(for attachments).
find data -name '*,v' -exec rcs -u -M '{}' \;
find pub -name '*,v' -exec rcs -u -M '{}' \;
Main.TWikiUsers
topic to the new TWiki. If you upgrade from Cairo you can simply use the old file and add the missing new system users to the list of users. If you upgrade from TWiki-4.0.x simply use the old topic. Starting from 4.2.0 TWiki no longer ships with a Main.TWikiUsers
topic. When you register the first user TWiki now checks for an existing Main.TWikiUsers
and if it does not exist it gets created.
data/.htpasswd
for authentication copy this file from the old TWiki to the new. tools/upgrade_emails.pl
.
TWiki.TWikiRegistration
. Make sure you either reuse the registration topic from the old installation or apply the same field changes to the new TWiki.TWikiRegistration
topic.
NewUserTemplate
and UserForm
in the TWiki web. If you choose to tailor anything you are strongly advised to copy NewUserTemplate
and UserForm
to the Main web and tailor the Main web copies. TWiki will look for the NewUserTemplate
in the Main web first and if it does not exist it uses the default from the TWiki web. By creating a Main.NewUserTemplate
and its Main.UserForm
you will not loose your tailorings next time you upgrade TWiki.
Main.TWikiPreferences
. This avoids having to write over files in the distribution on a later upgrade.
data/TWiki
of the old and new TWiki installation, and transfer the changes into the new TWiki install. If you can run a GUI on your server, you may find that using a visual diff tool like WinMerge, meld, kdiff3, xxdiff, etc. is helpful.
WebPreferences
topics in the old TWiki Installation with the default from the new TWiki installation and add any new Preferences that may be relevant.
WebLeftBar
topics in the old TWiki Installation with the default from the new TWiki installation and add any new feature that you desire.
TWiki.ChangePassword
TWiki.ResetPassword
TWiki.ChangeEmailAddress
* Set FAVICON = %PUBURLPATH%/%SYSTEMWEB%/%WEBPREFSTOPIC%/favicon.ico
* TWikiContributor - 2005-01-01 * TWikiGuest - guest - 1999-02-10 * TWikiRegistrationAgent - 2005-01-01 * UnknownUser - 2005-01-01What these users are:
Set ALLOWTOPICCHANGE = TWikiAdminGroup, TWikiRegistrationAgent
access control setting. Otherwise people will not be able to register.
%TMPL:DEF{"block"}%
and %TMPL:END%
was stripped of leading and trailing white space incl new lines.
This caused a lot of problems for skin developers when you wanted a newline before or after the block text.
From TWiki 4.1.0 this has changed so that white space is no longer stripped. Skins like PatternSkin and NatSkin have been updated so that they work with the new behavior. But if you use an older skin or have written your own you will most likely need to make some adjustments.
It is not difficult. The general rule is - if you get mysterious blank lines in your skin, the newline after the %TMPL:DEF{"block"}%
needs to be removed. Ie. the content of the block must follow on the same line as the TMPL:DEF.
The spec change have the same impact on CommentPlugin templates where you may have to remove the first line break after the TMPL:DEF. See the CommentPluginTemplate for examples of how comment template definitions should look like in TWiki-4.1.X
An example: A CommentPlugin template that adds a comment as appending a row to a table. Before the spec change this would work.
<verbatim> %TMPL:DEF{OUTPUT:tabletest}%%POS:BEFORE% |%URLPARAM{"comment"}%| -- %WIKIUSERNAME% - %DATE% | %TMPL:END% </verbatim>From Twiki 4.1.0 the old template definition will add an empty line before the new table row. To fix it simply remove the new line before the table.
<verbatim> %TMPL:DEF{OUTPUT:tabletest}%%POS:BEFORE%|%URLPARAM{"comment"}%| -- %WIKIUSERNAME% - %DATE% | %TMPL:END% </verbatim>The advantage of the spec change is that now you can add leading and trailing white space including new lines. This was not possible before.
{PassthroughDir}
and {Sessions}{Dir}
were by default set to /tmp
. These config settings have been replaced by {TempfileDir}
with the default setting value /tmp/twiki
. If the twiki
directory does not exist twiki will create it first time it needs it.
It is highly recommended no longer to use the tmp directory common to other web applications and the new default will work fine for most. You may want to delete all the old session files in /tmp after the upgrade to 4.1.1. They all start with cgisess_. It is additionally highly recommended to limit write access to the {TempfileDir}
for security reasons if you have non-admin users with login access to the webserver just like you would do with the other webserver directories.
NewUserTemplate
and UserForm
.
The NewUserTemplate
was located in the TWiki web and the UserForm
in the Main web. When upgrading TWiki these were some of the topics you had to take care not to overwrite.
From 4.2.0 the UserForm
and NewUserTemplate
are distributed in the TWiki web. If you create the two in the Main web the Main web version will be used instead. So if you tailor the user topic format or the form then you should always copy the two files to the Main web and modify the ones in the Main web. When you later upgrade TWiki your tailored template and form will not be overwritten.
Main.TWikiUsers
topic contains all the registered users. It is a topic you do not want to overwrite when you upgrade TWiki.
From 4.2.0 this file is no longer included in the TWiki distribution. When you register the first time TWiki creates the Main.TWikiUsers
topic in the Main web if it does not exist already. This means that you can now upgrade TWiki without risk of overwriting the important TWikiUsers
topic.
working
directory working
which per default is located in the twiki root, has been introduced which contains:
{WorkingDir}
defines the container directory for temporary files, extensions' work areas, and intermediate registration data. The default is working
under your installation root.
Take care for that change if you run your own routine to delete obsolete session files, which will now be found under working/tmp/cgisess*
.
FirstName
to First Name
(no change in %META:FIELD name
)
LastName
to Last Name
(no change in %META:FIELD name
)
OrganisationName
to Organization
OrganisationURL
to URL
Profession
to Titles
VoIP
to Skype ID
State
to Region
Address
InstantMessaging (IM)
HomePage
Comment
Department
Status Update
.htpasswd
files on the server. These files can be unique to TWiki, or can be shared with other applications (such as an Apache webserver). A variety of password encodings are supported for flexibility when re-using existing files. See the descriptive comments in the Security Settings section of the configure interface for more details.
You can easily plug in alternate password management modules to support interfaces to other third-party authentication databases.
Main/WebPreferences
. By doing so, new users are able to register without any errors.
none
in configure) TWiki::LoginManager::TemplateLogin
login manager (on the Security Settings pane).
{TemplateLogin}{PreventBrowserRememberingPassword}
that you can set to prevent Browsers from remembering username and passwords if you are concerned about public terminal usage.
.htpasswd
files, check that a new line with the username and encrypted password is added to the .htpasswd
file. If not, you probably got a path wrong, or the permissions may not allow the webserver user to write to that file.
pub
area, unless they are only accessed through the viewfile
script. If your pub
directory is set up in the webserver to allow open access you may want to add .htaccess
files in there to restrict access.
You can create a custom version of the TWikiRegistration form by copying the topic, and then deleting or adding input tags in your copy. 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 profile page correctly. Do not modify the version of TWikiRegistration shipped with TWiki, as your changes will be overwritten next time you upgrade.
The default new user template page is in TWiki.NewUserTemplate. The same variables get expanded as in the template topics. You can create a custom new user profile page by creating the Main.NewUserTemplate topic, which will then override the default.
REMOTE_USER
environment variable, which is set when you enable authentication in the webserver.
The advantage of this scheme is that if you have an existing website authentication scheme using Apache modules such as mod_auth_ldap
or mod_auth_mysql
you can just plug in directly to them.
The disadvantage is that because the user identity is cached in the browser, you can log in, but you can't log out again unless you restart the browser.
TWiki maps the REMOTE_USER
that was used to log in to the webserver to a WikiName using the table in TWikiUsers. This table is updated whenever a user registers, so users can choose not to register (in which case their webserver login name is used for their signature) or register (in which case that login name is mapped to their WikiName).
The same private .htpasswd
file used in TWiki Template Login can be used to authenticate Apache users, using the Apache Basic Authentication support.
Warning: Do not use the Apache htpasswd
program with .htpasswd
files generated by TWiki! htpasswd
wipes out email addresses that TWiki plants in the info fields of this file.
TWiki::LoginManager::ApacheLogin
login manager.
.htpasswd
entries.
.htaccess
file in the twiki/bin
directory.twiki/bin/.htaccess.txt
that you can copy and change. The comments in the file explain what need to be done..htaccess
does not have the desired effect, you may need to "AllowOverride All" for the directory in httpd.conf
(if you have root access; otherwise, e-mail web server support) pub
area, unless they are only accessed through the viewfile
script. If your pub
directory is set up to allow open access you may want to add .htaccess
files in there as well to restrict access
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 profile page correctly. Do not modify the version of TWikiRegistration shipped with TWiki, as your changes will be overwritten next time you upgrade. .htpasswd
file. If not, you may have got a path wrong, or the permissions may not allow the webserver user to write to that file.
bin/logon
script enables this. If you are using Apache Login, the bin/logon
script must be setup in the bin/.htaccess
file to be a script which requires a valid user
. Once authenticated, it will redirect the user to the view URL for the page from which the logon
script was linked.
%SESSION_VARIABLE{ "varName" }% |
Read a session variable |
%SESSION_VARIABLE{ "varName" set="varValue" }% |
Set a session variable |
%SESSION_VARIABLE{ "varName" clear="" }% |
Clear a session variable |
%SESSION_VARIABLE{"AUTHUSER"}%
- user ID, current value:
%SESSION_VARIABLE{"SESSION_REQUEST_NUMBER"}%
- number of pages accessed by current user since login, current value:
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.
PeterThoeny
, is recorded when you register using TWikiRegistration; doing so also generates a user profile page in the Main web.
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, for exampleMain.WikiUsername
or%USERSWEB%.WikiUsername
. This pointsWikiUsername
to the Main web, where user profile pages are located, no matter which web it's entered in. Without the web prefix, the name appears as a NewTopic everywhere but in the Main web.
TWiki/ChangePassword
)
TWiki/ResetPassword
)
TWiki/ChangeEmailAddress
)
.htaccess
Web | Sitemap | VIEW | CHANGE | RENAME | |||
---|---|---|---|---|---|---|---|
Listed | DENY | ALLOW | DENY | ALLOW | DENY | ALLOW | |
Main | on | ||||||
TWiki | on | TWikiAdminGroup | TWikiAdminGroup | ||||
IVOA | on | GuestUserGroup | GuestUserGroup | TWikiAdminGroup | |||
IVOA.PDL1RFC | on | GuestUserGroup | GuestUserGroup | TWikiAdminGroup | |||
IVOA.PhotDM1 | on | GuestUserGroup | GuestUserGroup | TWikiAdminGroup | |||
IVOA.Spectral2 | on | GuestUserGroup | GuestUserGroup | TWikiAdminGroup | |||
IVOA.SpectralDM2 | on | GuestUserGroup | GuestUserGroup | TWikiAdminGroup | |||
Know | on | GuestUserGroup | GuestUserGroup | TWikiAdminGroup | |||
Sandbox | on |
Main
web. To create a new group, visit TWikiGroups and enter the name of the new group ending in Group
into the "new group" form field. This will create a new group topic with two important settings: Set GROUP = < list of Users and/or Groups >
Set ALLOWTOPICCHANGE = < list of Users and/or Groups >
Set GROUP = SomeUser, OtherUser, SomeGroup
Set ALLOWTOPICCHANGE = MarketingGroup
TWikiAdminGroup
. The system administrator may have chosen a different name for this group if your local TWiki uses an alternate group mapping manager but for simplicity we will use the default name TWikiAdminGroup in the rest of this topic.
You can create new administrators simply by adding them to the TWikiAdminGroup topic. For example, Set GROUP = RobertCailliau, TimBernersLee
Set DENYWEBVIEW = < comma-delimited list of Users and Groups >
Set ALLOWWEBVIEW = < comma-delimited list of Users and Groups >
Set DENYWEBCHANGE = < comma-delimited list of Users and Groups >
Set ALLOWWEBCHANGE = < comma-delimited list of Users and Groups >
Set DENYWEBRENAME = < comma-delimited list of Users and Groups >
Set ALLOWWEBRENAME = < comma-delimited list of Users and Groups >
Set ALLOWWEBVIEW = Main.MarketingGroup
ALLOWWEBVIEW
set, this will also apply to the subweb. Also note that you will need to ensure that the parent web's FINALPREFERENCES
does not include the access control settings listed above. Otherwise you will not be able override the parent web's access control settings in sub-webs.
Creation and renaming of sub-webs is controlled by the WEBCHANGE setting on the parent web (or ROOTCHANGE for root webs). Renaming is additionally restricted by the setting of WEBRENAME in the web itself.
Note: If you restrict access to the Main, make sure to add the TWikiRegistrationAgent
so that users can register. Example: Set ALLOWWEBCHANGE = TWikiAdminGroup, TWikiRegistrationAgent
Set DENYTOPICVIEW = < comma-delimited list of Users and Groups >
Set ALLOWTOPICVIEW = < comma-delimited list of Users and Groups >
Set DENYTOPICCHANGE = < comma-delimited list of Users and Groups >
Set ALLOWTOPICCHANGE = < comma-delimited list of Users and Groups >
Set DENYTOPICRENAME = < comma-delimited list of Users and Groups >
Set ALLOWTOPICRENAME = < comma-delimited list of Users and Groups >
Set ALLOWTOPICVIEW = Main.MarketingExecGroup
Set ALLOWTOPICVIEW =
Set DENYTOPICVIEW =
mod_rewrite
module to redirect accesses to attachments via the TWiki viewfile
script, which honors the TWiki access controls settings to topics.
The preferred method to secure attachments is by editing the twiki.conf
file to include:
ScriptAlias /twiki/bin/ /filesystem/path/to/twiki/bin/ Alias /twiki/pub/ /filesystem/path/to/twiki/pub/ RewriteEngine on RewriteCond %{REQUEST_URI} !^/+twiki/+pub/+(TWiki|Sandbox)/+.+ RewriteRule ^/+twiki/+pub/+(.*)$ /twiki/bin/viewfile/$1 [L,PT]Notes:
viewfile
script. The TWiki web and Sandbox web are excluded for performance reasons.
twiki.conf
file used by Apache, you can make the same change directly to the .htaccess
file in the /twiki/bin
directory.
viewfile
script sets the mime type based upon file name suffix. Unknown types are served as text/plain which can result in corrupt files.
Set DENYROOTCHANGE = < comma-delimited list of Users and Groups >
Set ALLOWROOTCHANGE = < comma-delimited list of Users and Groups >
ROOTCHANGE
access to rename an existing top-level web. You just need WEBCHANGE
in the web itself.
twiki/bin
and twiki/pub
directories to all but valid users. In the Apache .htaccess
file or the appropriate .conf
file, replace the <FilesMatch "(attach|edit|...
section with this:
<FilesMatch ".*"> require valid-user </FilesMatch>If needed, you can further restrict access to selected webs with ALLOWWEBVIEW and other access control settings. Note: With this configuration, someone with access to the site needs to register new users.
require valid-user
on your view
script in .htaccess or the appropriate Apache .conf file. As of 4.x, this looks like: FilesMatch "(attach|edit|manage|rename|save|view|upload|mail|logon|.*auth).*"
(normally view
is not in that list).
Set DENYWEBVIEW = < list of Users and Groups >
Set ALLOWWEBVIEW = < list of Users and Groups >
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 if DENYWEBVIEW
and ALLOWWEBVIEW
are not defined.
Set DENYWEBVIEW = < list of Users and Groups >
Set ALLOWWEBVIEW = < list of Users and Groups >
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 if DENYWEBVIEW
and ALLOWWEBVIEW
are not defined.
Edit topic preference settings
under More topic actions
menu. Preferences set in this manner are not visible in the topic text, but take effect nevertheless. Access control settings added as topic preference settings are stored in the topic meta data and they override settings defined in the topic text.
Alternatively, place them in HTML comment markers, but this exposes the access setting during ordinary editing.
<!--
* Set DENYTOPICCHANGE = Main.SomeGroup
-->
all webs
search option from accessing obfuscated webs. Do so by enabling the NOSEARCHALL
variable in WebPreferences: Set NOSEARCHALL = on
Formatting Command: | You write: | You get: | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Paragraphs: Blank lines will create new paragraphs. |
1st paragraph 2nd paragraph | 1st paragraph 2nd paragraph | |||||||||||||||||||||||||
Headings: Three or more dashes at the beginning of a line, followed by plus signs and the heading text. One plus creates a top level heading, two pluses a second level heading, etc. The maximum heading depth is 6. You can create a table of contents with the %TOC% variable. If you want to exclude a heading from the TOC, put !! after the ---+ .
Empty headings are allowed and won't appear in the table of contents. |
---++ Sushi ---+++ Maguro ---+++!! Not in TOC |
SushiMaguroNot in TOC |
|||||||||||||||||||||||||
Bold Text: Words get shown in bold by enclosing them in * asterisks.
|
*Bold* | Bold | |||||||||||||||||||||||||
Italic Text: Words get shown in italic by enclosing them in _ underscores.
|
_Italic_ | Italic | |||||||||||||||||||||||||
Bold Italic: Words get shown in 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
|
|||||||||||||||||||||||||
You can follow the closing bold, italic, or other (* _ __ = == ) indicator
with normal punctuation, such as commas and full stops.
Make sure there is no space between the text and the indicators. All words enclosed by the indicators need to be on the same line. |
_This works_, _this does not _ _this fails too_ |
This works, _this does not _ _this fails too_ |
|||||||||||||||||||||||||
Separator (Horizontal Rule): Three or more three dashes at the beginning of a line.. |
------- |
|
|||||||||||||||||||||||||
Bulleted List: Multiple of three spaces, an asterisk, and another space. For all the list types, you can break a list item over several lines by indenting lines after the first one by at least 3 spaces. |
* level 1 * level 2 * back on 1 * A bullet broken over three lines * last bullet |
|
|||||||||||||||||||||||||
Numbered List: Multiple of three spaces, a type character, a dot, and another space. Several types are available besides a number:
|
1. Sushi 1. Dim Sum 1. Fondue A. Sushi A. Dim Sum A. Fondue i. Sushi i. Dim Sum i. Fondue |
|
|||||||||||||||||||||||||
Definition List: Three spaces, a dollar sign, the term, a colon, a space, followed by the definition. Deprecated syntax: Three spaces, the term with no spaces, a colon, a space, followed by the definition. |
$ Sushi: Japan $ Dim Sum: S.F. |
|
|||||||||||||||||||||||||
Table: Each row of the table is a line containing of one or more cells. Each cell starts and ends with a vertical bar '|'. Any spaces at the beginning of a line are ignored.
|^| multiple-span row functionality and additional rendering features
|
| *L* | *C* | *R* | | A2 | B2 | C2 | | A3 | B3 | C3 | | multi span ||| | A5-7 | 5 | 5 | |^| six | six | |^| seven | seven | | split\ | over\ | 3 lines | | A9 | B9 | C9 | |
|
|||||||||||||||||||||||||
WikiWord Links: CapitalizedWordsStuckTogether (or WikiWords) will produce a link automatically if preceded by whitespace or parenthesis. If you want to link to a topic in a different web write Otherweb.TopicName . To link to a topic in a subweb write Otherweb.Subweb.TopicName .The link label excludes the name of the web, e.g. only the topic name is shown. As an exception, the name of the web is shown for the WebHome topic. Dots '.' are used to separate webs and subwebs from topic names and therefore cannot be used in topic names.
It's generally a good idea to use the TWikiVariables %SYSTEMWEB% and %USERSWEB% instead of TWiki and Main.
|
WebStatistics Sandbox.WebNotify Sandbox.WebHome Sandbox.Subweb.TopicName | WebStatistics WebNotify Sandbox TopicName | |||||||||||||||||||||||||
Anchors: You can define a reference inside a TWiki topic (called an anchor name) and link to that. To define an anchor write #AnchorName at the beginning of a line. The anchor name must be a WikiWord of no more than 32 characters. 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 | |||||||||||||||||||||||||
Forced Links: Use double square brackets to create forced links: Write [[link]] or [[link][label]] to force a link. Use the former for singleton words and if automatic linking is disabled. Use the latter one to specify a link label other than the link. For the link, you can use internal link references (e.g. WikiWords) and URLs (e.g. http://TWiki.org/).
Anchor names can be added to create a link to a specific place in a document. To "escape" double square brackets that would otherwise make a link, prefix the leading left square bracket with an exclamation point. |
[[WikiWord]] [[WikiWord#TheSyntax]] [[WikiSyntax][wiki syntax]] [[http://gnu.org/][GNU]] [[Singleton]] escaped: ![[WikiSyntax]] | WikiWord WikiWord#TheSyntax wiki syntax GNU Singleton escaped: [[WikiSyntax]] | |||||||||||||||||||||||||
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.It is possible to turn off all auto-linking with a NOAUTOLINK preferences setting. |
<noautolink> RedHat & SuSE </noautolink> | RedHat & SuSE | |||||||||||||||||||||||||
Mailto Links: E-mail addresses are linked automatically. To create e-mail links that have more descriptive link text, specify subject lines or message bodies, or omit the e-mail address, you can write [[mailto:user@domain][descriptive text]] .
|
a@b.com [[mailto:a@b.com]\ [Mail]] [[mailto:?subject=\ Hi][Hi]] | a@b.com Mail Hi | |||||||||||||||||||||||||
Verbatim Text: Surround code excerpts and other formatted text with <verbatim> and </verbatim> tags.verbatim tags disable HTML code. Use <pre> and </pre> tags instead if you want the HTML code within the tags to be interpreted.NOTE: Preferences variables (* Set NAME = value) are set within verbatim tags. |
<verbatim> class CatAnimal { void purr() { <code here> } } </verbatim> |
class CatAnimal { void purr() { <code here> } } |
|||||||||||||||||||||||||
Literal Text: TWiki generates HTML code from TWiki shorthand. Experts surround anything that must be output literally in the HTML code, without the application of TWiki shorthand rules, with <literal>..</literal> tags. any HTML
within literal tags must be well formed i.e. all tags must be properly closed before
the end of the literal block. TWiki Variables are expanded within literal blocks.
|
<literal> | Not | A | Table | <literal> |
| Not | A | Table | | |||||||||||||||||||||||||
Protected Text: Experts protect text from mangling by WYSIWYG editors using <sticky>..</sticky> tags. Sticky tags don't have any effect on normal
topic display; they are only relevant when content has to be
protected from a WYSIWYG editor (usually because it isn't well-formed HTML, or because it
is HTML that WYSIWYG would normally filter out or modify). Protected
content appears as plain text in the WYSIWYG editor.
|
<sticky> <div> This div is required </div> </sticky> |
This div is required
|
<strike>deleted text</strike>
to get <literal>..</literal>
tags around blocks of HTML to avoid accidental interpretation of TWiki shorthand within the HTML.
<body>
and </body>
tags.
<p />
paragraph tags on empty lines, which causes problems if done between HTML tags that do not allow paragraph tags, like for example between table tags.
<...>
- of a HTML tag are on the same line, or the tag will be broken.
JavaScript Example: | CSS Example: |
---|---|
<!-- <pre> --> <script language="javascript"> <!-- // put your JavaScript code here //--> </script> <!-- </pre> --> |
<!-- <pre> --> <style type="text/css"> /* put your CSS code here */ </style> <!-- </pre> --> |
http://...
, https://...
, ftp://...
, gopher://...
, news://...
, file://...
, telnet://...
and mailto:...@...
are linked automatically.
[[URL][label]]
to get an external link with a descriptive text for the link, such as [[http://google.com/][Google home page]]
to get Google home page.
name@domain.com
are linked automatically.
%TOPIC%
is expanded to TWikiVariablesQuickStart. Some variables can take arguments in curly braces - for example, %INCLUDE{"OtherTopic" ARG="arg"}%
.
Many TWiki variables are built-in, and others are predefined for your convenience. TWikiVariables describes how you can also define your own TWiki Variables at the entire site, individual web, or individual topic level. Variables are fully expanded before any of the TWiki text formatting rules are applied.
Commonly used variables:
%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 TWikiVariablesQuickStart.
%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 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.
%ICON{"help"}%
, %ICON{"tip"}%
, and %ICON{"warning"}%
to get: , , and , respectively.
!%SOMEVARIABLE%
to get: %SOMEVARIABLE%.
%PLUGINDESCRIPTIONS%
:
"$SUM( $ABOVE() )"
to TWiki tables or anywhere in topic text ExternalSite:Page
to link to a page on an external site based on aliases defined in a rules topic :-)
for or :eek:
for <filename>
is not displayed. How can I show it as it is? '<'
and '>'
characters have a special meaning in HTML, they define HTML tags. You need to escape them, so write '<'
instead of '<'
, and '>'
instead of '>'
. 'prog <filename>'
to get 'prog <filename>'
.
'&'
character sometimes not displayed? '&'
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 '&'
. 'This & that'
to get 'This & that'
.
%VARIABLE%
or %VARIABLE{ parameter="value" }%
- that expand into content whenever a topic is rendered for viewing. There are two types of variables:
%CALC{}%
variable)
%T%
to get (a preferences variable)
%TOPIC%
to get TWikiVariables
(a predefined variable)
%CALC{ "$UPPER(Text)" }%
to get TEXT
(a variable defined by a plugin)
!%TOPIC%
to get %TOPIC%
%ALLVARIABLES%
to get a full listing of all variables defined for a particular topic
%MYVAR%
, %MyVar%
, %My2ndVar%
, and %My_Var%
are all valid variable names. Variables are case sensitive. %MyVAR%
and %MYVAR%
are not the same variable.
By convention all settings, predefined variables and variables used by plugins are always UPPER-CASE.
preview
will show the wrong thing, and you must save
the topic to see it correctly.
The syntax for setting variables is the same anywhere in TWiki (on its own TWiki bullet line, including nested bullets): [multiple of 3 spaces] * [space] Set [space] VARIABLENAME [space] = [space] value
Examples:
* Set VARIABLENAME1 = value * Set VARIABLENAME2 = valueSpaces between the = sign and the value will be ignored. You can split a value over several lines by indenting following lines with spaces - as long as you don't try to use * as the first character on the following line. Example:
* Set VARIABLENAME = value starts here and continues hereWhatever you include in your variable will be expanded on display, exactly as if it had been entered directly. Example: Create a custom logo variable
%MYLOGO%
, define the Variable on the web's WebPreferences topic, 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, e.g. LogoTopic
. Sample variable setting in WebPreferences:
* Set MYLOGO = %PUBURL%/%WEB%/LogoTopic/mylogo.gifYou can also set preferences variables on a topic by clicking the link
Edit topic preference settings
under More topic actions
. Use the same * Set VARIABLENAME = value
syntax. Preferences set in this manner are not visible in the topic text, but take effect nevertheless.
* Set EXAMPLE = Example variable using %DEFAULT%, %PARAM1% and %PARAM2% * Set DEMO = Demo using %DEFAULT{ default="(undefined)" }%, %PARAM1{ default="(undefined)" }% and %PARAM2{ default="(undefined)" }%A special
%DEFAULT%
variable denotes the default (nameless) parameter of the calling variable. Variables optionally may list a default="..."
parameter that gets used in case the calling variable does not specify that parameter.
To use a parameterized variable (or call a macro), add parameters within the curly brackets, such as:
* %EXAMPLE{ "foo" PARAM1="bar" PARAM2="baz" }% * %DEMO{ "demo" PARAM2="parameter 2" }% -- note that PARAM1 is missingwhich resolves to:
%PARAM1%
gets expanded to bar
.
* Set DRINK = red wine * Set FAVORITE = My %DEFAULT{default="favorite"}% dish is %DISH{default="steak"}%, my %DEFAULT{default="favorite"}% drink is %DRINK%.The default can be defined with a default parameter (
%DISH{default="steak"}%
), or as a preferences setting (Set DRINK = ...
).
Use Variables:
%FAVORITE{ DISH="Sushi" DRINK="Sake" }%Returns:
%FAVORITE{}%Returns:
%FAVORITE{ "preferred" }%Returns:
Local
in place of Set
in the variable definition. For example, if the user sets the following in their home topic:
* Set EDITBOXHEIGHT = 10 * Local EDITBOXHEIGHT = 20Then when they are editing any other topic, they will get a 10 high edit box. However when they are editing their home topic, they will get a 20 high edit box.
Local
can be used wherever a preference needs to take a different value depending on where the current operation is being performed.
Use this powerful feature with great care! %ALLVARIABLES%
can be used to get a listing of the values of all variables in their evaluation order, so you can see variable scope if you get confused.
%BB%
- line break and bullet combined
%BB2%
- level 2 bullet with line break
%BB3%
- level 3 bullet with line break
%BB4%
- level 4 bullet with line break
%BR%
- line break
%BULLET%
- bullet sign
%CARET%
- caret symbol
%VBAR%
- vertical bar
%H%
- Help icon
%I%
- Idea icon
%M%
- Moved to icon
%N%
- New icon
%P%
- Refactor icon
%Q%
- Question icon
%S%
- Pick icon
%T%
- Tip icon
%U%
- Updated icon
%X%
- Alert icon
%Y%
- Done icon
%RED% text %ENDCOLOR%
- colored text (also %YELLOW%
, %ORANGE%
, %PINK%
, %PURPLE%
, %TEAL%
, %NAVY%
, %BLUE%
, %AQUA%
, %LIME%
, %GREEN%
, %OLIVE%
, %MAROON%
, %BROWN%
, %BLACK%
, %GRAY%
, %SILVER%
, %WHITE%
)
%REDBG% text %ENDBG%
- colored background (also %YELLOWBG%
, %ORANGEBG%
, %PINKBG%
, %PURPLEBG%
, %TEALBG%
, %NAVYBG%
, %BLUEBG%
, %AQUABG%
, %LIMEBG%
, %GREENBG%
, %OLIVEBG%
, %MAROONBG%
, %BROWNBG%
, %BLACKBG%
, %GRAYBG%
, %SILVERBG%
, %WHITEBG%
)
%SEARCH%
, are powerful and general tools.
%INCLUDINGTOPIC%
, %INCLUDE%
, and the mighty %SEARCH%
.
%ACTIVATEDPLUGINS%
%ADDTOHEAD{}%
expands in-place to an empty string, unless there is an error in which case the variable expands to an error string.
%ADDTOHEAD{ "..." text="..." }%
Parameter: | Description: | Comment: |
---|---|---|
"..." | ID of the head block, such as "MY_CSS" | Optional but recommended |
text="..." | HTML text to add to the head section | Mutually exclusive with topic="" |
topic="Web.TopicName" | Name of topic that contains the full HTML text to add to the head section, such as topic="Main.MyCssTopic" | Mutually exclusive with text="" |
requires="..., ..." | Comma-separated list of other IDs this one depends on | Optional |
%ADDTOHEAD{ "MYBOX_CSS" text="<style type=\"text/css\"> .myBox { height: 22px; background-color: #AFB3C5; } </style>" }%
%ALLVARIABLES%
AQUA
is one of the rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of colors.
%AQUA% aqua text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%ATTACHURL%
https://wiki.ivoa.net/internal/TWiki/VarATTACHURL
%ATTACHURL%/image.gif
%ATTACHURLPATH%
/internal/TWiki/VarATTACHURLPATH
%AUTHREALM%
%TOPIC%
if there is no INCLUDE
%BASETOPIC%
%WEB%
in case there is no include.
%BASEWEB%
%BASEWEB{format="..."}%
-- see WEB for format documentation
%BB%
%BB2%
%BB3%
%BB4%
BLACK
is one of the rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of colors.
%BLACK% black text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
BLUE
is one of the rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of colors.
%BLUE% blue text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%BR%
BROWN
is one of the rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of colors.
%BROWN% brown text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
| %BULLET% One %BB% Two %BB% Three |
%BULLET%
%CALC{"formula"}%
variable is handled by the SpreadSheetPlugin. There are around 80 formulae, such as $ABS()
, $EXACT()
, $EXISTS()
, $GET()/$SET()
, $IF()
, $LOG()
, $LOWER()
, $PERCENTILE()
, $TIME()
, $VALUE()
.
%CALC{"formula"}%
%CALC{"$SUM($ABOVE())"}%
returns the sum of all cells above the current cell
%CALC{"$EXISTS(Web.SomeTopic)"}%
returns 1
if the topic exists
%CALC{"$UPPER(Collaboration)"}%
returns COLLABORATION
%CARET%
%COMMENT%
without parameters shows a simple text box.
%COMMENT{}%
can handle the following parameters: Parameter | Description | Default |
---|---|---|
type | This is the name of the template to use for this comment. Comment templates are defined in a TWiki template - see customization. If this attribute is not defined, the type is whatever is defined by COMMENTPLUGIN_DEFAULT_TYPE, either in this topic or in your WebPreferences. | "below" |
default | Default text to put into the textarea of the prompt. | |
target | Name of the topic to add the comment to | the current topic |
location | Regular expression specifying the comment location in the target topic. Read carefully the CommentPlugin documentation! | |
mode | For compatibility with older versions only, synonymous with type | |
nonotify | Set to "on" to disable change notification for target topics | "off" |
noform | Set to "on" to disable the automatic form that encloses your comment block - remember to insert <form> tags yourself! See CommentPluginExamples#noform for an example. | "off" |
nopost | Set to "on" to disable insertion of the posted text into the topic. | "off" |
remove | Set to "on" to remove the comment prompt after the first time it is clicked. | "off" |
button | Button label text | "Add comment" |
%DATE%
2024-10-04
$year-$mo-$day
%DISPLAYTIME%
2024-10-04 - 18:52
$year-$mo-$day
. The time is shown as hh:mm (24 hour clock)
$year-$mo-$day
. Same format qualifiers as %GMTIME%
%DISPLAYTIME{"format"}%
$seconds
, $minutes
, $hours
, $day
, $wday
, $dow
, $month
, $mo
, $year
, $ye
, $tz
, $iso
, $rcs
, $http
, $epoch
%DISPLAYTIME{"$hou:$min"}%
expands to 18:52
text
, then hide the form. If EDITACTION is defined as form
hide the normal text area and only edit the form.
;action=text
or ;action=form
to the URL for the edit script. If you have defined EDITACTION in a topic setting or preference setting you can still edit the topic content or the form by removing the ;action=form
or ;action=text
from the edit URL in the browser and reload.
%EDITTABLE{}%
variable is handled by the EditTablePlugin
%EDITTABLE{ attributes }%
Attribute | Comment | Default |
---|---|---|
header | Specify the header format of a new table like "|*Food*|*Drink*|" . Useful to start a table with only a button | (no header) |
format | The format of one column when editing the table. A cell can be a text input field, or any of these edit field types: • Text input field (1 line): | text, <size>, <initial value> | • Textarea input field: | textarea, <rows>x<columns>, <initial value> | • Drop down box: | select, <size>, <option 1>, <option 2>, etc* | * only one item can be selected • Radio buttons: | radio, <size*>, <option 1>, <option 2>, etc | * size indicates the number of buttons per line in edit mode • Checkboxes: | checkbox, <size*>, <option 1>, <option 2>, etc | * size indicates the number of checkboxes per line in edit mode • Fixed label: | label, 0, <label text> | • Row number: | row, <offset> | • Date: | date, <size>, <initial value>, <DHTML date format*> | * see Date Field Type | "text, 16" for all cells |
changerows | Rows can be added and removed if "on" Rows can be added but not removed if "add" Rows cannot be added or removed if "off" | CHANGEROWS plugin setting |
quietsave | Quiet Save button is shown if "on" , hidden if "off" | QUIETSAVE plugin setting |
include | Other topic defining the EDITTABLE parameters. The first %EDITTABLE% in the topic is used. This is useful if you have many topics with the same table format and you want to update the format in one place. | (none) |
helptopic | Topic name containing help text shown below the table when editing a table. The %STARTINCLUDE% and %STOPINCLUDE% variables can be used in the topic to specify what is shown. | (no help text) |
headerislabel | Table header cells are read-only (labels) if "on" ; header cells can be edited if "off" or "0" | "on" |
editbutton | Set edit button text, e.g. "Edit this table" ; set button image with alt text, e.g. "Edit table, %PUBURL%/%SYSTEMWEB%/TWikiDocGraphics/edittopic.gif" ; hide edit button at the end of the table with "hide" (Note: Button is automatically hidden if an edit button is present in a cell) | EDITBUTTON plugin setting |
buttonrow | Set to top to put the edit buttons above the table. | bottom |
javascriptinterface | Use javascript to directly move and delete row without page refresh. Enable with "on" , disable with "off" . | JAVASCRIPTINTERFACE plugin setting |
%EDITTABLE{ format="| text, 20 | select, 1, one, two, three |" changerows="on" }%
| *Name* | *Type* |
| Foo | two |
"\n"
) and linefeed ("\r"
)
"<"
, ">"
, "&"
, single quote ('
) and double quote ("
)
"%"
, "["
, "]"
, "@"
, "_"
, "*"
, "="
and "|"
%ENCODE{"string"}%
Parameter: | Description: | Default: |
---|---|---|
"string" | String to encode | required (can be empty) |
type="url" | Encode special characters for URL parameter use, like a double quote into %22 | (this is the default) |
type="quotes" | Escape double quotes with backslashes (\" ), does not change other characters. This type does not protect against cross-site scripting. | type="url" |
type="moderate" | Encode special characters into HTML entities for moderate cross-site scripting protection: "<" , ">" , single quote (' ) and double quote (" ) are encoded. Useful to allow TWiki variables in comment boxes. | type="url" |
type="safe" | Encode special characters into HTML entities for cross-site scripting protection: "<" , ">" , "%" , single quote (' ) and double quote (" ) are encoded. | type="url" |
type="entity" | Encode special characters into HTML entities, like a double quote into " . Does not encode newline (\n ) or linefeed (\r ). | type="url" |
type="html" | Encode special characters into HTML entities. In addition to type="entity" , it also encodes space, \n and \r . Useful to encode text properly in HTML input fields. | type="url" |
%ENCODE{"spaced name"}%
expands to spaced%20name
"html"
.<input type="text" name="address" value="%ENCODE{ "any text" type="html" }%" />
%SEARCH{ "%ENCODE{ "string with "quotes"" type="quotes" }%" noheader="on" }%
type="moderate"
, type="safe"
or type="entity"
to protect user input from URL parameters and external sources against cross-site scripting (XSS). type="entity"
is the safest mode, but some TWiki applications might not work. type="safe"
provides a safe middle ground, type="moderate"
provides only moderate cross-site scripting protection.
ENDBG
is a rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of background colors.
%REDBG% red background %ENDBG%
%<color>BG%
section must end with %ENDBG%
. If you want to switch from one background color to another one you first need to end the active background color with %ENDBG%
, such as %REDBG% some text %ENDBG% %GREENBG% more text %ENDBG%
.
ENDCOLOR
is a rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of colors.
%RED% red text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%ENDSECTION{"name"}%
%ENDSECTION{type="include"}%
%ENDSECTION{type="templateonly"}%
%ENDSECTION{type="expandvariables"}%
Parameter: | Description: |
---|---|
"name" | Name of the section. |
type="..." | Type of the section being terminated; supported types "section" , "include" , "templateonly" , "expandvariables" |
STARTSECTION
is named, the corresponding ENDSECTION
must also be named with the same name. If the STARTSECTION
specifies a type, then the corresponding ENDSECTION
must also specify the same type. If the section is unnamed, ENDSECTION
will match with the nearest unnamed %STARTSECTION%
of the same type above it.
{AccessibleENV}
in the Security Settings/Miscellaneous section of configure
can be displayed. Any other variable will just be shown as an empty string, irrespective of its real value.
%ENV{MOD_PERL}%
displays as: not set
not set
.
%EXAMPLEVAR{}%
variable is handled by the EmptyPlugin
%EXAMPLEVAR{"text" format="..."}%
text="..."
- example text.
format="..."
- format of report.
%EXAMPLEVAR{"hello" format="| $topic: $summary |"}%
%FAILEDPLUGINS%
%FORMFIELD{"fieldname"}%
Parameter: | Description: | Default: |
---|---|---|
"fieldname" | The name of a TWiki form field | required |
topic="..." | Topic where form data is located. May be of the form Web.TopicName | Current topic |
format="..." | Format string. Variable $value expands to the field value, $title to the raw field name, $name to the field name, $attributes to the attributes, $type to the form field type, $size to the size, and $definingTopic to the form definition topic. | "$value" |
default="..." | Text shown when no value is defined for the field | "" |
alttext="..." | Text shown when field is not found in the form | "" |
newline="$br" | Convert newlines in textarea to other delimiters. Variable $br expands to <br /> tag, and $n to a newline. Other text is encoded based on encode parameter. | no conversion |
encode="html" | Encode special characters into HTML entities. If a FORMFIELD is passed into an HTML form field it should be encoded as "html" . Additional encodings available: encode="quote" , encode="moderate" , encode="safe" , encode="entity" and encode="url" . See ENCODE for details. | "" (no encoding) |
%FORMFIELD{"ProjectName" topic="Projects.SushiProject" default="(not set)" alttext="ProjectName field not found"}%
<input type="text" name="Address" value="%FORMFIELD{ "Address" encode="html" }%" />
%SET{}%
. The %SET{}%
and %GET{}%
variables are handled by the SetGetPlugin.
%GET{ "name" default="..." }%
Attribute | Comment | Default |
---|---|---|
"name" | Name of variable. | (required) |
default="..." | Text shown if variable is not found. | "" (empty string) |
%GET{"lunch"}%
returns Sushi
if the following has been previously set:%SET{ "lunch" value="Sushi" default="undecided" }%
- see more examples
%GMTIME%
2024-10-04 - 18:52
$year-$mo-$day
%GMTIME{"format"}%
Variable: | Unit: | Example |
---|---|---|
$seconds | seconds | 59 |
$minutes | minutes | 59 |
$hours | hours | 23 |
$day | day of month | 31 |
$wday | day of the Week (Sun, Mon, Tue, Wed, Thu, Fri, Sat) | Thu |
$dow | day of the week (Sun = 0) | 2 |
$week | number of week in year (ISO 8601) | 34 |
$month | short name of month | Dec |
$mo | 2 digit month | 12 |
$year | 4 digit year | 1999 |
$ye | 2 digit year | 99 |
$tz | either "GMT" (if set to gmtime), or offset such as "-0700" (if set to servertime) | GMT |
$iso | ISO format timestamp | 2024-10-04T18:52:14Z |
$rcs | RCS format timestamp | 2024/10/04 18:52:14 |
$http | E-mail & http format timestamp | Fri, 04 Oct 2024 18:52:14 GMT |
$epoch | Number of seconds since 00:00 on 1st January, 1970 | 1728067934 |
%GMTIME{"$day $month, $year - $hour:$min:$sec"}%
expands to 04 Oct, 2024 - 18:52:14
GRAY
is one of the rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of colors.
%GRAY% gray text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
GREEN
is one of the rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of colors.
%GREEN% green text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%GROUPS%
%H%
%HEADLINES{"url"}%
variable is handled by the HeadlinesPlugin.
%HEADLINES{ "http://..." }%
"..." | Source of RSS or ATOM feed; this can be a URL (starting with http) or a web.topic location for internal feeds |
refresh="60" | Refresh rate in minutes for caching feed; "0" for no caching |
limit="12" | Maximum number of items shown |
header="..." | Header. May include these variables: - $channeltitle , $title : title of channel (channel.title) - $channellink , $link : link of channel (channel.link) - $channeldescription , $description : description (channel.description) - $channeldate , $date : publication date of the channel (channel.pubDate) - $rights : copyrights of the channel (channel.copyright) - $imagetitle : title text for site (image.title) - $imagelink : link for site (image.link) - $imageurl : URL of image (image.url) - $imagedescription : description of image (image.description) |
format="..." | Format of one item. May include these variables: - $title : news item title (item.title) - $link : news item link (item.link) - $description : news item description (item.description) - $date : the publication date (item.pubDate, item.date) - $category : the article category (item.category) |
Details |
%HEADLINES{ "http://slashdot.org/slashdot.rdf" header="*[[$link][$title]]:* $description" format="$t* [[$link][$title]]" limit="4" }%
shows the latest Slashdot news in bullet list format
%HIDE{ any text }%
<!-- HTML comments -->
also hide content from the user, but unlike HIDE, HTML comments are sent to the browser.
%HOMETOPIC%
WebHome
, renders as WebHome
%HTTP%
%HTTP{"Header-name"}%
%HTTP% | |
%HTTP{"Accept-language"}% | en-US,en;q=0.5 |
%HTTP{"User-Agent"}% | CCBot/2.0 (https://commoncrawl.org/faq/) |
%HTTP_HOST%
wiki.ivoa.net
%HTTP%
but operates on the HTTPS environment variables present when the SSL protocol is in effect. Can be used to determine whether SSL is turned on.
%HTTPS%
%HTTPS{"Header-name"}%
%I%
%ICON{"name"}%
Parameter: | Description: | Default: |
---|---|---|
"name" | Name of icon | required |
format="..." | Format of icon. Supported variables (with %ICON{"person"}% example): • $name - name of icon (person ) • $type - type of icon (gif ) • $filename - icon filename (person.gif ) • $web - web where icon is defined (TWiki ) • $topic - topic where icon is defined (TWikiDocGraphics ) • $description - icon description (Person ) • $width - width of icon ('16') • $height - height of icon ('16') • $img - full img tag of icon (<img src="... /> ) • $info - icon tag with usage info in title • $url - URL of icon (http://example.com/pub/TWiki/TWikiDocGraphics/person.gif ) • $urlpath - URL path of icon (/pub/TWiki/TWikiDocGraphics/person.gif ) | format="$img" |
default="else" | Alternate icon if named icon is not defined | default="$name" |
%ICON{"flag-gray"}%
returns:
%ICON{"pdf"}%
returns:
%ICON{"smile.pdf"}%
returns:
%ICON{"/home/sweet/home.pdf"}%
returns:
%ICON{"http://twiki.org/doc/xhtml.xsl"}%
returns:
%ICON{"bubble" format="$description icon is defined in $web.$topic"}%
returns: Speech bubble icon is defined in TWikiDocGraphics
arrowbright
, bubble
, choice-yes
, hand
bmp
, doc
, gif
, hlp
, html
, mp3
, pdf
, ppt
, txt
, xls
, xml
, zip
%ICON{"name"}%
generates the full HTML img tag. Specify image name or full filename (see ICON for details on filenames.)
%ICONURL{"name"}%
%ICONURL{"arrowbright"}%
returns https://wiki.ivoa.net/internal/TWiki/TWikiDocGraphics/arrowbright.gif
%ICONURL{"novel.pdf"}%
returns https://wiki.ivoa.net/internal/TWiki/TWikiDocGraphics/pdf.gif
%ICONURL{"/queen/boheme.mp3"}%
returns https://wiki.ivoa.net/internal/TWiki/TWikiDocGraphics/wav.gif
%ICONURLPATH{"name"}%
%ICONURLPATH{"locktopic"}%
returns /internal/TWiki/TWikiDocGraphics/locktopic.gif
%ICONURLPATH{"eggysmell.xml"}%
returns /internal/TWiki/TWikiDocGraphics/xml.gif
%ICONURLPATH{"/doc/xhtml.xsl"}%
returns /internal/TWiki/TWikiDocGraphics/xsl.gif
%IF{"CONDITION" then="THEN" else="ELSE"}%
shows "THEN"
if "CONDITION"
evaluates to TRUE
, otherwise "ELSE"
will be shown
%IF{"defined FUNFACTOR" then="FUNFACTOR is defined" else="FUNFACTOR is not defined"}%
renders as FUNFACTOR is not defined
%INCLUDE{"page" ...}%
Parameter: | Description: | Default: |
---|---|---|
"SomeTopic" | The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}% | |
"Web.Topic" | A topic in another web, i.e. %INCLUDE{"TWiki.SiteMap"}% | |
"http://..." | A full qualified URL, i.e. %INCLUDE{"http://twiki.org:80/index.html"}% . Supported content types are text/html and text/plain . if the URL resolves to an attachment file on the server this will automatically translate to a server-side include. | |
pattern="..." | Include a subset of a topic or a web page. Specify a RegularExpression that scans from start ('^' ) to end and contains the text you want to keep in parenthesis, e.g., pattern="^.*?(from here.*?to here).*" . IncludeTopicsAndWebPages has more. | none |
headingoffset="2" | Adjust the level of headings in the included topic. A "2" or "+2" increases the level by two, e.g. a ---+ H1 turns into a ---+++ H3. Positive and negative values are supported. Adjusted min and max levels are H1 and H6, respectively. | no adjustment |
hidetoc="on" | Remove %TOC% in included content. Useful to show table of contents in individual topics, while suppressing them if included in a big master document. | TOC_HIDE_IF_ setting |
rev="2" | Include a previous topic revision; N/A for URLs | top revision |
raw="on" | When a page is included, normally TWiki will process it, doing the following: 1) Alter relative links to point back to originating host, 2) Remove some basic HTML tags (html, head, body, script) and finally 3) Remove newlines from HTML tags spanning multiple lines. If you prefer to include exactly what is in the source of the originating page set this to on . raw="on" is short for disableremoveheaders="on" , disableremovescript="on" , disableremovebody="on" , disablecompresstags="on" and disablerewriteurls="on" . | disabled |
literal="on" | While using the raw option will indeed include the raw content, the included content will still be processed and rendered like regular topic content. To disable parsing of the included content, set the literal option to "on" . | disabled |
disableremoveheaders="on" | Bypass stripping headers from included HTML (everything until first </head> tag) | disabled |
disableremovescript="on" | Bypass stripping all <script> tags from included HTML | disabled |
disableremovebody="on" | Bypass stripping the </body> tag and everything around over and below it | disabled |
disablecompresstags="on" | Bypass replacing newlines in HTML tags with spaces. This compression step rewrites unmatched <'s into < entities unless bypassed | disabled |
disablerewriteurls="on" | Bypass rewriting relative URLs into absolute ones | disabled |
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) | %INCLUDEWARNING% preferences setting |
section="name" | Includes only the specified named section, as defined in the included topic by the STARTSECTION and ENDSECTION variables. Nothing is shown if the named section does not exists. section="" is equivalent to not specifying a section | |
PARAMONE="val 1" | Any other parameter will be defined as a variable within the scope of the included topic. The example parameters on the left will result in %PARAMONE% and %PARAMTWO% being defined within the included topic. A default value for a variable can be specified in the included topic in case the corresponding parameter is not specified, such as %PARAMONE{ default="..." }% |
%INCLUDE{"http://www.google.com/"}%
is turned off by default. To turn this on, ask your TWiki administrator to enable the {INCLUDE}{AllowURLs}
flag in the Security setup section of configure.
raw
or disableremovescript
parameter.
%TOPIC%
in case there is no include
%INCLUDINGTOPIC%
%WEB%
if there is no INCLUDE.
%INCLUDINGWEB%
%INCLUDINGWEB{format="..."}%
-- see WEB for format documentation
%JQTABPANE% %JQTAB{"Tab 1}% ... %JQENDTAB% %JQTAB{"Tab 2}% ... %JQENDTAB% ... %JQENDTABPANE%
%JQTABPANE% %JQTAB{"Tab 1}% ... %JQENDTAB% %JQTAB{"Tab 2}% ... %JQENDTAB% ... %JQENDTABPANE%
%JQTABPANE% %JQTAB{"Tab 1}% ... %JQENDTAB% %JQTAB{"Tab 2}% ... %JQENDTAB% ... %JQENDTABPANE%
Parameter: | Description: | Comment: |
---|---|---|
"..." | Name of tab, shown as tab label | Required, no default |
%JQTAB{"..."}%
and %JQENDTAB%
pairs, and enclose them in %JQTABPANE%
and %JQENDTABPANE%
. Tab panes can be nested, e.g. within one tab you can add another tab pane. These variable are handled by the JQueryPlugin.
%JQTABPANE% %JQTAB{"Tab 1}% ... %JQENDTAB% %JQTAB{"Tab 2}% ... %JQENDTAB% ... %JQENDTABPANE%
%JQTABPANE%
%JQTAB{"Tab 1"}%
Tab 1 content...
%JQENDTAB%
%JQTAB{"Tab 2"}%
Tab 2 content...
%JQENDTAB%
%JQENDTABPANE%
LANGUAGE
preference is set, it's used as user's language instead of any language detected from the browser.
LANGUAGE
at a non per-user way, so each user can choose his/her preferred language.
PO
files) to TWiki. Those are the languages in which TWiki's user interface is available.
%LANGUAGES{...}%
Parameter: | Description: | Default: |
---|---|---|
format | format for each item. See below for variables available in the format string. | " * $langname" |
separator | separator between items. | "\n" (newline) |
marker="selected" | Text for $marker if the item matches selection | "selected" |
selection="%LANGUAGE%" | Current language to be selected in list | (none) |
format
variables: Variable | Meaning |
---|---|
$langname | language's name, as informed by the translators |
$langtag | language's tag. Ex: en , pt-br , etc. |
<select>%LANGUAGES{format="<option $marker value='$langtag'>$langname</option>" selection="%LANGUAGE%"}%</select>
creates an option list of the available languages with the current language selected
LIME
is one of the rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of colors.
%LIME% lime text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%LOCALSITEPREFS%
Main.TWikiPreferences
, renders as TWikiPreferences
%LOGIN%
%LOGINURL%
/twiki/bin/login/TWiki/TWikiDocumentation?origurl=/twiki/bin/view/TWiki/TWikiDocumentation
%LOGOUT%
%LOGOUTURL%
/twiki/bin/view/TWiki/TWikiDocumentation?logout=1
%M%
%MAKETEXT{"string" args="..."}%
Parameter | Description | Default |
---|---|---|
"text" or string="text" | The text to be displayed. | none |
args="param1, param2" | a comma-separated list of arguments to be interpolated in the string, replacing the [_N] placeholders in it. | none |
%MAKETEXT{string="Notes:"}%
%MAKETEXT{"If you have any questions, please contact [_1]." args="%WIKIWEBMASTER%"}%
%MAKETEXT{"Did you want to [[[_1]][reset [_2]'s password]]?" args="%SYSTEMWEB%.ResetPassword,%WIKIUSERNAME%"}%
string
to the current user's language only if it has such string in its translation table for that language.
&
) followed by one letter (one of a...z
, A...Z
-- say, X
) in the translatable string will be translated to <span class='twikiAccessKey'>X</span>
. This is used to implement access keys. If you want to write an actual amperstand that stays just before a letter, write two consecutive amperstands (&&
): they will be transformed in just one.
_
) are reserved. You must not use translatable phrases starting with an underscore.
%VARIABLES%
inside the translatable strings (since they will get expanded before the %MAKETEXT{...}%
itself is handled).
MAROON
is one of the rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of colors.
%MAROON% maroon text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
formfield
item is the most likely to be useful to casual users.
%META{ "item" ...}%
Item | Options | Description |
---|---|---|
"formfield" | name="..." : name of the field. The field value can be shortened as described in FormattedSearch for $formfield . newline="..." : by default, each newline character will be rewritten to <br /> to allow metadata that contains newlines to be used in tables, etc. $n indicates a newline character.bar="..." : by default, each vertical bar is rewritten to an HTML entity so as to not be mistaken for a table separator.topic="..." : Get meta info of "Topic" or "Web.Topic"; default "%BASEWEB%.%BASETOPIC%" . | Show a single form field |
"form" | topic="..." : Get meta info of "Topic" or "Web.Topic"; default "%BASEWEB%.%BASETOPIC%" . | Generates the table showing the form fields. See Form Templates |
"attachments" | all="on" to show hidden attachments.title="..." to show a title - only if attachments are displayed.template="..." to use a custom template for the rendering of attachments; default attachtables is used.topic="..." : Get meta info of "Topic" or "Web.Topic"; default "%BASEWEB%.%BASETOPIC%" . | Generates the list of attachments |
"moved" | topic="..." : Get meta info of "Topic" or "Web.Topic"; default "%BASEWEB%.%BASETOPIC%" . | Details of any topic moves |
"parent" | dontrecurse="on" : By default recurses up tree, this has some cost.nowebhome="on" : Suppress WebHome. prefix="..." : Prefix that goes before parents, but only if there are parents, default "" . format="..." : Format string used to display each parent topic where $web expands to the web name, and $topic expands to the topic name; default: "[[$web.$topic][$topic]]" suffix="..." : Suffix, only appears if there are parents; default "" . separator="..." : Separator between parents; default " > " . topic="..." : Get meta info of "Topic" or "Web.Topic"; default "%BASEWEB%.%BASETOPIC%" . | Generates the parent link |
%META{}%
is placed in an included topic. Add a topic="%WEB%.%TOPIC%"
parameter if you need meta info of the current topic.
newline
, prefix
, format
, suffix
and separator
options, such as separator="$n * "
%METASEARCH{...}%
Parameter: | Description: | Default: |
---|---|---|
type="topicmoved" | What sort of search is required? "topicmoved" if search for a topic that may have been moved "parent" if searching for topics that have a specific parent i.e. its children "field" if searching for topics that have a particular form field value (use the name and value parameters to specify which field to search) | Required |
web="%WEB%" | Wiki web to search: A web, a list of webs separated by whitespace, or all webs. | Current web |
topic="%TOPIC%" | The topic the search relates to, for topicmoved and parent searches | All topics in a web |
name | form field to search, for field type searches. May be a regular expression (see SEARCH). | |
value | form field value, for field type searches. May be a regular expression (see SEARCH). | |
title="Title" | Text that is prefixed to any search results | empty |
format="..." | Custom format results. Supports same format strings as SEARCH. See FormattedSearch for usage, variables & examples | Results in table |
default="none" | Default text shown if no search hit | Empty |
%METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%
%METASEARCH{type="parent" web="%WEB%" topic="%TOPIC%" title="Children: "}%
%METASEARCH{type="field" name="Country" value="China"}%
%N%
NAVY
is one of the rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of colors.
%NAVY% navy text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%NOP%
%NOP{...}%
deprecated %STARTSECTION{type="templateonly"}%
.. %ENDSECTION{type="templateonly"}%
instead (see TWikiTemplates for more details).
%NOTIFYTOPIC%
WebNotify
, renders as WebNotify
OLIVE
is one of the rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of colors.
%OLIVE% olive text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
ORANGE
is one of the rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of colors.
%ORANGE% orange text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%P%
%PARENTTOPIC%
or %PARENTTOPIC{ format="..." topic="..." }%
TWikiVariables
, renders as TWikiVariables
Item | Description | Default |
---|---|---|
format="..." | Format string used to display parent topic, where $web expands to the web name, and $topic expands to the topic name. Additional formatting tokens can be used. | "$topic" (topic name) |
topic="..." | Get parent of "Topic" or "Web.Topic" | "%WEB%.%TOPIC%" (current topic) |
PINK
is one of the rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of colors.
%PINK% pink text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%PLUGINDESCRIPTIONS%
"$SUM( $ABOVE() )"
to TWiki tables or anywhere in topic text ExternalSite:Page
to link to a page on an external site based on aliases defined in a rules topic :-)
for or :eek:
for %PLUGINVERSION{"name"}%
to get the version of a specific plugin
%PLUGINVERSION{"InterwikiPlugin"}%
expands to $Rev: 30454 (2018-07-16) $
%PLUGINVERSION%
to get the version of the API
6.10
%PUBURL%
https://wiki.ivoa.net/internal
%PUBURL%/%WEB%/OtherTopic/image.gif
%PUBURLPATH%
/internal
PURPLE
is one of the rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of colors.
%PURPLE% purple text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%Q%
%QUERYPARAMS{...}%
format="..."
format string for each entry, default $name=$value
separator="..."
separator string, default separator="$n"
(newline)
encode="..."
the encoding to apply to parameter values; see ENCODE for a description of the available encodings. If this parameter is not given, no encoding is performed.
Sequence: | Expands To: |
---|---|
$name | Name of the parameter |
$value | String value of the parameter. Multi-valued parameters will have a "row" for each value. |
$n or $n() | New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() | Is a "no operation". This variable gets removed; useful for nested search |
$quot or \" | Double quote (" ) |
$percnt | Percent sign (% ) |
$dollar | Dollar sign ($ ) |
$lt | Less than sign (< ) |
$gt | Greater than sign (> ) |
%QUERYPARAMS{format="<input type='hidden' name='$name' value='$value' encoding="html" />"}%
%QUERYPARAMS%
.
%QUERYSTRING%
RED
is one of the rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of colors.
%RED% red text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
REDBG
is one of the rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of background colors.
%REDBG% red background %ENDBG%
%REDBG%
area must end with %ENDBG%
.
%REDIRECT{}%
variable is handled by the RedirectPlugin.
%REDIRECT{"TopicName"}%
%REDIRECT{"ExampleTopic"}%
redirects to the ExampleTopic topic
%REDIRECT{"OtherWeb.ExampleTopic"}%
redirects to the OtherWeb.ExampleTopic topic
%REDIRECT{"http://twiki.org/"}%
redirects to http://twiki.org/
%REMOTE_ADDR%
3.237.15.145
%REMOTE_PORT%
%REMOTE_USER%
%RENDERLIST%
variable is handled by the RenderListPlugin
%RENDERLIST%
%RENDERLIST{ "org" focus="Sales.WestCoastTeam" }%
%RENDERLIST{ "org" }%
* [[Eng.WebHome][Engineering]]
* [[Eng.TechPubs][Tech Pubs]]
* [[Sales.WestCoastTeam][Sales]]
* [[Sales.EastCoastTeam][East Coast]]
* [[Sales.WestCoastTeam][West Coast]]
%REVINFO%
r3 - 2010-12-29 - 23:23:37 - TWikiContributor
$year-$mo-$day
%REVINFO{"format"}%
Parameter: | Description: | Default: |
---|---|---|
"format" | Format of revision information, see supported variables below | "r1.$rev - $date - $wikiusername" |
web="..." | Name of web | Current web |
topic="..." | Topic name | Current topic |
rev="5" | Specific revison number. Old RCS format "1.5" is also supported. | Latest revision |
Variable: | Unit: | Example |
---|---|---|
$web | Name of web | Current web |
$topic | Topic name | Current topic |
$rev | Revison number. Add prefix r to get the usual r5 format | 5 |
$username | Login username of revision | jsmith |
$wikiname | WikiName of revision | JohnSmith |
$wikiusername | WikiName with Main web prefix | Main.JohnSmith |
$date | Revision date. Actual date format defined as {DefaultDateFormat} in configure, default $year-$mo-$day | 2010-12-31 |
$time | Revision time | 23:24:25 |
$iso | Revision date in ISO date format | 2006-09-22T06:24:25Z |
$min , $sec , etc. | Same date format qualifiers as GMTIME{"format"} |
%REVINFO{"$date - $wikiusername" rev="1.1"}%
returns revision info of first revision
%S%
viewauth.cgi
)
%SCRIPTNAME%
view
.pl
or .cgi
%SCRIPTSUFFIX%
%SCRIPTURL%
https://wiki.ivoa.net/twiki/bin
edit
script should always be used in conjunction with ?t=%GMTIME{"$epoch"}%
to ensure pages about to be edited are not cached in the browser
%SCRIPTURL{"script"}%
https://wiki.ivoa.net/twiki/bin/script
%SCRIPTURL{"viewauth"}%/%WEB%/%TOPIC%
which expands to https://wiki.ivoa.net/twiki/bin/viewauth/TWiki/TWikiVariables
[[%SCRIPTURL{view}%/%WEB%/MyQuery?food=sushi][Sushi]]
%SCRIPTURLPATH{"script"}%
instead, as it works with URL rewriting much better
%SCRIPTURL%
, but doesn't include the protocol and host part of the URL
%SCRIPTURLPATH%
/twiki/bin
edit
script should always be used in conjunction with ?t=%GMTIME{"$epoch"}%
to ensure pages about to be edited are not cached in the browser
%SCRIPTURL{"script"}%
, but doesn't include the protocol and host part of the URL
%SCRIPTURLPATH{"script"}%
/twiki/bin/script
%SEARCH{"text" ...}%
Parameter: | Description: | Default: |
---|---|---|
"text" | Search term. Is a keyword search, literal search, regular expression search, or query, depending on the type parameter. SearchHelp has more | required |
search="text" | (Alternative to above) | N/A |
web="Name" web="Main, Know" web="all" | Comma-separated list of webs to search. You can specifically exclude webs from an all search using a minus sign - for example, web="all,-Secretweb" . The special word all means all webs that do not have the NOSEARCHALL variable set to on in their WebPreferences. Note that TWikiAccessControls are respected when searching webs; it is much better to use them than NOSEARCHALL . | 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. Note this is a list of topic names and must not include web names. | 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. Note this is a list of topic names and must not include web names. | None |
scope="topic" scope="text" scope="all" | Search topic name (title); the text (body) of topic; or all (title and body) | "text" |
type="keyword" type="word" type="literal" type="regex" type="query" | Control how the search is performed when scope="text" or scope="all" keyword : use Google-like controls as in soap "web service" -shampoo ; searches word parts: using the example, topics with "soapsuds" will be found as well, but topics with "shampoos" will be excluded word : identical to keyword but searches whole words: topics with "soapsuds" will not be found, and topics with "shampoos" will not be excluded literal : search for the exact string, like web service regex : use a RegularExpression search like soap;web service;!shampoo ; to search on whole words use \bsoap\b query : query search of form fields and other meta-data, like (Firstname='Emma' OR Firstname='John') AND Lastname='Peel' | %SEARCHVAR- DEFAULTTYPE% preferences setting (literal) |
order="topic" order="created" order="modified" order="editby" order= | Sort the results of search by the topic names, topic creation time, last modified time, last editor, or named field of TWikiForms. The sorting is done web by web; if you want to sort across webs, create a formatted table and sort it with TablePlugin's initsort. Note that dates are sorted most recent date last (i.e at the bottom of the table). | Sort by topic name |
limit="all" limit="16" | Limit the number of results returned. This is done after sorting if order is specified | All results |
date="..." | limits the results to those pages with latest edit time in the given time interval. | All results |
reverse="on" | Reverse the direction of the search | Ascending search |
casesensitive="on" | Case sensitive search | Ignore case |
bookview="on" | BookView search, e.g. show complete topic text | Show topic summary |
nonoise="on" | Shorthand for nosummary="on" nosearch="on" nototal="on" zeroresults="off" noheader="on" noempty="on" | Off |
nosummary="on" | Show topic title only | Show topic summary |
nosearch="on" | Suppress search string | Show search string |
noheader="on" | Suppress default search header Topics: Changed: By: , unless a header is explicitly specified | Show default search header, unless search is inline and a format is specified (Cairo compatibility) |
nototal="on" | Do not show number of topics found | Show number |
zeroresults="off" | Suppress all output if there are no hits | zeroresults="on" , displays: "Number of topics: 0" |
noempty="on" | Suppress results for webs that have no hits. | Show webs with no hits |
headingoffset="2" | Adjust the level of headings in text of topics found, taking effect in $text and $pattern() of a FormattedSearch. A "2" or "+2" increases the level by two, e.g. a ---+ H1 turns into a ---+++ H3. Positive and negative values are supported. Adjusted min and max levels are H1 and H6, respectively. | no adjustment |
header="..." format="..." footer="..." | Custom format results: see FormattedSearch for usage, variables & examples | Results in table |
expandvariables="on" | Expand variables before applying a FormattedSearch on a search hit. Useful to show the expanded text, e.g. to show the result of a SpreadSheetPlugin %CALC{}% instead of the formula | Raw text |
multiple="on" | Multiple hits per topic. Each hit can be formatted. The last token is used in case of a regular expression ";" and search | Only one hit per topic |
nofinalnewline="on" | If on , the search variable does not end in a line by itself. Any text continuing immediately after the search variable on the same line will be rendered as part of the table generated by the search, if appropriate. | off |
recurse="on" | Recurse into subwebs, if subwebs are enabled. | off |
separator=", " | Line separator between search hits | "$n" (Newline) |
newline="%BR%" | Line separator within a search hit. Useful if you want to put multi-line content into a table cell, for example if the format="" parameter contains a $pattern() that captures more than one line, or contains a $formfield() that returns a multi-line textfield. | "$n" (Newline) |
%SEARCH{"wiki" web="Main" scope="topic"}%
%SEARCH{"FAQ" scope="topic" nosearch="on" nototal="on" header="| *Topic: * | *Summary: * |" format="| $topic | $summary |"}%
(displays results in a table with header - details)
%TABLE{}%
variable just before the %SEARCH{}%
to alter the output of a search. Example: %TABLE{ tablewidth="90%" }%
%SERVERTIME%
2024-10-04 - 20:52
$year-$mo-$day
%GMTIME%
%SERVERTIME{"format"}%
$seconds
, $minutes
, $hours
, $day
, $wday
, $dow
, $month
, $mo
, $year
, $ye
, $tz
, $iso
, $rcs
, $http
, $epoch
%SERVERTIME{"$hou:$min"}%
expands to 20:52
%SESSIONID%
%SESSIONVAR%
%SESSION_VARIABLE{"name"}%
- read a session variable
%SESSION_VARIABLE{"name" set="value"}%
- set a session variable
%SESSION_VARIABLE{"name" clear=""}%
- clear a session variable
%SESSION_VARIABLE{"AUTHUSER"}%
- user ID, current value:
%SESSION_VARIABLE{"SESSION_REQUEST_NUMBER"}%
- number of pages accessed by current user since login, current value:
%GET{}%
. No output is shown, e.g. %SET{}%
resolves to an empty string. The %SET{}%
and %GET{}%
variables are handled by the SetGetPlugin.
%SET{ "name" value="..." remember="1" }%
Attribute | Comment | Default |
---|---|---|
"name" | Name of variable. Alphanumeric characters, dashes and underscores can be used. | (required) |
value="..." | Value of variable. Escape double quotes with backslash. | (required, may be empty) |
remember="1" | If set, the variable will be stored persistently so that it can be used later in any TWiki topic. See important notes. | "0" |
%SET{"lunch" value="Sushi"}%
- see more examples.
%SET{}%
. The %SETGETDUMP{}%
, %SET{}%
, and %GET{}%
variables are handled by the SetGetPlugin.
%SETGETDUMP{ format="..." separator="..." }%
Attribute | Comment | Default |
---|---|---|
format="..." | Format output using variables $key and $value | "key: $key, value: $value <br />" |
separator="..." | String used for separating entries | "\n" |
%SETGETDUMP{"| $key | $value |" separator="$n"}%
- see more examples.
SILVER
is one of the rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of colors.
%SILVER% silver text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%SLIDESHOWEND%
variable is handled by the SlideShowPlugin
%SLIDESHOWEND%
%SLIDESHOWSTART%
variable is handled by the SlideShowPlugin
%SLIDESHOWSTART%
%SLIDESHOWSTART{ template="MyOwnSlideTemplate" }%
%SLIDESHOWSTART%
---++ Sample Slide 1
* Bullet 1
* Bullet 2
---++ Sample Slide 2
* Bullet 1
* Bullet 2
%SLIDESHOWEND%
%SPACEDTOPIC%
Var%20*SPACEDTOPIC
%ENCODE{%SPACEOUT{"%TOPIC%" separator=" *"}%}%
%SPACEOUT{ "%TOPIC%" }%
TWiki Variables
Parameter: | Description: | Default: |
---|---|---|
separator | The separator to put between words e.g. %SPACEOUT{"DogsCatsBudgies" separator=", "}% -> Dogs, Cats, Budgies | ' ' |
[[WebHome][%SPACEOUT{"WebHome"}%]]
expands to Web Home
%STOPINCLUDE%
variable. A normal view of the topic shows everything exept the %STARTINCLUDE%
variable itself.
%STARTSECTION{type="include"}%
instead
%STARTINCLUDE%
%STARTSECTION{}%
and %ENDSECTION{}%
.
type="section"
- the default, used for a generic section, such as a named section used by INCLUDE.
type="include"
- like %STARTINCLUDE%
... %STOPINCLUDE%
except that you can have as many include blocks as you want (%STARTINCLUDE%
is restricted to only one).
type="templateonly"
- start position of text to be removed when a template topic is used. Use this to embed text that you do not want expanded when a new topic based on the template topic is created. TWikiTemplates has more.
type="expandvariables"
- start position where TWikiVariables get expanded when a new topic is created. Normally only certain variables get expanded when a new topic based on the template topic is created. All variables get expanded within a "expandvariables"
section. TWikiTemplates has more.
%STARTSECTION{"name"}% ................... %ENDSECTION{"name"}%
%STARTSECTION{type="include"}% ........... %ENDSECTION{type="include"}%
%STARTSECTION{type="templateonly"}% ...... %ENDSECTION{type="templateonly"}%
%STARTSECTION{type="expandvariables"}% ... %ENDSECTION{type="expandvariables"}%
Parameter: | Description: | Default |
---|---|---|
"name" | Name of the section. Must be unique inside a topic. | Generated name |
type="..." | Type of the section; type "section" , "include" , "templateonly" , or "expandvariables" | "section" |
_SECTION0
for the first unnamed section in the topic, _SECTION1
for the second, etc..
%STATISTICSTOPIC%
WebStatistics
, renders as WebStatistics
%STOPINCLUDE%
variable itself.
%STOPINCLUDE%
%SYSTEMWEB%
TWiki
%T%
%TABLE{}%
variable is handled by the TablePlugin
%TABLE{ attributes }%
Argument | Comment | Default value | Example |
---|---|---|---|
sort | Set table sorting by clicking headers "on" or "off" . | unspecified | sort="on" |
initsort | Column to sort initially ("1" to number of columns). | unspecified | initsort="2" |
initdirection | Initial sorting direction for initsort , set to "up" (descending) or "down" (ascending). | unspecified | initdirection="up" |
disableallsort | Disable all sorting, both initsort and header sort. This is mainly used by plugins such as the EditTablePlugin to disable sorting in a table while editing the table. | unspecified | disableallsort="on" |
headerbg | Header cell background colour. | "#6b7f93" | headerbg="#999999" |
headerbgsorted | Header cell background colour of a sorted column. | the value of headerbg | headerbgsorted="#32596c" |
headercolor | Header cell text colour. | "#ffffff" | headercolor="#0000cc" |
databg | Data cell background colour, a comma separated list. Specify "none" for no colour, that is to use the colour/background of the page the table is on. | "#edf4f9,#ffffff" | databg="#f2f2f2,#ffffff" |
databgsorted | Data cell background colour of a sorted column; see databg . | the values of databg | databgsorted="#d4e8e4,#e5f5ea" |
datacolor | Data cell text colour, a comma separated list. | unspecified | datacolor="#0000CC, #000000" |
tableborder | Table border width (pixels). | "1" | tableborder="2" |
tableframe | Table frame, set to "void" (no sides), "above" (the top side only), "below" (the bottom side only), "hsides" (the top and bottom sides only), "lhs" (the left-hand side only), "rhs" (the right-hand side only), "vsides" (the right and left sides only), "box" (all four sides), "border" (all four sides). | unspecified | tableframe="hsides" |
tablerules | Table rules, set to "none" (no rules), "groups" (rules will appear between row groups and column groups only), "rows" (rules will appear between rows only), "cols" (rules will appear between columns only), "all" (rules will appear between all rows and columns). | unspecified | tablerules="rows" |
cellpadding | Cell padding (pixels). | "0" | cellpadding="0" |
cellspacing | Cell spacing (pixels). | "0" | cellspacing="3" |
cellborder | Cell border width (pixels). | unspecified | cellborder="0" |
valign | Vertical alignment of cells and headers, set to "top" , "middle" , "bottom" or "baseline" . | unspecified | valign="top" |
headervalign | Vertical alignment of header cells; overrides valign . | unspecified | headervalign="top" |
datavalign | Vertical alignment of data cells; overrides valign . | unspecified | datavalign="top" |
headeralign | Header cell alignment, one value for all columns, or a comma separated list for different alignment of individual columns. Set to "left" , "center" , "right" or "justify" . Overrides individual cell settings. | unspecified | headeralign="left,right" |
dataalign | Data cell alignment, one value for all columns, or a comma separated list for different alignment of individual columns. Set to "left" , "center" , "right" or "justify" . Overrides individual cell settings. | unspecified | dataalign="center" |
tablewidth | Table width: Percentage of window width, or absolute pixel value. | unspecified | tablewidth="100%" |
columnwidths | Column widths: Comma delimited list of column widths, percentage or absolute pixel value. | unspecified | columnwidths="80%,20%" |
headerrows | Number of header rows to exclude from sort. (will be rendered in a HTML thead section) | "1" | headerrows="1" |
footerrows | Number of footer rows to exclude from sort. (will be rendered in a HTML tfoot section) | "0" | footerrows="1" |
id | Unique table identifier string, used for targeting a table with CSS. | tableN (where N is the table order number on the page) | id="userTable" |
summary | Table summary used by screenreaders: A summary of what the table presents. It should provide an orientation for someone who listens to the table. | unspecified | summary="List of subscribed users" |
caption | Table caption: A title that will be displayed just above the table. | unspecified | caption="Users" |
%TABLE{ tableborder="0" cellpadding="4" cellspacing="3" cellborder="0" }%
| *A1* | *B1* |
| A2 | B2 |
TEAL
is one of the rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of colors.
%TEAL% teal text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
"---++ 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. An abbreviated heading can be shown in the TOC, such as "---++ text!! this is excluded from TOC"
.
%TOC%
"---++ 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. An abbreviated heading can be shown in the TOC, such as "---++ text!! this is excluded from TOC"
.
%TOC{"SomeTopic" ...}%
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 |
%TOC{depth="2"}%
%TOC{"TWikiDocumentation" web="TWiki" title="Contents:"}%
%TOPIC%
expands to the name of the topic. If you are looking at the text of an included topic, it is the name of the included topic.
%TOPIC%
TWikiVariables
, renders as TWikiVariables
$topic
variable gets expanded to the topic name, $marker
to marker
parameter where topic matches selection
, and $web
to the name of the web, or any of the standard FormatTokens.
%TOPICLIST{"format" ...}%
Parameter: | Description: | Default: |
---|---|---|
"format" | Format of one line, may include $web (name of web), $topic (name of the topic), $marker (which expands to marker for the item matching selection only) | "$topic" |
format="format" | (Alternative to above) | "$topic" |
separator=", " | line separator | "$n" (new line) |
marker="selected" | Text for $marker if the item matches selection | "selected" |
selection="TopicA, TopicB" | Current value to be selected in list | (none) |
web="Name" | Name of web | Current web |
%TOPICLIST{" * $web.$topic"}%
creates a bullet list of all topics
%TOPICLIST{separator=", "}%
creates a comma separated list of all topics
%TOPICLIST{" <option>$topic</option>"}%
creates an option list (for drop down menus)
<select>%TOPICLIST{" <option $marker value='$topic'>$topic</option>" separator=" " selection="%TOPIC%"}%</select>
creates an option list of web topics with the current topic selected
%TOPICURL%
- shortcut for %SCRIPTURL{view}%/%WEB%/%TOPIC%
%TWISTY{}%
variable is handled by the TwistyPlugin.
%TWISTY{}% ... %ENDTWISTY%
%TWISTY{}%
my twisty content
%ENDTWISTY%
%U%
%URLPARAM{"name"}%
Parameter: | Description: | Default: |
---|---|---|
"name" | The name of a URL parameter | required |
newline="$br" | Convert newlines in textarea to other delimiters. Variables $br (for <br /> tag), $n (for newline) are expanded. Other text is encoded based on encode parameter. | no conversion |
encode="off" | Turn off encoding. See important security note below | encode="safe" |
encode="quote" | Escape double quotes with backslashes (\" ), does not change other characters; required when feeding URL parameters into other TWiki variables. This encoding does not protect against cross-site scripting. | encode="safe" |
encode="moderate" | Encode special characters into HTML entities for moderate cross-site scripting protection: "<" , ">" , single quote (' ) and double quote (" ) are encoded. Useful to allow TWiki variables in comment boxes. | encode="safe" |
encode="safe" | Encode special characters into HTML entities for cross-site scripting protection: "<" , ">" , "%" , single quote (' ) and double quote (" ) are encoded. | (this is the default) |
encode="entity" | Encode special characters into HTML entities. See ENCODE for details. | encode="safe" |
encode="html" | Encode special characters into HTML entities. In addition to encode="entity" , it also encodes space, newline (\n ) and linefeed (\r ). Useful to encode text properly in HTML input fields. | encode="safe" |
encode="url" | Encode special characters for URL parameter use, like a double quote into %22 | encode="safe" |
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" (newline) |
format="..." | Format the result. $value expands to the URL parameter. If multiple is specified, $value expands to the result of the concatenated items. | "$value" |
default="..." | Default value in case parameter is empty or missing. The format parameter is not applied. | empty string |
%URLPARAM{"skin"}%
returns print
for a .../view/TWiki/TWikiVariables?skin=print
URL
encode="safe"
is the default, it provides a safe middle ground. The encode="entity"
is more aggressive, but some TWiki applications might not work.
"html"
. <input type="text" name="address" value="%URLPARAM{ "address" encode="html" }%" />
%SEARCH{ "%URLPARAM{ "search" encode="quotes" }%" noheader="on" }%
rev
, skin
, template
, topic
, web
; they have a special meaning in TWiki. Common parameters and view script specific parameters are documented at TWikiScripts.
%URLPARAM{
in the value of a URL parameter, it will be modified to %<nop>URLPARAM{
. This is to prevent an infinite loop during expansion.
%USERINFO%
guest, TWikiGuest,
(comma-separated list of the username, wikiusername, and emails)
$emails
, $username
, $wikiname
, $wikiusername
, $groups
and $admin
($admin returns 'true' or 'false'): %USERINFO{ format="$username is really $wikiname" }%
guest is really TWikiGuest
%USERINFO{ "TWikiGuest" format="$username is really $wikiname" }%
guest is really TWikiGuest
{AntiSpam}{HideUserDetails}
configuration option is not enabled, or if you are an admin. (User details are hidden in this TWiki)
jsmith
, WIKINAME like JohnSmith
and WIKIUSERNAME like Main.JohnSmith
. Un-authenticated users are all TWikiGuest.
%USERNAME%
guest
%USERSWEB%
Main
%VAR{"NAME" web="Web"}%
%WEBBGCOLOR%
of the Main web write %VAR{"WEBBGCOLOR" web="Main"}%
, which expands to #FFEFA6
%VBAR%
%WEB%
expands to the name of the web where the topic is located. If you are looking at the text of an included topic, it is the web where the included topic is located.
%WEB%
, expands to: TWiki
%WEB{format="..."}%
Parameter: | Description: | Default: |
---|---|---|
format="..." | Format, may include tokens $web (the full web path), $parents (parent webs, if any), $current (current web without parent webs) | "$web" |
%WEB%
is Engineering/TechPubs/Apps
: %WEB{format="Parent webs: $parents, current web: $current"}%
returns: Parent webs: Engineering/TechPubs, current web: Apps
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
.
%WEBLIST{"format" ...}%
Parameter: | Description: | Default: |
---|---|---|
"format" | Format of one line, may include $name (the name of the web), $qname (the name of the web in double quotes), $indentedname (the name of the web with parent web names replaced by indents, for use in indented lists), and $marker (which expands to marker for the item matching selection only) | "$name" |
format="format" | (Alternative to above) | "$name" |
separator=", " | Line separator | "$n" (new line) |
web="" | if you specify $web in format, it will be replaced with this | "" |
webs="public" | Comma separated list of webs, public expands to all non-hidden.NOTE: Administrators will see all webs, not just the public ones | "public" |
marker="selected" | Text for $marker if the item matches selection | "selected" |
selection="%WEB%" | Current value to be selected in list | selection="%WEB%" |
subwebs="Sandbox" | Show webs that are a sub-web of this one (recursivly) | "" |
limit="30" | Limit number of webs to show | "" (all) |
overlimit="..." | Message shown if over limit, such as: overlimit=" * [[%SYSTEMWEB%.SiteMap][More...]]" | "" |
%WEBLIST{" * [[$name.WebHome]]"}%
- creates a bullet list of all webs.
<form><select name="web"> %WEBLIST{"<option $marker value=$qname>$name</option>" webs="Trash, public" selection="%WEB%" separator=" "}% </select></form>
- creates a dropdown of all public webs + Trash web, with the current web highlighted.
%WEBPREFSTOPIC%
WebPreferences
, renders as WebPreferences
WHITE
is one of the rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of colors.
%WHITE% white text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%WIKIHOMEURL%
/twiki/bin/view/Main/WebHome
%SCRIPTURLPATH{"view"}%/%USERSWEB%/%HOMETOPIC%
%WIKILOGOURL%
defined in WebPreferences instead.
%WIKILOGOALT%
International Virtual Observatory Alliance
%WIKILOGOIMG%
/internal/TWiki/TWikiPreferences/ivoa_logo137x77.jpg
%WIKILOGOURL%
/
%SCRIPTURLPATH{"view"}%/%USERSWEB%/%HOMETOPIC%
%USERNAME%
if not defined in the TWikiUsers topic
%WIKINAME%
TWikiGuest
%WIKIPREFSTOPIC%
TWikiPreferences
, renders as TWikiPreferences
%WIKITOOLNAME%
TWiki
%WIKIUSERNAME%
Main.TWikiGuest
, renders as TWikiGuest
%WIKIUSERSTOPIC%
TWikiUsers
, with Main prefix renders as TWikiUsers
%WIKIVERSION%
TWiki-6.1.0, Mon, 16 Jul 2018, build 30610
%X%
%Y%
YELLOW
is one of the rendering shortcut settings predefined in TWikiPreferences. See the section rendering shortcut settings in that topic for a complete list of colors.
%YELLOW% yellow text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%SEARCH{...}%
is a table consisting of topic names and topic summaries. Use the format="..."
parameter to customize the search result. The format parameter typically defines a bullet or a table row containing variables, such as %SEARCH{ "food" format="| $topic | $summary |" }%
. See %SEARCH{...}%
for other search parameters, such as separator=""
.
header="..."
parameter header="| *Topic:* | *Summary:* |"
Variables that can be used in the header string:
Name: | Expands To: |
---|---|
$web |
Name of the web |
$n or $n() |
New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() |
Is a "no operation". This variable gets removed; useful for nested search |
$quot or \" |
Double quote (" ) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
$lt |
Less than sign (< ) |
$gt |
Greater than sign (> ) |
format="..."
parameter 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, shortened 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. 04 Oct 2024 - 18:52 |
$isodate |
Time stamp of last topic update, e.g. 2024-10-04T18:52Z |
$rev |
Number of last topic revision, e.g. 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 |
$createusername |
Login name of topic revision 1, e.g. jsmith |
$createwikiname |
Wiki user name of topic revision 1, e.g. JohnSmith |
$createwikiusername |
Wiki user name of topic revision 1, e.g. Main.JohnSmith |
$summary |
Topic summary, just the plain text, all formatting and line breaks removed; up to 162 characters |
$summary(50) |
Topic summary, up to 50 characters shown |
$summary(showvarnames) |
Topic summary, with %ALLTWIKI{...}% variables shown as ALLTWIKI{...} |
$summary(noheader) |
Topic summary, with leading ---+ headers removedNote: The tokens can be combined, for example $summary(100, showvarnames, noheader) |
$changes |
Summary of changes between latest rev and previous rev |
$changes(n) |
Summary of changes between latest rev and rev n |
$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, shortened to 30 characters with "..." indication |
$query(query-syntax) |
Access topic meta data using SQL-like QuerySearch syntax. Example: • $query(attachments.arraysize) returns the number of files attached to the current topic • $query(attachments[name~'*.gif'].size) returns an array with size of all .gif attachments, such as 848, 1425, 923 • $query(parent.name) is equivalent to $parent |
$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 e-mail 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 |
$count(reg-exp) |
Count of number of times a regular expression pattern appears in the text of a topic (does not search meta data). Follows guidelines for use and limitations outlined above under $pattern(reg-exp) . Example: $count(.*?(---[+][+][+][+]) .*) counts the number of <H4> headers in a page. |
$ntopics |
Number of topics found in current web. This is the current topic count, not the total number of topics |
$nhits |
Number of hits if multiple="on" . Cumulative across all topics in current web. Identical to $ntopics unless multiple="on" |
$n or $n() |
New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() |
Is a "no operation". This variable gets removed; useful for nested search |
$quot or \" |
Double quote (" ) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
$lt |
Less than sign (< ) |
$gt |
Greater than sign (> ) |
footer="..."
parameter footer="| *Topic* | *Summary* |"
Variables that can be used in the footer string:
Name: | Expands To: |
---|---|
$web |
Name of the web |
$ntopics |
Number of topics found in current web |
$nhits |
Number of hits if multiple="on" . Cumulative across all topics in current web. Identical to $ntopics unless multiple="on" |
$n or $n() |
New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() |
Is a "no operation". This variable gets removed; useful for nested search |
$quot or \" |
Double quote (" ) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
$lt |
Less than sign (< ) |
$gt |
Greater than sign (> ) |
%SEARCH{}%
are evaluated once before the search. This is OK for variables that do not change, such as %SCRIPTURLPATH%
. Variables that should be evaluated once per search hit must be escaped. For example, to escape a conditional:
%IF{ "..." then="..." else="..." }%
format="$percntIF{ \"...\" then=\"...\" else=\"...\" }$percnt"
%SEARCH{ "FAQ" scope="topic" nosearch="on" nototal="on" header=" * *Topic: Summary:*" format=" * [[$topic]]: $summary" footer=" * *Topic: Summary*" }%
To get this:
TopicClassification
field, an OperatingSystem
field and an OsVersion
field we could write:
| *Topic:* | *OperatingSystem:* | *OsVersion:* |
%SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" scope="text" type="regex" nosearch="on" nototal="on" format="| [[$topic]] | $formfield(OperatingSystem) | $formfield(OsVersion) |" }%
To get this:
Topic: | OperatingSystem | OsVersion |
---|---|---|
IncorrectDllVersionW32PTH10DLL | OsWin | 95/98 |
WinDoze95Crash | OsWin | 95 |
%SEARCH{ "__Back to\:__ TWikiFAQ" scope="text" type="regex" nosearch="on" nototal="on" header="TWiki FAQs:" format=" * $pattern(.*?FAQ\:[\n\r]*([^\n\r]+).*) [[$topic][Answer...]]" }%
To get this:
TWiki FAQs: %SEARCH{ "culture" format=" * $topic is referenced by: (list all references)" nosearch="on" nototal="on" }%
%SEARCH{ "(topic found in first search)" format="$topic" nosearch="on" nototal="on" separator=", " }%
$percnt
to escape the leading percent of the second search
\"
to escape the double quotes
$dollar
to escape the $
of $topic
$nop
to escape the }%
sequence
%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:
$dollarpercntSEARCH{
for level three, $dollardollarpercntSEARCH{
for level four, etc.
%SEARCH{ "\.*" scope="topic" type="regex" nosearch="on" nototal="on" order="modified" reverse="on" format="| [[$topic]] | $wikiusername | $date |" limit="7" }%
To get this:
TWikiRegistration | GiuliaIafrate | 2024-04-08 - 07:41 |
RedirectPlugin | TWikiAdminUser | 2023-01-19 - 10:06 |
VarREDIRECT | TWikiAdminUser | 2023-01-19 - 10:06 |
BackupRestoreConsole | TWikiAdminUser | 2022-12-02 - 09:41 |
BackupRestorePlugin | TWikiAdminUser | 2022-12-02 - 09:41 |
TinyMCEPlugin | TWikiAdminUser | 2022-12-02 - 09:10 |
TinyMCEQuickHelp | TWikiAdminUser | 2022-12-02 - 09:10 |
%CALC{$SET(weekold, $TIMEADD($TIME(), -7, day))}%
%SEARCH{ "." scope="topic" type="regex" nosearch="on" nototal="on" order="modified" reverse="on" format="$percntCALC{$IF($TIME($date) < $GET(weekold), <nop>, | [[$topic]] | $wikiusername | $date | $rev |)}$percnt" limit="100" }%
weekold
variable to the serialized date of exactly one week ago
$percnt
makes sure that the CALC gets executed once for each search hit
weekold
date
<nop>
is returned, which gets removed at the end of the TWiki rendering process
%URLPARAM{"..."}%
variable. Example:
Write this:
<form action="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%"> Find Topics: <input type="text" name="q" size="32" value="%URLPARAM{"q" encode="entity"}%" /> <input type="submit" class="twikiSubmit" value="Search" /> </form> Result: %SEARCH{ search="%URLPARAM{"q" encode="quote"}%" type="keyword" format=" * $web.$topic: %BR% $summary" nosearch="on" }%To get this: Result: Related Topics: UserDocumentationCategory, SearchHelp, VarSEARCH, SearchPatternCookbook, RegularExpression, QuerySearch -- Contributors: TWiki:Main.PeterThoeny, TWiki:Main.CrawfordCurrie, TWiki:Main.SopanShewale Back to top
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. *.php
files are renamed to *.php.txt
so that no one can place code that would be read in a .php file.
%ATTACHFILESIZELIMIT%
variable of the TWikiPreferences, currently set at 150000 KB. Manage
on the Attachment to be moved.
Move
. The attachment and its version history are moved. The original location is stored as topic Meta Data.
Trash
, topic TrashAttachment
.
Attach
file: Sample.txt
Edit
topic and enter: %ATTACHURL%/Sample.txt
Preview
: %ATTACHURL%/Sample.txt
text appears as: /internal/TWiki/FileAttachment/Sample.txt, a link to the text file.
%PUBURLPATH%/%WEB%/OtherTopic/Sample.txt
(if it's within the same web)
%PUBURLPATH%/Otherweb/OtherTopic/Sample.txt
(if it's in a different web)
Attach
file: Sample.txt
Edit
topic and write text: %INCLUDE{"%ATTACHURL%/Sample.txt"}%
Attach
file: Smile.gif
Edit
topic and write text: %ATTACHURL%/Smile.gif
Preview
: text appears as /internal/TWiki/FileAttachment/Smile.gif, an image.
I | Attachment | Action | Size | Date | Who | Comment |
---|---|---|---|---|---|---|
txt | Sample.txt | manage | 0.1 K | 22 Jul 2000 - 19:37 | TWikiContributor | Just a sample |
gif | Smile.gif | manage | 0.1 K | 22 Jul 2000 - 19:38 | TWikiContributor | Smiley face |
Manage
link takes you to a new page that looks a bit like this (depending on what skin is selected):
Sample.txt
(UploadingUser)h
means the attachment is hidden, it isn't listed when viewing a topic.
Hide file
checkbox, then click Change properties
.
YourForm
, ExpenseReportForm
, InfoCategoryForm
, RecordReviewForm
, whatever you need.
Name
, Type
, Size
, Values
, Tooltip message
, and Attributes
(see sample below).
Example:See structure of a form for full details of what types are available and what all the columns mean. You can also retrieve possible values for
| *Name* | *Type* | *Size* | *Values* | *Tooltip message* | *Attributes* |
| TopicClassification | select | 1 | NoDisclosure, PublicSupported, PublicFAQ | blah blah... | |
| OperatingSystem | checkbox | 3 | OsHPUX, OsLinux, OsSolaris, OsWin | blah blah... | |
| OsVersion | text | 16 | | blah blah... | |
Name Type Size Values Tooltip message Attributes TopicClassification select 1 NoDisclosure, PublicSupported, PublicFAQ blah blah... OperatingSystem checkbox 3 OsHPUX, OsLinux, OsSolaris, OsWin blah blah... OsVersion text 16 blah blah...
select
, checkbox
or radio
types from other topics:
Example:Field values can also be set using the result of expanding other TWiki variables. For example,
- In the WebForm topic, define the form:
Name Type Size Values Tooltip message Attributes TopicClassification select 1 blah blah... OperatingSystem checkbox 3 blah blah... OsVersion text 16 blah blah...
Leave theValues
field blank.
- Then in the TopicClassification topic, define the possible values:
| *Name* |
| NoDisclosure |
| Public Supported |
| Public FAQ |
Name NoDisclosure Public Supported Public FAQ
%SEARCH{"Office$" scope="topic" web="%USERSWEB%" nonoise="on" type="regex" format="$web.$topic" separator=", " }%
When used in the value field of the form definition, this will find all topic names in the Main web which end in "Office" and use them as the legal field values.
WEBFORMS
variable in WebPreferences is optional and defines a list of possible form templates.
Example:
- Set WEBFORMS = BugForm, FeatureForm, Books.BookLoanForm
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.
SEARCH
to define WEBFORMS
.
WebTopicEditTemplate
topic in a web, or a new topic that serves as an application specific template topic. Initial Form values can be set there.
formtemplate
parameter in the (edit or save) URL. Initial values can then be provided in the URLs or as form values: name
, ex: ?BugPriority=1
namevalue=1
, ex: ?ColorRed=1
. <form name="newtopic" action="%SCRIPTURLPATH{"edit"}%/%WEB%/"> <input type="hidden" name="formtemplate" value="MyForm" /> New topic name <input type="text" name="topic" size="40" /> <input type="submit" class="twikiSubmit" value="Create" /> </form>
save
script instead of the edit
script in the form action. When you specify the save
script you have to use the "post" method. Example: <form name="newtopic" action="%SCRIPTURLPATH{"save"}%/%WEB%/" method="post"> ..... </form>
edit
and save
scripts understand many more parameters, see TWikiScripts#edit and TWikiScripts#save for details.
Name
, Type
, Size
, Values
, Tooltip message
, and Attributes
.
The Name
, Type
and Size
columns are required. Other columns are optional. The form must have a header row (e.g. | *Name* | *Type* | *Size* |
).
Name column: Name
is the name of the form field.
Type, Size, Value columns: Type
, Size
and Value
describe the type, size and initial value for this field:
Type | Description | Size | Value |
---|---|---|---|
text |
One-line text field | Text box width in number of characters | Initial (default) content |
textarea |
Multi-line text box | Columns x rows, such as 80x6 ; default is 40x5 |
Initial (default) content |
label |
Read-only text label | Text of the label | |
checkbox |
One or more checkboxes that can be toggled individually | Number of checkboxes shown per line | Comma-space-separated list of item labels - can be a dynamic SEARCH |
checkbox+buttons |
Like checkbox , adding [Set] and [Clear] buttons |
||
radio |
Radio buttons, mutually exclusive; only one can be selected | Number of radio buttons shown per line | Comma-space-separated list of item labels - can be a dynamic SEARCH |
select |
Select box, rendered as a picklist or a multi-row selector box depending on the size value | • 1 : Show a picklist • Number > 1: Multi-row selector box of specified size • Range e.g. 3..10 : Multi-row selector box with variable size - the box will never be smaller than 3 items, never larger than 10, and will be 5 high if there are only 5 options |
Comma-space-separated list of options of the select box - can be a dynamic SEARCH |
select+multi |
Like select , turning multi-select on, to allow Shift+Click and Ctrl+Click to select (or deselect) multiple items |
||
select+values |
Like select , allowing definition of values that are different to the displayed text. For example:| Field 9 | select+values | 3 | One, Two=2, Three=III | Various values formats | shows but the values of options Two and Three are 2 and III , respectively. |
||
select+multi+values |
Combination of select+multi and select+values |
||
color |
Single-line text box and a color picker to pick a color. The color can also be typed into the text box, such as #123456 . |
Text box width in number of characters | Initial (default) color |
date |
Single-line text box and a button next to it to pick a date from a popup calendar. The date can also be typed into the text box. The date format can be customized. | Text box width in number of characters | Initial (default) date |
Tooltip message
will be displayed when the cursor is hovered over the field in edit
view.
Attributes column: Attributes
specifies special attributes for the field. Multiple attributes can be entered, separated by spaces.
H
indicates that this field is hidden, e.g. not shown in view mode. However, the field is available for editing and storing information.
M
indicates that this field is mandatory. The topic cannot be saved unless a value is provided for this field. If the field is found empty during topic save, an error is raised and the user is redirected to an oops
page. Mandatory fields are indicated by an asterisks next to the field name.
| *Name* | *Type* | *Size* | | Name | text | 80 | | Date | date | 30 |Field Name Notes:
Aeroplane Manufacturers
is equivalent to AeroplaneManufacturers
.
label
field has no name, it will not be shown when the form is viewed, only when it is edited.
select
, checkbox
or radio
field, and want to get the values from another topic, you can use [[...]]
links. This notation can also be used when referencing another topic to obtain field values, but a name other than the topic name is required as the name of the field.
label
, text
, and textarea
fields the value may also contain commas. checkbox
fields cannot be initialized through the form template.
|
character in the initial values field, you have to precede it with a backslash, thus: \|
.
<nop>
to prevent TWiki variables from being expanded.
| *Name* | *Type* | *Size* | | AeroplaneManufacturers | select | |the TWiki will look for the topic AeroplaneManufacturers to get the possible values for the
select
.
The AeroplaneManufacturers topic must contain a table, where each row of the table describes a possible value. The table only requires one column, Name
. Other columns may be present, but are ignored.
For example:
| *Name* | | Routan | | Focke-Wulf | | De Havilland |Notes:
Values
column must be empty in the referring form definition.
checkbox
+multi
anywhere in the name
form
(see details).
action=form
parameter to the edit URL string, such as%SCRIPTURL{edit}%/%BASEWEB%/%BASETOPIC%?t=%SERVERTIME{$epoch}%;action=form
(see details).
SubmitExpenseReport
topic where you can create new expense reports, a SubmitVacationRequest
topic, and so on. These can specify the required template topic with its associated form. Template topics has more.
A Form Template specifies the fields in a form. A Form Template is simply a page containing a TWiki table, where each row of the table specifies one form field.
FORMFIELD
, SEARCH
and METASEARCH
variables in TWikiVariables, and TWiki Formatted Search.
ExampleSearching forms this way is obviously pretty inefficient, but it's easy to do. If you want better performance, take a look at some of the structured wiki extensions that support higher performance searching e.g. TWiki:Plugins.DBCachePlugin.
TWiki users often want to have an overview of topics they contributed to. With the$formfield
parameter it is easy to display the value of a classification field next to the topic link:| *Topic* | *Classification* | %SEARCH{"%USERSWEB%.UserName" scope="text" nosearch="on" nototal="on" order="modified" reverse="on" format="|<b>[[$web.$topic][$topic]]</b> |<nop>$formfield(TopicClassification) |" web="Sandbox"}%
text
fields when a topic is saved. If you need linefeeds in a field, make sure it is a textarea
.
.tmpl
.
They are usually HTML with embedded template directives.
The directives are expanded when TWiki wants to generate a user interface screen.
%TMPL:<key>%
and %TMPL:<key>{"attr"}%
.
%TMPL:INCLUDE{"file"}%
: Includes a template file. The file is found as described below.
%TMPL:DEF{"block"}%
: Define a block. All text between this and the next %TMPL:END%
directive is removed and saved for later use with %TMPL:P
.
%TMPL:END%
: Ends a block definition.
%TMPL:P{"var"}%
: Includes a previously defined block.
%{...}%
: is a comment.
twiki.tmpl
master template, like twiki.print.tmpl
, that redefines the header and footer.
%TMPL:DEF{"x"}% x%P%z%TMPL:END%
then %TMPL:P{"x" P="y"}%
will expand to xyz
.
Note that parameters can simply be ignored; for example, %TMPL:P{"x"}%
will expand to x%P%z.
Any alphanumeric characters can be used in parameter names.
You are highly recommended to use parameter names that cannot be confused with TWikiVariables.
Note that three parameter names, context
, then
and else
are reserved.
They are used to support a limited form of "if" condition that you can use to select which of two templates to use, based on a context identifier:
%TMPL:DEF{"link_inactive"}%<input type="button" disabled value="Link>%TMPL:END% %TMPL:DEF{"link_active"}%<input type="button" onclick="link()" value="Link" />%TMPL:END% %TMPL:P{context="inactive" then="inactive_link" else="active_link"}% for %CONTEXT%When the "inactive" context is set, then this will expand the "link_inactive" template; otherwise it will expand the "link_active" template. See IfStatements for details of supported context identifiers.
twiki/templates/view.tmpl
is the default template file for the twiki/bin/view
script.
You can save templates in other directories as long as they are listed in the {TemplatePath}
configuration setting.
The {TemplatePath}
is defined in the Miscellaneous section of the configure page.
You can also save templates in user topics (IF there is no possible template match in the templates
directory).
The {TemplatePath}
configuration setting defines which topics will be accepted as templates.
Templates that are included with an explicit '.tmpl'
extension are looked for only in the templates/
directory.
For instance %TMPL:INCLUDE{"example.tmpl"}%
will only return templates/example.tmpl
, regardless of {TemplatePath}
and SKIN settings.
The out-of-the-box setting of {TemplatePath}
supports the following search order to determine which template file or topic to use for a particular script or %TMPL:INCLUDE{"script"}%
statement.
The skin path is set as described in TWikiSkins.
view
, edit
View
dragon
, pattern
. All skins are checked at each stage, in the order they appear in the skin path.
Dragon
example
template file will be searched for in the following places, when the current web is Thisweb
and the skin path is print,pattern
:
templates/Thisweb/example.print.tmpl
deprecated; don't rely on it
templates/Thisweb/example.pattern.tmpl
deprecated; don't rely on it
templates/example.print.tmpl
templates/example.pattern.tmpl
templates/Thisweb/example.tmpl
deprecated; don't rely on it
templates/example.tmpl
Thisweb.PrintSkinExampleTemplate
Thisweb.PatternSkinExampleTemplate
Thisweb.ExampleTemplate
TWiki.PrintSkinExampleTemplate
TWiki.PatternSkinExampleTemplate
TWiki.ExampleTemplate
view
and edit
scripts, for example when a topic-specific template is required. Two preference variables can be used to override the templates used: VIEW_TEMPLATE
sets the template to be used for viewing a topic
EDIT_TEMPLATE
sets the template for editing a topic.
view
and edit
respectively. The template search order is as specified above.
Tip: If you want to override existing templates, without having to worry that your changes will get overwritten by the next TWiki update, change the {TemplatePath}
so that another directory, such as the %USERSWEB%
appears at the front. You can then put your own templates into that directory or web and these will override the standard templates. (Note that such will increase the lookup time for templates by searching your directory first.)
%TMPL:INCLUDE{"twiki"}%
, the templating system will include the next twiki.SKIN in the skin path.
For example, to create a customisation of pattern skin, where you only want to over-ride the breadcrumbs for the view script, you can create only a view.yourlocal.tmpl:
%TMPL:INCLUDE{"view"}% %TMPL:DEF{"breadcrumb"}% We don't want any crumbs %TMPL:END%and then set SKIN=yourlocal,pattern The default
{TemplatePath}
will not give you the desired result if you put these statements in the topic Thisweb.YourlocalSkinViewTemplate
. The default {TemplatePath}
will resolve the request to the template/view.pattern.tmpl
, before it gets to the Thisweb.YourlocalSkinViewTemplate
resolution. You can make it work by prefixing the {TemplatePath}
with: $web.YourlocalSkin$nameTemplate
.
twiki.tmpl
is the default master template. It defines the following sections.
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 |
Topic Name: | What it is: |
---|---|
WebTopicViewTemplate | Alert page shown when you try to view a nonexistent topic. This page is usually used as a prompt to help you create a new topic. |
WebTopicNonWikiTemplate | Alert page shown when you try to view a nonexistent topic with a non-WikiName. Again, this page is used as a prompt to help you create the new topic. |
WebTopicEditTemplate | Default text used in a new topic. |
<MyCustomNamed>Template | Whenever you create a topic ending in the word "Template", it is automatically added to the list of available templates in the "Use Template" drop down field on the WebCreateNewTopic page. |
edit
script, TWiki locates a topic to use as a content template according to the following search order: templatetopic
CGI parameter Variable: | Description: |
---|---|
%DATE% |
Signature format date. See VarDATE |
%GMTIME% |
Date/time. See VarGMTIME |
%GMTIME{...}% |
Formatted date/time. See VarGMTIME2 |
%NOP% |
A no-operation variable that gets removed. Useful to prevent a SEARCH from hitting an edit template topic; also useful to escape a variable, such as %URLPA%NOP%RAM{...}% escaping URLPARAM |
%STARTSECTION{type="templateonly"}% |
Text that gets removed when a new topic based on the template is created. See notes below. |
%SERVERTIME% |
Date/time. See VarSERVERTIME |
%SERVERTIME{...}% |
Formatted date/time. See VarSERVERTIME2 |
%USERNAME% |
Login name of user who is instantiating the new topic, e.g. guest |
%URLPARAM{"name"}% |
Value of a named URL parameter. See VarURLPARAM. |
%WIKINAME% |
WikiName of user who is instantiating the new topic, e.g. TWikiGuest |
%WIKIUSERNAME% |
User name of user who is instantiating the new tpoic, e.g. Main.TWikiGuest |
%STARTSECTION{type="templateonly"}% ... %ENDSECTION{type="templateonly"}%
section. For example, you might want to write this in the template topic:
%STARTSECTION{type="templateonly"}% This template can only be changed by: * Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup %ENDSECTION{type="templateonly"}%This will restrict who can edit the template topic, but will be removed when a new topic based on that template topic is created.
%NOP%
can be used to prevent expansion of TWiki variables that would otherwise be expanded during topic creation. For example, escape %SERVERTIME%
with %SER%NOP%VERTIME%
.
type="expandvariables"
section in the template topic, such as:
...Example: If you have the following content in a template topic:
* %SYSTEMWEB%.ATasteOfTWiki - view a short introductory presentation on TWiki for beginners * %SYSTEMWEB%.WelcomeGuest - starting points on TWiki * %SYSTEMWEB%.TWikiUsersGuide - complete TWiki documentation * Sandbox.%HOMETOPIC% - try out TWiki on your own * Sandbox.%TOPIC%Sandbox - just for meyou will get this raw text in new topics based on that template topic:
* TWiki.ATasteOfTWiki - view a short introductory presentation on TWiki for beginners * TWiki.WelcomeGuest - starting points on TWiki * TWiki.TWikiUsersGuide - complete TWiki documentation * Sandbox.WebHome - try out TWiki on your own * Sandbox.JimmyNeutronSandbox - just for me
formtemplate
CGI parameter to the edit
script to specify the name of a form to attach.
See TWikiScripts for information about all the other parameters to edit
.
AUTOINC<n>
to the topic name in the edit and save scripts, and it will be replaced with an auto-incremented number on topic save. <n>
is a number starting from 0, and may include leading zeros. Leading zeros are used to zero-pad numbers so that auto-incremented topic names can sort properly. Deleted topics are not re-used to ensure uniqueness of topic names. That is, the auto-incremented number is always higher than the existing ones, even if there are gaps in the number sequence.
Examples: BugAUTOINC0
- creates topic names Bug0
, Bug1
, Bug2
, ... (does not sort properly)
ItemAUTOINC0000
- creates topic names Item0000
, Item0001
, Item0002
, ... (sorts properly up to 9999)
DocIDAUTOINC10001
- start with DocID10001
, DocID10002
, ... (sorts properly up to 99999; auto-links)
[[%SCRIPTURLPATH{edit}%/%WEB%/BugIDAUTOINC00001?templatetopic=BugTemplate;topicparent=%TOPIC%;t=%SERVERTIME{"$day$hour$min$sec"}%][Create new item]]
templatetopic
specifies ExampleTopicTemplate as the template topic to use. Here is the HTML source of the form:
<form name="new" action="%SCRIPTURLPATH{edit}%/Sandbox/"> * New example topic: <input type="text" name="topic" value="ExampleTopicAUTOINC0001" size="30" /> <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" /> <input type="hidden" name="topicparent" value="%TOPIC%" /> <input type="hidden" name="onlywikiname" value="on" /> <input type="hidden" name="onlynewtopic" value="on" /> <input type="submit" class="twikiSubmit" value="Create" /> </form>Note: You can create a topic in one step, without going through the edit screen. To do that, specify the
save
script instead of the edit
script in the form action. When you specify the save script you have to use the "post" method. Example:
<form name="new" action="%SCRIPTURLPATH{save}%/Sandbox/" method="post"> ... </form>The
edit
and save
scripts understand many more parameters, see TWikiScripts#edit and TWikiScripts#save for details.
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%
twiki/templates
directory and are named according to the skin: <scriptname>.<skin>.tmpl
. Skin files may also be defined in TWiki topics - see TWikiTemplates for details.
To start creating a new skin, copy the default TWikiTemplates (like view.tmpl
), or copy an existing skin to use as a base for your own skin. You should only need to copy the files you intend to customise, as TWiki can be configured to fall back to another skin if a template is not defined in your skin. Name the files as described above (for example view.myskin.tmpl
.
If you use PatternSkin as your starting point, and you want to modify the layout, colors or even the templates to suit your own needs, have a look first at the topics PatternSkinCustomization and PatternSkinCssCookbook.
For your own TWiki skin you are encouraged to show a small 80x31 pixel logo at the bottom of your skin:
<a href="http://twiki.org/"><img src="%PUBURL%/%SYSTEMWEB%/TWikiLogos/T-logo-80x15.gif" alt="This site is powered by the TWiki collaboration platform" width="80" height="15" title="This site is powered by the TWiki collaboration platform" border="0" /></a>
The standard TWiki skins show the logo in the %WEBCOPYRIGHT%
variable.
Note: Two skin names have reserved meanings; text
skin, and skin names starting with rss
have hard-coded meanings.
The following template files are used for TWiki screens, and are referenced in the TWiki core code. If a skin doesn't define its own version of a template file, then TWiki will fall back to the next skin in the skin path, or finally, to the default version of the template file.
(Certain template files are expected to provide certain TMPL:DEFs - these are listed in sub-bullets) addform
- used to select a new form for a topic
attachagain
- used when refreshing an existing attachment
attachnew
- used when attaching a new file to a topic
attachtables
- defines the format of attachments at the bottom of the standard topic view ATTACH:files:footer
, ATTACH:files:header
, ATTACH:files:row
, ATTACH:versions:footer
, ATTACH:versions:header
, ATTACH:versions:row
changeform
- used to change the form in a topic
changes
- used by the changes
script
edit
- used for the edit screen
form
formtables
- used to defined the format of forms FORM:display:footer
, FORM:display:header
, FORM:display:row
login
- used for loggin in when using the TemplateLoginManager LOG_IN
, LOG_IN_BANNER
, LOG_OUT
, LOGGED_IN_BANNER
, NEW_USER_NOTE
, UNRECOGNISED_USER
moveattachment
- used when moving an attachment
oopsaccessdenied
- used to format Access Denied messages no_such_topic
, no_such_web
, only_group
, topic_access
oopsattention
- used to format Attention messages already_exists
, bad_email
, bad_ver_code
, bad_wikiname
, base_web_missing
, confirm
, created_web
, delete_err
, invalid_web_color
, invalid_web_name
, in_a_group
, mandatory_field
, merge_notice
, missing_action
, missing_fields
, move_err
, missing_action
, no_form_def
, no_users_to_reset
, notwikiuser
, oversized_upload
, password_changed
, password_mismatch
, problem_adding
, remove_user_done
, rename_err
, rename_not_wikiword
, rename_topic_exists
, rename_web_err
, rename_web_exists
, rename_web_prerequisites
, reset_bad
, reset_ok
, save_error
, send_mail_error
, thanks
, topic_exists
, unrecognized_action
, upload_name_changed
, web_creation_error
, web_exists
, web_missing
, wrong_password
, zero_size_upload
oopschangelanguage
- used to prompt for a new language when internationalisation is enabled
oopsgeneric
- a basic dialog for user information; provides "ok" button only
oopslanguagechanged
- used to confirm a new language when internationalisation is enabled
oopsleaseconflict
- used to format lease Conflict messages lease_active
, lease_old
preview
- used for previewing edited topics before saving
rdiff
- used for viewing topic differences
registernotify
- used by the user registration system
registernotifyadmin
- used by the user registration system
rename
- used when renaming a topic
renameconfirm
- used when renaming a topic
renamedelete
- used when renaming a topic
renameweb
- used when renaming a web
renamewebconfirm
- used when renaming a web
renamewebdelete
- used when renaming a web
searchbookview
- used to format inline search results in book view
searchformat
- used to format inline search results
search
- used by the search
CGI script
settings
view
- used by the view
CGI script
viewprint
- used to create the printable view
twiki.tmpl
is a master template conventionally used by other templates, but not used directly by code.
Note: Make sure templates do not end with a newline. Any newline will expand to an empty <p />
in the generated html. It will produce invalid html, and may break the page layout.
%TMPL:INCLUDE{"twiki"}%
, the templating system will include the next twiki.SKIN in the skin path.
For example, to create a customisation of pattern skin, where you only want to remove the edit & WYSIWYG buttons from view page, you create only a view.yourlocal.tmpl
:
%TMPL:INCLUDE{"view"}% %TMPL:DEF{"edit_topic_link"}%%TMPL:END% %TMPL:DEF{"edit_wysiwyg_link"}%%TMPL:END%and then set
SKIN=yourlocal,pattern
.
Because ClassicSkin and the default templates use the same Template definition names, you can over-ride the edit links in them (or any skin derived from them) using the same view.yourlocal.tmpl
(just set SKIN=yourlocal,classic either in TWikiPreferences for globally, or a Web's Webname.WebPreferences for a particular web)
Variable: | Expanded to: |
---|---|
%WEBLOGONAME% |
Filename of web logo |
%WEBLOGOIMG% |
Image URL of web logo |
%WEBLOGOURL% |
Link of web logo |
%WEBLOGOALT% |
Alt text of web logo |
%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 |
%SCRIPTURLPATH% |
The script URL path |
%SCRIPTSUFFIX% |
The script suffix, ex: .pl , .cgi |
%WEB% |
The name of the current web. |
%TOPIC% |
The name of the current topic. |
%WEBTOPICLIST% |
Common links of current web, defined in the WebPreferences. It includes a Jump box |
%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; can be set in TWikiPreferences |
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 onchange
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 Jump Box for illustration purposes. You need to have JavaScript enabled for this to work:
Note: Redirect to a URL only works if it is enabled in configure
(Miscellaneous, {AllowRedirectUrl}
).
styles.pattern.tmpl
.
<style type='text/css' media='all'>@import url('%PUBURLPATH%/%SYSTEMWEB%/MySkin/mystyle.css');</style>
attachtables.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 |
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 |
ATTACH:row
macros are expanded for each file in the attachment table, using the following special tags:
Tag | Description |
---|---|
%A_URL% |
viewfile URL that will recover the file |
%A_REV% |
Revision of this file |
%A_ICON% |
A file icon suitable for representing the attachment content |
%A_FILE% |
The name of the file. To get the 'pub' url of the file, use %PUBURL%/%WEB%/%TOPIC%/%A_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 |
view.
skin.tmpl
, where skin is the name of the skin e.g. pattern
. If no template is found, then the fallback is to use view.tmpl
. Each skin on the path is searched for in turn. For example, if you have set the skin path to local,pattern
then view.local.tmpl
will be searched for first, then view.pattern.tmpl
and finally view.tmpl
.
The basic skin is defined by a SKIN
setting:
Set SKIN = catskin, bearskin
?skin=catskin,bearskin
:
Setting SKIN
(or the ?skin
parameter in the URL) replaces the existing skin path setting, for the current page only. You can also extend the existing skin path as well, using covers.
Set COVER = ruskin
ruskin, catskin, bearskin
). There is also an equivalent cover
URL parameter. The difference between setting SKIN
vs. COVER
is that if the chosen template is not found (e.g., for included templates), SKIN
will fall back onto the next skin in line, or the default skin, if only one skin was present, while COVER
will always fall back onto the current skin.
An example would be invoking the printable mode, which is achieved by applying ?cover=print
. The view.print.tmpl
simply invokes the viewprint
template for the current skin which then can appropriately include all other used templates for the current skin. Where the printable mode be applied by using SKIN
, all skins would have the same printable appearance.
The full skin path is built up as follows: SKIN
setting (or ?skin
if it is set), then COVER
setting is added, then ?cover
.
text
skin is reserved for TWiki internal use.
Skin names starting with rss
also have a special meaning; if one or more of the skins in the skin path starts with 'rss' then 8-bit characters will be encoded as XML entities in the output, and the content-type
header will be forced to text/xml
.
Related Topics: TWikiSkinBrowser, AdminDocumentationCategory, DeveloperDocumentationCategory, TWiki:TWiki.TWikiSkinsSupplement
-- Contributors: TWiki:Main.PeterThoeny, TWiki:Main.MikeMannix, TWiki:Main.CrawfordCurrie
Back to top
META:
tags
META:
tags.
META:
data includes program-generated info like FileAttachment and topic movement data, and user-defined TWikiForms info.
%META:<type>{key1="value1" key2="value2" ...}%
name
, this appears first for easier searching (note the order of the variables themselves is defined).
Example of Format%META:TOPICINFO{version="1.6" date="976762663" author="LastEditorWikiName" format="1.0"}% text of the topic %META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="TopicMoverWikiName" date="976762680"}% %META:TOPICPARENT{name="NavigationByTopicContext"}% %META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }% %META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }% %META:FORM{name="WebFormTemplate"}% %META:FIELD{name="OperatingSystem" value="OsWin"}% %META:FIELD{name="TopicClassification" value="PublicFAQ"}%
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{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 |
Key | Comment |
---|---|
name | The topic from which this was created, typically when clicking on a red-link, or by filling out a form. Normally just TopicName , but it can be a full Web.TopicName format if the parent is in a different Web. |
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 |
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 |
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 |
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 |
diff
function output appears in a logical order
META:TOPICINFO
META:TOPICPARENT
(optional)
META:TOPICMOVED
(optional)
META:FILEATTACHMENT
(0 or more entries)
META:FORM
(optional)
META:FIELD
(0 or more entries; FORM required)
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
view
, preview
and edit
scripts.
You can render form fields in topic text by using the FORMFIELD variable. Example:%FORMFIELD{"TopicClassification"}%
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 " > " . |
Behaviour
Javascript event library to create Javascript based interactions that degrade well when Javascript is not available - version 18694 (2010-05-29) %FAILEDPLUGINS%
variable can be used to debug failures. You may also want to check your webserver error log and the various TWiki log files.
ab
utility. Example on Unix:time wget -qO /dev/null /twiki/bin/view/TWiki/AbcPlugin
If you need to install an "expensive" plugin, but you only need its functionality only in a subset of your data, you can disable it elsewhere by defining the %DISABLEDPLUGINS% TWiki variable.
Define DISABLEDPLUGINS
to be a comma-separated list of names of plugins to disable. Define it in Main.TWikiPreferences to disable those plugins everywhere, in the WebPreferences topic to disable them in an individual web, or in a topic to disable them in that topic. For example,
* Set DISABLEDPLUGINS = SpreadSheetPlugin, EditTablePlugin
{PluginsOrder}
in the plugins section of configure.
Set VARCACHEPLUGIN_REFRESH = 24
%<pluginname>_<setting>%
, such as %VARCACHEPLUGIN_REFRESH%
.
To learn how this is done, use the TWiki:Plugins.VarCachePlugin documentation and Perl plugin code as a reference.
2. Use configure settings:
The administrator can set plugin settings in the configure interface. Recommended if only site administrators should be able to change settings. Chose this option to set sensitive or dangerous system settings, such as passwords or path to executables. To define plugin-specific configure settings,
lib/TWiki/Plugins/YourPlugin/
with variables, such as$TWiki::cfg{Plugins}{RecentVisitorPlugin}{ShowIP} = 0;
$showIP = $TWiki::cfg{Plugins}{RecentVisitorPlugin}{ShowIP} || 0;
Set SHORTDESCRIPTION = Show recent visitors to a TWiki site
our $SHORTDESCRIPTION = 'Show recent visitors to a TWiki site';
our $NO_PREFS_IN_TOPIC = 1;
%ACTIVATEDPLUGINS%
%PLUGINDESCRIPTIONS%
"$SUM( $ABOVE() )"
to TWiki tables or anywhere in topic text ExternalSite:Page
to link to a page on an external site based on aliases defined in a rules topic :-)
for or :eek:
for %FAILEDPLUGINS%
Plugin | Errors |
---|---|
SpreadSheetPlugin | none |
BackupRestorePlugin | none |
ColorPickerPlugin | none |
CommentPlugin | none |
DatePickerPlugin | none |
EditTablePlugin | none |
HeadlinesPlugin | none |
InterwikiPlugin | none |
JQueryPlugin | none |
PreferencesPlugin | none |
RedirectPlugin | none |
SetGetPlugin | none |
SlideShowPlugin | none |
SmiliesPlugin | none |
TWikiSheetPlugin | none |
TablePlugin | none |
TagMePlugin | none |
TinyMCEPlugin | none |
TwistyPlugin | none |
WatchlistPlugin | none |
WysiwygPlugin | none |
Handler | Plugins |
---|---|
afterEditHandler | WysiwygPlugin |
afterRenameHandler | TagMePlugin WatchlistPlugin |
afterSaveHandler | TagMePlugin WatchlistPlugin |
beforeCommonTagsHandler | EditTablePlugin PreferencesPlugin TWikiSheetPlugin TwistyPlugin WysiwygPlugin |
beforeEditHandler | TinyMCEPlugin WysiwygPlugin |
beforeMergeHandler | WysiwygPlugin |
beforeSaveHandler | CommentPlugin WatchlistPlugin WysiwygPlugin |
commonTagsHandler | SpreadSheetPlugin BackupRestorePlugin CommentPlugin EditTablePlugin JQueryPlugin SlideShowPlugin SmiliesPlugin TWikiSheetPlugin |
initPlugin | SpreadSheetPlugin BackupRestorePlugin ColorPickerPlugin CommentPlugin DatePickerPlugin EditTablePlugin HeadlinesPlugin InterwikiPlugin JQueryPlugin PreferencesPlugin RedirectPlugin SetGetPlugin SlideShowPlugin SmiliesPlugin TWikiSheetPlugin TablePlugin TagMePlugin TinyMCEPlugin TwistyPlugin WatchlistPlugin WysiwygPlugin |
modifyHeaderHandler | WysiwygPlugin |
postRenderingHandler | PreferencesPlugin WysiwygPlugin |
preRenderingHandler | InterwikiPlugin SmiliesPlugin TablePlugin |
lib/TWiki/Func.pm
) describes all the interfaces available to plugins. Plugins should only use the interfaces described in this module.
Note: If you use other core functions not described in Func.pm
, you run the risk of creating security holes. Also, your plugin will likely break and require updating when you upgrade to a new version of TWiki.
lib/TWiki/Plugins/EmptyPlugin.pm
module.
#
from all lines of the callback.
eval
block like this:eval { require IPC::Run }
return "<font color=\"red\">SamplePlugin: Can't load required modules ($@)</font>" if $@;
lib/TWiki/Plugins/BathPlugin/
.
$NO_PREFS_IN_TOPIC
in your plugin package as that will stop TWiki from reading the plugin topic for every page. Use Config.spec or preferences settings instead. (See details).
$VERSION
variable. This should be an integer, or a subversion version id.
initPlugin
handler should check all dependencies and return 1 if the initialization is OK or 0 if something went wrong. initPlugin
handler).
$TWiki::Plugins::VERSION
in the TWiki::Plugins
module contains the TWiki plugin API version, currently 6.10. %PLUGINVERSION{}%
variable to query the plugin API version or the version of installed plugins.
%TWiki::cfg
hash than adding it as preferences in the plugin topic. configure
describes the steps
MyFirstPlugin.pm
MyFirstPlugin.txt
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.
The TWiki:Plugins.BuildContrib module provides a lot of support for plugins development, including a plugin creator, automatic publishing support, and automatic installation script writer. If you plan on writing more than one plugin, you probably need it.
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();
MyFirstPlugin
, press enter and create the new topic
OUTLINE: Doc Topic Contents
Check the plugins web on TWiki.org for the latest plugin doc topic template. Here's a quick overview of what's covered: Syntax Rules: <Describe any special text formatting that will be rendered.>" Example: <Include an example of the plugin in action. Possibly include a static HTML version of the example to compare if the installation was a success!>" Plugin Settings: <Description and settings for custom plugin %VARIABLES%, and those required by TWiki.>" Plugin Installation Instructions: <Step-by-step set-up guide, user help, whatever it takes to install and run, goes here.>" Plugin Info: <Version, credits, history, requirements - entered in a form, displayed as a table. Both are automatically generated when you create or edit a page in the TWiki:Plugins web.>"
Plugin
, ex: MyFirstPlugin.pm
, and a documentation page with the same name(MyFirstPlugin.txt
).
lib/TWiki/Plugins/MyFirstPlugin.pm
data/TWiki/MyFirstPlugin.txt
pub/TWiki/MyFirstPlugin/uparrow.gif
[a required graphic]
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
MyFirstPlugin
MyFirstPlugin.zip
Dev
, ex: MyFirstPluginDev
. This is the discussion page for future development. (User support for plugins is handled in TWiki:Support.)
TWiki::Func::getWorkArea()
function, which gives you a persistent directory where you can store data files. By default they will not be web accessible. The directory is guaranteed to exist, and to be writable by the webserver user. For convenience, TWiki::Func::storeFile()
and TWiki::Func::readFile()
are provided to persistently store and retrieve simple data in this area.
TWiki::Func::saveAttachment()
function to store the data.
Recommendation for file name: _GaugePlugin_img123.gif
TWiki::Func::saveAttachment()
function to store the data.
Recommendation for file names in plugin attachment area: _Main_roundedge-ul.gif
configure
configure
rather than trying to use TWiki preferences variables. These extensions use Config.spec
files to publish their configuration requirements.
Config.spec
files are read during TWiki configuration. Once a Config.spec
has defined a configuration item, it is available for edit through the standard configure
interface. Config.spec
files are stored in the 'plugin directory' e.g. lib/TWiki/Plugins/BathPlugin/Config.spec
.
Config.spec
file Config.spec
file for an extension starts with the extension announcing what it is:
# ---+ Extensions # ---++ BathPlugin # This plugin senses the level of water in your bath, and ensures the plug # is not removed while the water is still warm.This is followed by one or more configuration items. Each configuration item has a type, a description and a default. For example:
# **SELECT Plastic,Rubber,Metal** # Select the plug type $TWiki::cfg{BathPlugin}{PlugType} = 'Plastic'; # **NUMBER** # Enter the chain length in cm $TWiki::cfg{BathPlugin}{ChainLength} = 30; # **BOOLEAN EXPERT** # Set this option to 0 to disable the water temperature alarm $TWiki::cfg{BathPlugin}{TempSensorEnabled} = 1;The type (e.g.
**SELECT**
) tells configure
to how to prompt for the value. It also tells configure
how to do some basic checking on the value you actually enter. All the comments between the type and the configuration item are taken as part of the description. The configuration item itself defines the default value for the configuration item. The above spec defines the configuration items $TWiki::cfg{BathPlugin}{PlugType}
, $TWiki::cfg{BathPlugin}{ChainLength}
, and $TWiki::cfg{BathPlugin}{TempSensorEnabled}
for use in your plugin. For example,
if( $TWiki::cfg{BathPlugin}{TempSensorEnabled} && $curTemperature > 50 ) { die "The bathwater is too hot for comfort"; }The Config.spec file is read by
configure
, which then writes LocalSite.cfg
with the values chosen by the local site admin.
A range of types are available for use in Config.spec
files:
BOOLEAN | A true/false value, represented as a checkbox |
COMMAND length | A shell command |
LANGUAGE | A language (selected from {LocalesDir} |
NUMBER | A number |
OCTAL | An octal number |
PASSWORD length | A password (input is hidden) |
PATH length | A file path |
PERL | A perl structure, consisting of arrays and hashes |
REGEX length | A perl regular expression |
SELECT choices | Pick one of a range of choices |
SELECTCLASS root | Select a perl package (class) |
STRING length | A string |
URL length | A url |
URLPATH length | A relative URL path |
EXPERT | means this an expert option |
M | means the setting is mandatory (may not be empty) |
H | means the option is not visible in configure |
lib/TWiki.spec
for many more examples.
Config.spec
files for non-plugin extensions are stored under the Contrib
directory instead of the Plugins
directory.
Note that from TWiki 5.0 onwards, CGI scripts (in the TWiki bin
directory) provided by extensions must also have an entry in the Config.spec
file. This entry looks like this (example taken from PublishContrib)
# **PERL H** # Bin script registration - do not modify $TWiki::cfg{SwitchBoard}{publish} = [ "TWiki::Contrib::Publish", "publish", { publishing => 1 } ];
PERL
specifies a perl data structure, and H
a hidden setting (it won't appear in configure
). The first field of the data value specifies the class where the function that implements the script can be found. The second field specifies the name of the function, which must be the same as the name of the script. The third parameter is a hash of initial context settings for the script.
TWiki:TWiki/SpecifyingConfigurationItemsForExtensions has supplemental documentation on configure settings.
Dev
, such as MyFirstPluginDev
. The plugin development topic is a great resource to discuss feature enhancements and to get feedback from the TWiki community.
if( $TWiki::Plugins::VERSION >= 1.1 ) { @webs = TWiki::Func::getListOfWebs( 'user,public' ); } else { @webs = TWiki::Func::getPublicWebList( ); }
TWiki::Plugins
version in which the handler was first deprecated. For example, if we need to define the endRenderingHandler
for compatibility with TWiki::Plugins
versions before 1.1, we would add this to the plugin:
package TWiki::Plugins::SinkPlugin; use vars qw( %TWikiCompatibility ); $TWikiCompatibility{endRenderingHandler} = 1.1;If the currently-running TWiki version is 1.1 or later, then the handler will not be called and the warning will not be issued. TWiki with versions of
TWiki::Plugins
before 1.1 will still call the handler as required.
Back to top
%PLUGINVERSION%
TWiki variable, and accessed in code using
$TWiki::Plugins::VERSION
. The 'Since' field in the function
documentation refers to $TWiki::Plugins::VERSION
.
Notes on use of $TWiki::Plugins::VERSION
(from 1.2 forwards):
1.
) is the same then any plugin coded to use any earlier revision of the 1.
API will still work. No function has been removed from the interface, nor has any API published in that version changed in such a way as to require plugins to be recoded.
TWiki::Plugins::VERSION
also applies to the plugin handlers. The handlers are documented in the EmptyPlugin, and that module indicates what version of TWiki::Plugins::VERSION
it relates to.
SKIN
and COVER
preferences variables or the skin
and cover
CGI parameters
Return: $skin
Comma-separated list of skins, e.g. 'gnu,tartan'
. Empty string if none.
Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
$host
URL host, e.g. "http://example.com:80"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web
- Web name, e.g. 'Main'
$topic
- Topic name, e.g. 'WebNotify'
$script
- Script name, e.g. 'view'
...
- an arbitrary number of name=>value parameter pairs that will be url-encoded and added to the url. The special parameter name '#' is reserved for specifying an anchor. e.g. getScriptUrl('x','y','view','#'=>'XXX',a=>1,b=>2) will give .../view/x/y?a=1&b=2#XXX
$url
URL, e.g. "http://example.com:80/cgi-bin/view.pl/Main/WebNotify"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web
- Web name, e.g. 'Main'
. The current web is taken if empty
$topic
- Topic name, e.g. 'WebNotify'
$url
URL, e.g. "http://example.com:80/cgi-bin/view.pl/Main/WebNotify"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$path
URL path of pub directory, e.g. "/pub"
Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
https
if the LWP
CPAN module is
installed.
Note that the $url
may have an optional user and password, as specified by
the relevant RFC. Any proxy set in configure
is honoured.
The $response
is an object that is known to implement the following subset of
the methods of LWP::Response
. It may in fact be an LWP::Response
object,
but it may also not be if LWP
is not available, so callers may only assume
the following subset of methods is available:
code() |
message() |
header($field) |
content() |
is_error() |
is_redirect() |
require LWP
.
is_error()
will return
true, code()
will return a valid HTTP status code
as specified in RFC 2616 and RFC 2518, and message()
will return the
message that was received from
the server. In the event of a client-side error (e.g. an unparseable URL)
then is_error()
will return true and message()
will return an explanatory
message. code()
will return 400 (BAD REQUEST).
Note: Callers can easily check the availability of other HTTP::Response methods
as follows:
my $response = TWiki::Func::getExternalResource($url); if (!$response->is_error() && $response->isa('HTTP::Response')) { ... other methods of HTTP::Response may be called } else { ... only the methods listed above may be called }Since: TWiki::Plugins::VERSION 1.2
$query
CGI query object; or 0 if script is called as a shell script
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
setSessionValue
and
getSessionValue
.
Since: TWiki::Plugins::VERSION 1.2
$key
- Session key
$value
Value associated with key; empty string if not set
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 200)
$key
- Session key
$value
- Value associated with key
setSessionValue
. $key
- name of value stored in session to be cleared. Note that you cannot clear AUTHUSER
.
sub initPlugin { TWiki::Func::getContext()->{'MyID'} = 1; ...This can be used in SecondPlugin.pm like this:
sub initPlugin { if( TWiki::Func::getContext()->{'MyID'} ) { ... } ...or in a template, like this:
%TMPL:DEF{"ON"}% Not off %TMPL:END% %TMPL:DEF{"OFF"}% Not on %TMPL:END% %TMPL:P{context="MyID" then="ON" else="OFF"}%or in a topic:
%IF{"context MyID" then="MyID is ON" else="MyID is OFF"}%Note: all plugins have an automatically generated context identifier if they are installed and initialised. For example, if the FirstPlugin is working, the context ID 'FirstPlugin' will be set. Since: TWiki::Plugins::VERSION 1.1
$web
- new web
$topic
- new topic
$web.$topic
from now on. All the preferences will be reset to those of the new topic.
Note that if the new topic is not readable by the logged in user due to
access control considerations, there will not be an exception. It is the
duty of the caller to check access permissions before changing the topic.
It is the duty of the caller to restore the original context by calling
popTopicContext
.
Note that this call does not re-initialise plugins, so if you have used
global variables to remember the web and topic in initPlugin
, then those
values will be unchanged.
Since: TWiki::Plugins::VERSION 1.2
pushTopicContext
was called.
Since: TWiki::Plugins::VERSION 1.2
$key
- Preferences key
$web
- Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
$value
Preferences value; empty string if not set
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
* Set COLOR = red
"MYPLUGIN_COLOR"
for $key
my $color = TWiki::Func::getPreferencesValue( "MYPLUGIN_COLOR" );
* Set WEBBGCOLOR = #FFFFC0
my $webColor = TWiki::Func::getPreferencesValue( 'WEBBGCOLOR', 'Sandbox' );
$NO_PREFS_IN_TOPIC
is enabled in the plugin, then
preferences set in the plugin topic will be ignored.
$key
- Plugin Preferences key w/o PLUGINNAME_ prefix.
$value
Preferences value; empty string if not set
Note: This function will will only work when called from the Plugin.pm file itself. it will not work if called from a sub-package (e.g. TWiki::Plugins::MyPlugin::MyModule)
Since: TWiki::Plugins::VERSION 1.021 (27 Mar 2004)
NOTE: As of TWiki4.1, if $NO_PREFS_IN_TOPIC
is enabled in the plugin, then
preferences set in the plugin topic will be ignored.
$key
- Preferences key
$web
- Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
$value
Preferences flag '1'
(if set), or "0"
(for preferences values "off"
, "no"
and "0"
)
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
* Set SHOWHELP = off
"MYPLUGIN_SHOWHELP"
for $key
my $showHelp = TWiki::Func::getPreferencesFlag( "MYPLUGIN_SHOWHELP" );
$NO_PREFS_IN_TOPIC
is enabled in the plugin, then
preferences set in the plugin topic will be ignored.
$key
- Plugin Preferences key w/o PLUGINNAME_ prefix.
"off"
, "no"
and "0"
, or values not set at all. True otherwise.
Note: This function will will only work when called from the Plugin.pm file itself. it will not work if called from a sub-package (e.g. TWiki::Plugins::MyPlugin::MyModule)
Since: TWiki::Plugins::VERSION 1.021 (27 Mar 2004)
NOTE: As of TWiki4.1, if $NO_PREFS_IN_TOPIC
is enabled in the plugin, then
preferences set in the plugin topic will be ignored.
%$name%
will expand to the preference when used in
future variable expansions.
The preference only persists for the rest of this request. Finalised
preferences cannot be redefined using this function.
Returns 1 if the preference was defined, and 0 otherwise.
$name
Name of tool, e.g. 'TWiki'
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
$name
Name, e.g. 'Main'
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
$name
Name, e.g. 'TWiki'
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
DefaultUserLogin
Return: $loginName
Default user name, e.g. 'guest'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$user
can be a login, wikiname or web.wikiname
$cUID
, an internal unique and portable escaped identifier for
registered users. This may be autogenerated for an authenticated but
unregistered user.
Since: TWiki::Plugins::VERSION 1.2
$wikiName
Wiki Name, e.g. 'JohnDoe'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$wikiName
Wiki Name, e.g. "Main.JohnDoe"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$id
- Wiki name, e.g. 'Main.JohnDoe'
or 'JohnDoe'
. Since TWiki 4.2.1, $id may also be a login name. This will normally be transparent, but should be borne in mind if you have login names that are also legal wiki names.
$loginName
Login name of user, e.g. 'jdoe'
, or undef if not
matched.
Note that it is possible for several login names to map to the same wikiname.
This function will only return the first login name that maps to the
wikiname.
returns undef if the WikiName is not found.
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$loginName
- Login name, e.g. 'jdoe'
. Since TWiki 4.2.1 this may also be a wiki name. This will normally be transparent, but may be relevant if you have login names that are also valid wiki names.
$dontAddWeb
- Do not add web prefix if "1"
$wikiName
Wiki name of user, e.g. 'Main.JohnDoe'
or 'JohnDoe'
userToWikiName will always return a name. If the user does not
exist in the mapping, the $loginName parameter is returned. (backward compatibility)
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$email
- email address to look up
$dontAddWeb
- Do not add web prefix if "1"
$user
- wikiname of user to look up
if( TWiki::Func::isGroupMember( "HesperionXXGroup", "jordi" )) { ... }If
$user
is undef
, it defaults to the currently logged-in user.
my $iterator = TWiki::Func::eachUser(); while ($it->hasNext()) { my $user = $it->next(); # $user is a wikiname }WARNING on large sites, this could be a long list! Since: TWiki::Plugins::VERSION 1.2
$id
- WikiName or login name of the user. If $id
is undef
, defaults to the currently logged-in user.
my $iterator = TWiki::Func::eachGroup(); while ($it->hasNext()) { my $group = $it->next(); # $group is a group name e.g. TWikiAdminGroup }WARNING on large sites, this could be a long list! Since: TWiki::Plugins::VERSION 1.2
$group
is the name of a group known to TWiki.
my $iterator = TWiki::Func::eachGroupMember('RadioheadGroup'); while ($it->hasNext()) { my $user = $it->next(); # $user is a wiki name e.g. 'TomYorke', 'PhilSelway' }WARNING on large sites, this could be a long list! Since: TWiki::Plugins::VERSION 1.2
$type
- Access type, required, e.g. 'VIEW'
, 'CHANGE'
.
$id
- WikiName of remote user, required, e.g. "PeterThoeny"
. From TWiki 4.2.1, $id may also be a login name. If $id
is '', 0 or undef
then access is always permitted.
$text
- Topic text, optional. If 'perl false' (undef, 0 or ''), topic $web.$topic
is consulted. $text
may optionally contain embedded %META:PREFERENCE
tags. Provide this parameter if: $meta
parameter.
$topic
- Topic name, required, e.g. 'PrivateStuff'
$web
- Web name, required, e.g. 'Sandbox'
$meta
- Meta-data object, as returned by readTopic
. Optional. If undef
, but $text
is defined, then access controls will be parsed from $text
. If defined, then metadata embedded in $text
will be ignored. This parameter is always ignored if $text
is undefined. Settings in $meta
override Set
settings in $text.
ThatWeb.ThisTopic
, then a call to checkAccessPermission('SPIN', 'IncyWincy', undef, 'ThisTopic', 'ThatWeb', undef)
will return true
.
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
$filter
- spec of web types to recover
$filter
may also contain the word 'public' which will further filter
out webs that have NOSEARCHALL set on them.
'allowed' filters out webs the current user can't read.
For example, the deprecated getPublicWebList function can be duplicated
as follows:
my @webs = TWiki::Func::getListOfWebs( "user,public" );Since: TWiki::Plugins::VERSION 1.1
$web
- Web name, required, e.g. 'Sandbox'
$name
- web name
$templateWeb
- flag, optional. If true, then template web names (starting with _) are considered valid, otherwise only user web names are valid.
$newWeb
is the name of the new web.
$baseWeb
is the name of an existing web (a template web). If the base web is a system web, all topics in it will be copied into the new web. If it is a normal web, only topics starting with 'Web' will be copied. If no base web is specified, an empty web (with no topics) will be created. If it is specified but does not exist, an error will be thrown.
$opts
is a ref to a hash that contains settings to be modified in
use Error qw( :try ); use TWiki::AccessControlException; try { TWiki::Func::createWeb( "Newweb" ); } catch Error::Simple with { my $e = shift; # see documentation on Error::Simple } catch TWiki::AccessControlException with { my $e = shift; # see documentation on TWiki::AccessControlException } otherwise { ... };Since: TWiki::Plugins::VERSION 1.1
use Error qw( :try ); use TWiki::AccessControlException; try { TWiki::Func::moveWeb( "Oldweb", "Newweb" ); } catch Error::Simple with { my $e = shift; # see documentation on Error::Simple } catch TWiki::AccessControlException with { my $e = shift; # see documentation on TWiki::AccessControlException } otherwise { ... };To delete a web, move it to a subweb of
Trash
TWiki::Func::moveWeb( "Deadweb", "Trash.Deadweb" );Since: TWiki::Plugins::VERSION 1.1
$time
and now. $time is a time in seconds since 1st Jan 1970, and is not
guaranteed to return any changes that occurred before (now -
{Store}{RememberChangesFor}). {Store}{RememberChangesFor}) is a
setting in configure
. Changes are returned in most-recent-first
order.
Use it as follows:
my $iterator = TWiki::Func::eachChangeSince( $web, time() - 7 * 24 * 60 * 60); # the last 7 days while ($iterator->hasNext()) { my $change = $iterator->next(); # $change is a perl hash that contains the following fields: # topic => topic name # user => wikiname - wikiname of user who made the change # time => time of the change # revision => revision number *after* the change # more => more info about the change (e.g. 'minor') }
$web
- Web name, required, e.g. 'Sandbox'
@topics
Topic list, e.g. ( 'WebChanges', 'WebHome', 'WebIndex', 'WebNotify' )
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web
- Web name, optional, e.g. 'Main'
.
$topic
- Topic name, required, e.g. 'TokyoOffice'
, or "Main.TokyoOffice"
normalizeWebTopicName
.
Specifically, the Main is used if $web is not specified and $topic has no web specifier.
To get an expected behaviour it is recommened to specify the current web for $web; don't leave it empty.
Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
$name
- topic name
$web
Web name, e.g. "Main"
, or empty
$topic
Topic name, e.g. "MyTopic"
, or "Main.MyTopic"
( $oopsUrl, $loginName, $unlockTime )
- The $oopsUrl
for calling redirectCgiQuery(), user's $loginName
, and estimated $unlockTime
in minutes, or ( '', '', 0 ) if no lease exists. $script
The script to invoke when continuing with the edit
$web
Web name, e.g. "Main"
, or empty
$topic
Topic name, e.g. "MyTopic"
, or "Main.MyTopic"
$lock
1 to lease the topic, 0 to clear an existing lease
edit
script
always takes out a lease.
It is impossible to fully lock a topic. Concurrent changes will be
merged.
Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
$web
- web for the topic
$topic
- topic name
$meta
- reference to TWiki::Meta object
$text
- text of the topic (without embedded meta-data!!!
\%options
- ref to hash of save options \%options
may include: dontlog | don't log this change in twiki log |
forcenewrevision | force the save to increment the revision counter |
minor | True if this is a minor change, and is not to be notified |
# read topic: my( $topicMeta, $topicText ) = TWiki::Func::readTopic( $web, $topic ) # example to change topic text: $topicText =~ s/APPLE/ORANGE/g; # example to change TWiki form field: my $field = $topicMeta->get( 'FIELD', 'Title' ); if( $field ) { $field->{value} = $newTitle; $topicMeta->putKeyed( 'FIELD', $field ); } # save updated topic: TWiki::Func::saveTopic( $web, $topic, $topicMeta, $topicText, { forcenewrevision => 1 } );Note: Plugins handlers ( e.g.
beforeSaveHandler
) will be called as
appropriate.
$web
- Web name, e.g. 'Main'
, or empty
$topic
- Topic name, e.g. 'MyTopic'
, or "Main.MyTopic"
$text
- Topic text to save, assumed to include meta data
$ignorePermissions
- Set to "1"
if checkAccessPermission() is already performed and OK
$dontNotify
- Set to "1"
if not to notify users of the change
$oopsUrl
Empty string if OK; the $oopsUrl
for calling redirectCgiQuery() in case of error
This method is a lot less efficient and much more dangerous than saveTopic
.
Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
my $text = TWiki::Func::readTopicText( $web, $topic ); # 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
$web
source web - required
$topic
source topic - required
$newWeb
dest web
$newTopic
dest topic
use Error qw( :try ); try { moveTopic( "Work", "TokyoOffice", "Trash", "ClosedOffice" ); } catch Error::Simple with { my $e = shift; # see documentation on Error::Simple } catch TWiki::AccessControlException with { my $e = shift; # see documentation on TWiki::AccessControlException } otherwise { ... };
$web
- Web name, optional, e.g. 'Main'
$topic
- Topic name, required, e.g. 'TokyoOffice'
$rev
- revsion number, or tag name (can be in the format 1.2, or just the minor number)
$attachment
-attachment filename
( $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 | Wiki name of the author (not login name) |
$rev | actual rev number |
$comment | WHAT COMMENT? |
$meta->getRevisionInfo
instead if you can - it is significantly
more efficient.
Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
$web
- web for topic
$topic
- topic
$time
- time (in epoch secs) for the rev
$web
- Web name, required, e.g. 'Main'
$topic
- Topic name, required, e.g. 'TokyoOffice'
$rev
- revision to read (default latest)
( $meta, $text )
Meta data object and topic text
$meta
is a perl 'object' of class TWiki::Meta
. This class is
fully documented in the source code documentation shipped with the
release, or can be inspected in the lib/TWiki/Meta.pm
file.
This method ignores topic access permissions. You should be careful to use
checkAccessPermission
to ensure the current user has read access to the
topic.
See usage example at TWiki::Func::saveTopic.
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web
- Web name, e.g. 'Main'
, or empty
$topic
- Topic name, e.g. 'MyTopic'
, or "Main.MyTopic"
$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.
$ignorePermissions
- Set to "1"
if checkAccessPermission() is already performed and OK; an oops URL is returned if user has no permission
$text
Topic text with embedded meta data; an oops URL for calling redirectCgiQuery() is returned in case of an error
This method is more efficient than readTopic
, but returns meta-data embedded in the text. Plugins authors must be very careful to avoid damaging meta-data. You are recommended to use readTopic instead, which is a lot safer.
Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
$web
- Web name, optional, e.g. Main
.
$topic
- Topic name, required, e.g. TokyoOffice
, or Main.TokyoOffice
$attachment
- attachment name, e.g. logo.gif
normalizeWebTopicName
.
Since: TWiki::Plugins::VERSION 1.1
$web
- web for topic
$topic
- topic
$name
- attachment name
$rev
- revision to read (default latest)
readTopic
. If the attachment does not exist, or cannot be read, undef
will be returned. If the revision is not specified, the latest version will
be returned.
View permission on the topic is required for the
read to be successful. Access control violations are flagged by a
TWiki::AccessControlException. Permissions are checked for the current user.
my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic ); my @attachments = $meta->find( 'FILEATTACHMENT' ); foreach my $a ( @attachments ) { try { my $data = TWiki::Func::readAttachment( $web, $topic, $a->{name} ); ... } catch TWiki::AccessControlException with { }; }Since: TWiki::Plugins::VERSION 1.1
$web
- web for topic
$topic
- topic to atach to
$attachment
- name of the attachment
$opts
- Ref to hash of options
$opts
may include:
dontlog |
don't log this change in twiki log |
comment |
comment for save |
hide |
if the attachment is to be hidden in normal topic view |
stream |
Stream of file to upload |
file |
Name of a file to use for the attachment data. ignored if stream is set. Local file on the server. |
filepath |
Client path to file |
filesize |
Size of uploaded data |
filedate |
Date |
try { TWiki::Func::saveAttachment( $web, $topic, 'image.gif', { file => 'image.gif', comment => 'Picture of Health', hide => 1 } ); } catch Error::Simple with { # see documentation on Error } otherwise { ... };Since: TWiki::Plugins::VERSION 1.1
$web
source web - required
$topic
source topic - required
$attachment
source attachment - required
$newWeb
dest web
$newTopic
dest topic
$newAttachment
dest attachment
use Error qw( :try ); try { # move attachment between topics moveAttachment( "Countries", "Germany", "AlsaceLorraine.dat", "Countries", "France" ); # Note destination attachment name is defaulted to the same as source } catch TWiki::AccessControlException with { my $e = shift; # see documentation on TWiki::AccessControlException } catch Error::Simple with { my $e = shift; # see documentation on Error::Simple };Since: TWiki::Plugins::VERSION 1.1
$name
- Template name, e.g. 'view'
$skin
- Comma-separated list of skin names, optional, e.g. 'print'
$text
Template text
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$name
- template file name
$skin
- comma-separated list of skins to use (default: current skin)
$web
- the web to look in for topics that contain templates (default: current web)
$def
- template name
$query
and $contentLength
parameters. Both were marked "you should not pass this parameter".
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$query
- CGI query object. Ignored, only there for compatibility. The session CGI query object is used instead.
$url
- URL to redirect to
$passthru
- enable passthrough.
$passthru
parameter allows you to pass the parameters that were passed
to the current query on to the target URL, as long as it is another URL on the
same TWiki installation. If $passthru
is set to a true value, then TWiki
will save the current URL parameters, and then try to restore them on the
other side of the redirect. Parameters are stored on the server in a cache
file.
Note that if $passthru
is set, then any parameters in $url
will be lost
when the old parameters are restored. if you want to change any parameter
values, you will need to do that in the current CGI query before redirecting
e.g.
my $query = TWiki::Func::getCgiQuery(); $query->param(-name => 'text', -value => 'Different text'); TWiki::Func::redirectCgiQuery( undef, TWiki::Func::getScriptUrl($web, $topic, 'edit'), 1);
$passthru
does nothing if $url
does not point to a script in the current
TWiki installation.
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$header
to the HTML header (the tag).
This is useful for Plugins that want to include some javascript custom css. $id
- Unique ID to prevent the same HTML from being duplicated. Plugins should use a prefix to prevent name clashes (e.g EDITTABLEPLUGIN_JSCALENDAR)
$header
- the HTML to be added to the section. The HTML must be valid in a HEAD tag - no checks are performed.
requires
optional, comma-separated list of id's of other head blocks this one depends on.
$header
will be expanded before being inserted into the
section.
Note that this is not the same as the HTTP header, which is modified through the Plugins modifyHeaderHandler
.
Since: TWiki::Plugins::VERSION 1.1
example:
TWiki::Func::addToHEAD('PATTERN_STYLE','<link id="twikiLayoutCss" rel="stylesheet" type="text/css" href="%PUBURL%/TWiki/PatternSkin/layout.css" media="all" />');
%VARIABLES%
$text
- Text with variables to expand, e.g. 'Current user is %WIKIUSER%'
$topic
- Current topic name, e.g. 'WebNotify'
$web
- Web name, optional, e.g. 'Main'
. The current web is taken if missing
$meta
- topic meta-data to use while expanding (Since TWiki::Plugins::VERSION 1.2)
$text
Expanded text, e.g. 'Current user is TWikiGuest'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
See also: expandVariablesOnTopicCreation
$text
- Text to render, e.g. '*bold* text and =fixed font='
$web
- Web name, optional, e.g. 'Main'
. The current web is taken if missing
$text
XHTML text, e.g. '<b>bold</b> and <code>fixed font</code>'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
renderText()
$pre
- Text occuring before the TWiki link syntax, optional
$web
- Web name, required, e.g. 'Main'
$topic
- Topic name to link to, required, e.g. 'WebNotify'
$label
- Link label, required. Usually the same as $topic
, e.g. 'notify'
$anchor
- Anchor, optional, e.g. '#Jump'
$createLink
- Set to '1'
to add question linked mark after topic name if topic does not exist;'0'
to suppress link for non-existing topics
$text
XHTML anchor, e.g. '<a href='/cgi-bin/view/Main/WebNotify#Jump'>notify</a>'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$text
- text of the mail, including MIME headers
$retries
- number of times to retry the send (default 1)
To: liz@windsor.gov.uk From: serf@hovel.net CC: george@whitehouse.gov Subject: Revolution Dear Liz, Please abolish the monarchy (with King George's permission, of course) Thanks, A. PeasantLeave a blank line between the last header field and the message body. Since: TWiki::Plugins::VERSION 1.1
$wikiname
- wiki name of the user
$text
- the text to process
%DATE%
Signature-format date
%SERVERTIME%
See TWikiVariables
%GMTIME%
See TWikiVariables
%USERNAME%
Base login name
%WIKINAME%
Wiki name
%WIKIUSERNAME%
Wiki name with prepended web
%URLPARAM{...}%
- Parameters to the current CGI query
%NOP%
No-op
commonTagsHandler
. $var
- The name of the variable, i.e. the 'MYVAR' part of %MYVAR%. The variable name must match /^[A-Z][A-Z0-9_]*$/ or it won't work.
\&fn
- Reference to the handler function.
$syntax
can be 'classic' (the default) or 'context-free'. 'classic' syntax is appropriate where you want the variable to support classic TWiki syntax i.e. to accept the standard %MYVAR{ "unnamed" param1="value1" param2="value2" }%
syntax, as well as an unquoted default parameter, such as %MYVAR{unquoted parameter}%
. If your variable will only use named parameters, you can use 'context-free' syntax, which supports a more relaxed syntax. For example, %MYVAR{param1=value1, value 2, param3="value 3", param4='value 5"}%
sub handler(\%session, \%params, $topic, $web)where:
\%session
- a reference to the TWiki session object (may be ignored)
\%params
- a reference to a TWiki::Attrs object containing parameters. This can be used as a simple hash that maps parameter names to values, with _DEFAULT being the name for the default parameter.
$topic
- name of the topic in the query
$web
- name of the web in the query
$meta
- topic meta-data to use while expanding, can be undef (Since TWiki::Plugins::VERSION 1.4)
$textRef
- reference to unexpanded topic text, can be undef (Since TWiki::Plugins::VERSION 1.4)
sub initPlugin{ TWiki::Func::registerTagHandler('EXEC', \&boo); } sub boo { my( $session, $params, $topic, $web ) = @_; my $cmd = $params->{_DEFAULT}; return "NO COMMAND SPECIFIED" unless $cmd; my $result = `$cmd 2>&1`; return $params->{silent} ? '' : $result; }would let you do this:
%EXEC{"ps -Af" silent="on"}%
Registered tags differ from tags implemented using the old TWiki approach (text substitution in commonTagsHandler
) in the following ways: commonTagsHandler
is only called later, when all system tags have already been expanded (though they are expanded again after commonTagsHandler
returns).
FRED
defines both %FRED{...}%
and also %FRED%
.
return '%SERVERTIME%';
). It won't work.
$alias
- The name .
\&fn
- Reference to the function.
sub handler(\%session)where:
\%session
- a reference to the TWiki session object (may be ignored)
TWiki::Func::registerRESTHandler('example', \&restExample);This adds the
restExample
function to the REST dispatch table
for the EmptyPlugin under the 'example' alias, and allows it
to be invoked using the URL
http://server:port/bin/rest/EmptyPlugin/example
note that the URL
http://server:port/bin/rest/EmptyPlugin/restExample
(ie, with the name of the function instead of the alias) will not work.
format
parameters that are used to block evaluation of paramater strings.
For example, if you were to write
%MYTAG{format="%WURBLE%"}%
then %WURBLE would be expanded before %MYTAG is evaluated. To avoid
this TWiki uses escapes in the format string. For example:
%MYTAG{format="$percntWURBLE$percnt"}%
This lets you enter arbitrary strings into parameters without worrying that
TWiki will expand them before your plugin gets a chance to deal with them
properly. Once you have processed your tag, you will want to expand these
tokens to their proper value. That's what this function does.
Escape: | Expands To: |
---|---|
$n or $n() |
New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() |
Is a "no operation". |
$quot |
Double quote (" ) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
$searchString
- the search string, in egrep format
$web
- The web to search in
\@topics
- reference to a list of topics to search
\%option
- reference to an options hash
\%options
hash may contain the following options: type
- if regex
will perform a egrep-syntax RE search (default '')
casesensitive
- false to ignore case (default true)
files_without_match
- true to return files only (default false). If files_without_match
is specified, it will return on the first match in each topic (i.e. it will return only one match per topic, and will not return matching lines).
my $result = TWiki::Func::searchInWebContent( "Slimy Toad", $web, \@topics, { casesensitive => 0, files_without_match => 0 } ); foreach my $topic (keys %$result ) { foreach my $matching_line ( @{$result->{$topic}} ) { ...etcSince: TWiki::Plugins::VERSION 1.1
$filename
- Full path name of file
$text
Content of file, empty if not found
NOTE: Use this function only for the Plugin workarea, not for topics and attachments. Use the appropriate functions to manipulate topics and attachments.
Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
$filename
- Full path name of file
$text
- Text to save
$name
- Name of the expression to retrieve. See notes below
my $upper = TWiki::Func::getRegularExpression('upperAlpha'); my $alpha = TWiki::Func::getRegularExpression('mixedAlpha'); my $capitalized = qr/[$upper][$alpha]+/;Those expressions marked type 'RE' are precompiled regular expressions that can be used outside square brackets. For example:
my $webRE = TWiki::Func::getRegularExpression('webNameRegex'); my $isWebName = ( $s =~ m/$webRE/ );
Name | Matches | Type |
---|---|---|
upperAlpha | Upper case characters | String |
upperAlphaNum | Upper case characters and digits | String |
lowerAlpha | Lower case characters | String |
lowerAlphaNum | Lower case characters and digits | String |
numeric | Digits | String |
mixedAlpha | Alphabetic characters | String |
mixedAlphaNum | Alphanumeric characters | String |
wikiWordRegex | WikiWords | RE |
webNameRegex | User web names | RE |
anchorRegex | #AnchorNames | RE |
abbrevRegex | Abbreviations e.g. GOV, IRS | RE |
emailAddrRegex | email@address.com | RE |
tagNameRegex | Standard variable names e.g. %THIS_BIT% (THIS_BIT only) | RE |
$web
- Web name, identifying variable, or empty string
$topic
- Topic name, may be a web.topic string, required.
Input | Return |
---|---|
( 'Web', 'Topic' ) | ( 'Web', 'Topic' ) |
( '', 'Topic' ) | ( 'Main', 'Topic' ) |
( '', '' ) | ( 'Main', 'WebHome' ) |
( '', 'Web/Topic' ) | ( 'Web', 'Topic' ) |
( '', 'Web/Subweb/Topic' ) | ( 'Web/Subweb', 'Topic' ) |
( '', 'Web.Topic' ) | ( 'Web', 'Topic' ) |
( '', 'Web.Subweb.Topic' ) | ( 'Web/Subweb', 'Topic' ) |
( 'Web1', 'Web2.Topic' ) | ( 'Web2', 'Topic' ) |
configure
.
The symbols %USERSWEB%, %SYSTEMWEB% and %DOCWEB% can be used in the input to represent the web names set in $cfg{UsersWebName} and $cfg{SystemWebName}. For example:
Input | Return |
---|---|
( '%USERSWEB%', 'Topic' ) | ( 'Main', 'Topic' ) |
( '%SYSTEMWEB%', 'Topic' ) | ( 'TWiki', 'Topic' ) |
( '', '%DOCWEB%.Topic' ) | ( 'TWiki', 'Topic' ) |
$pre
- Arbitrary Text
$text
Since: TWiki::Plugins::VERSION 1.3 (18 Jan 2010)
$text
- Text to write; timestamp gets added
$text
- Text to write; timestamp gets added
$action
- name of the event, such as 'blacklist'
.
$extra
- arbitrary extra information to add to the event.
$web
- web name, optional. Base web is taken if empty. Ignored if web is specified in $topic
.
$topic
- topic name, optional. Can be Topic
or Web.Topic
. Base topic is taken if empty.
$user
- WikiName of user, optional. Name of logged-in user is taken if not specified.
TWiki::Func::writeLog( 'blacklist', 'Magic number is missing' )
will add a log entry like this:
| 2011-01-19 - 01:13 | guest | blacklist | TWiki.TWikiRegistration | Magic number is missing | 1.2.3.4 |Note: Older plugins that use
$TWiki::cfg{LogFileName}
or call the internal TWiki
function directly should be fixed to use writeLog
.
To maintain compatibility with older TWiki releases, you can write conditional code as follows:
if( defined &TWiki::Func::writeLog ) { # use writeLog TWiki::Func::writeLog( $web, $topic, 'myevent', $extra ); } else { # deprecated code if plugin is used in older TWiki releases $TWiki::Plugins::VERSION > 1.1 ? $TWiki::Plugins::SESSION->writeLog( 'myevent', "$web.$topic", $extra ) : TWiki::Store::writeLog( 'myevent', "$web.$topic", $extra ); }
$time
- Time in epoc seconds
$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'
), or any string with tokens '$seconds, $minutes, $hours, $day, $wday, $month, $mo, $year, $ye, $tz'
for seconds, minutes, hours, day of month, day of week, 3 letter month, 2 digit month, 4 digit year, 2 digit year, timezone string, respectively
$timezone
- either not defined (uses the displaytime setting), 'gmtime', or 'servertime'
$text
Formatted time string
Note: | if you used the removed formatGmTime, add a third parameter 'gmtime' |
$value
is true, and 0 otherwise. "true" means set to
something with a Perl true value, with the special cases that "off",
"false" and "no" (case insensitive) are forced to false. Leading and
trailing spaces in $value
are ignored.
If the value is undef, then $default
is returned. If $default
is
not specified it is taken as 0.
Since: TWiki::Plugins::VERSION 1.2
$text
- Word to test
$attr
- Attribute string
%params
Hash containing all parameters. The nameless parameter is stored in key _DEFAULT
Since: TWiki::Plugins::VERSION 1.025 (26 Aug 2004)
%TEST{ 'nameless' name1="val1" name2="val2" }%
{...}
to get: 'nameless' name1="val1" name2="val2"
%params
hash contains now: _DEFAULT => 'nameless'
name1 => "val1"
name2 => "val2"
$attr
- Attribute string
$name
- Name, optional
$value
Extracted value
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
%TEST{ 'nameless' name1="val1" name2="val2" }%
{...}
to get: 'nameless' name1="val1" name2="val2"
my $noname = TWiki::Func::extractNameValuePair( $text );
my $val1 = TWiki::Func::extractNameValuePair( $text, "name1" );
my $val2 = TWiki::Func::extractNameValuePair( $text, "name2" );
TWiki::Plugins
version in which the handler was first deprecated. For example, if we need to define the endRenderingHandler
for compatibility with TWiki::Plugins
versions before 1.1, we would add this to the plugin:
package TWiki::Plugins::SinkPlugin; use vars qw( %TWikiCompatibility ); $TWikiCompatibility{endRenderingHandler} = 1.1;If the currently-running TWiki version is 1.1 or later, then the handler will not be called and the warning will not be issued. TWiki with versions of
TWiki::Plugins
before 1.1 will still call the handler as required.
The following functions are retained for compatibility only. You should
stop using them as soon as possible.
getScriptUrl
instead.
Return: $path
URL path of TWiki scripts, e.g. "/cgi-bin"
WARNING: you are strongly recommended not to use this function, as the
{ScriptUrlPaths} URL rewriting rules will not apply to urls generated
using it.
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web
- Web name, e.g. 'Main'
. The current web is taken if empty
$topic
- Topic name, e.g. 'WebNotify'
$template
- Oops template name, e.g. 'oopsmistake'
. The 'oops' is optional; 'mistake' will translate to 'oopsmistake'.
$param1
... $param4
- Parameter values for %PARAM1% ... %PARAMn% variables in template, optional
$url
URL, e.g. "http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked¶m1=joe"
DEPRECATED since 1.1, the recommended approach is to throw an oops exception.
use Error qw( :try ); throw TWiki::OopsException( 'toestuckerror', web => $web, topic => $topic, params => [ 'I got my toe stuck' ]);(this example will use the
oopstoestuckerror
template.)
If this is not possible (e.g. in a REST handler that does not trap the exception)
then you can use getScriptUrl
instead:
my $url = TWiki::Func::getScriptUrl($web, $topic, 'oops', template => 'oopstoestuckerror', param1 => 'I got my toe stuck'); TWiki::Func::redirectCgiQuery( undef, $url ); return 0;Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web
- Web name, required, e.g. 'Sandbox'
getPreferencesValue
instead to determine
what permissions are set on the web, for example:
foreach my $type ( 'ALLOW', 'DENY' ) { foreach my $action ( 'CHANGE', 'VIEW' ) { my $pref = $type . 'WEB' . $action; my $val = getPreferencesValue( $pref, $web ) || ''; if( $val =~ /\S/ ) { print "$pref is set to $val on $web\n"; } } }
getListOfWebs
instead.
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 (07 Dec 2002)
formatTime
instead.
Format the time to GM time $time
- Time in epoc seconds
$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'
)
$text
Formatted time string
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$dir
Data directory, e.g. '/twiki/data'
This function violates store encapsulation and is therefore deprecated.
Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
$dir/Web/TopicName
Return: $dir
Pub directory, e.g. '/htdocs/twiki/pub'
This function violates store encapsulation and is therefore deprecated.
Use readAttachment
and saveAttachment
instead.
Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
commonTagsHandler($text, $topic, $web)
endRenderingHandler($text)
outsidePREHandler($text)
insidePREHandler($text)
startRenderingHandler($text, $web)
checkAccessPermission($type, $login, $topicText, $topicName, $webName) -> $boolean
expandCommonVariables($text, $topic, $web) -> $text
extractNameValuePair($attrs, $name) -> $value
formatGmTime($time) -> $text
getCgiQuery() -> $query
getDataDir() -> $dir
getDefaultUserName() -> $loginName
getMainWebname() -> $name
getOopsUrl($web, $topic, $template, @theParams) -> $url
getPreferencesFlag($key) -> $boolean
getPreferencesValue($key, $web) -> $value
getPublicWebList() -> @webs
getPubDir() -> $dir
getPubUrlPath() -> $path
getRevisionInfo($webName, $topic, $rev, $attachment) -> ($date, $user, $rev, $comment)
getScriptUrl($web, $topic, $script) -> $url
getScriptUrlPath() -> $path
getSessionValue($key) -> $value
getSkin() -> $skin
getTopicList($web) -> @topics
getTwikiWebname() -> $name
getUrlHost() -> $host
getViewUrl($web, $topic) -> $url
getWikiName() -> $wikiName
getWikiUserName($text) -> $wikiName
getWikiToolName() -> $name
internalLink($preamble, $web, $topic, $linkText, $anchor, $createLink) -> $text
isGuest() -> $boolean
permissionsSet($web) -> $boolean
readFile($filename) -> $text
readTemplate($name, $skin) -> $text
readTopic($webName, $topic) -> ($meta, $text)
redirectCgiQuery($query, $url)
renderText($text, $web) -> $text
saveFile($filename, $text)
setSessionValue($key, $value)
topicExists($web, $topic) -> $boolean
userToWikiName($user, $dontAddWeb) -> $wikiName
webExists($web) -> $boolean
wikiToUserName($wiki) -> $loginName
writeDebug($text)
writeHeader()
writeWarning($text)
afterEditHandler($text, $topic, $web)
beforeEditHandler($text, $topic, $web)
beforeSaveHandler($text, $topic, $web)
initializeUserHandler($loginName, $url, $pathInfo)
redirectCgiQueryHandler($query, $url)
registrationHandler($web, $wikiName, $loginName)
writeHeaderHandler($query)
checkTopicEditLock($web, $topic) ->($oopsUrl, $loginName, $unlockTime)
readTopicText($web, $topic, $rev, $ignorePermissions) -> $text
saveTopicText($web, $topic, $text, $ignorePermissions, $dontNotify) -> $oopsUrl
setTopicEditLock($web, $topic, $lock) -> $oopsUrl
afterCommonTagsHandler($text, $topic, $web)
afterSaveHandler($text, $topic, $web, $error)
beforeCommonTagsHandler($text, $topic, $web)
earlyInitPlugin()
afterAttachmentSaveHandler(\%attrHash, $topic, $web, $error, $meta)
beforeAttachmentSaveHandler(\%attrHash, $topic, $web, $meta)
checkDependencies($moduleName, $dependenciesRef) -> $error
extractParameters($attr) -> %params
formatTime($time, $format, $timezone) -> $text
getPluginPreferencesFlag($key) -> $boolean
getPluginPreferencesValue($key) -> $value
getRegularExpression($regexName) -> $pattern
mergeHandler($diff, $old, $new, \%info) -> $text
modifyHeaderHandler(\%headers, $query)
postRenderingHandler($text)
preRenderingHandler($text, \%map)
renderFormFieldForEditHandler($name, $type, $size, $value, $attributes, $possibleValues) -> $html
renderWikiWordHandler($linkText, $hasExplicitLinkLabel, $web, $topic) -> $linkText
endRenderingHandler($text)
startRenderingHandler($text, $web)
addToHEAD($id, $header)
attachmentExists($web, $topic, $attachment) -> $boolean
clearSessionValue($key) -> $boolean
checkDependencies($moduleName, $dependenciesRef) -> $error
createWeb($newWeb, $baseWeb, $opts)
expandTemplate($def ) -> $string
expandVariablesOnTopicCreation($text) -> $text
getContext() -> \%hash
getListOfWebs($filter) -> @webs
getScriptUrl($web, $topic, $script, @params) -> $url
getRevisionAtTime($web, $topic, $time) -> $rev
getWorkArea($pluginName) -> $directorypath
isValidWikiWord($text) -> $boolean
loadTemplate($name, $skin, $web) -> $text
moveAttachment($web, $topic, $attachment, $newWeb, $newTopic, $newAttachment)
moveTopic($web, $topic, $newWeb, $newTopic)
moveWeb($oldName, $newName)
normalizeWebTopicName($web, $topic) ->($web, $topic)
readAttachment($web, $topic, $name, $rev) -> $data
registerRESTHandler($alias, \&fn,)
registerTagHandler($var, \&fn, $syntax)
saveAttachment($web, $topic, $attachment, $opts)
saveTopic($web, $topic, $meta, $text, $options) -> $error
searchInWebContent($searchString, $web, \@topics, \%options) -> \%map
sendEmail($text, $retries) -> $error
wikiToEmail($wikiName) -> $email
writeHeader($query, $contentLength)
checkDependencies($moduleName, $dependenciesRef) -> $error
formatGmTime($time, $format) -> $text
getDataDir() -> $dir
getOopsUrl( $web, $topic, $template, @params ) -> $url
getPubDir() -> $dir
getPublicWebList() -> @webs
getScriptUrlPath() -> $path
afterSaveHandler($text, $topic, $web, $error, $meta)
beforeSaveHandler($text, $topic, $web, $meta)
afterRenameHandler($oldWeb, $oldTopic, $oldAttachment, $newWeb, $newTopic, $newAttachment)
afterCommonTagsHandler($text, $topic, $web, $meta)
beforeCommonTagsHandler($text, $topic, $web, $meta)
commonTagsHandler($text, $topic, $web, $included, $meta)
decodeFormatTokens($str) -> $unencodedString
eachChangeSince($web, $time) -> $iterator
eachGroup() -> $iterator
eachGroupMember($group) -> $iterator
eachMembership($wikiname) -> $iterator
eachUser() -> $iterator
emailToWikiNames($email, $dontAddWeb) -> @wikiNames
expandCommonVariables($text, $topic, $web, $meta) -> $text
getCanonicalUserID( $user ) -> $cUID
getExternalResource($url) -> $response
getSessionKeys() -> @keys
isAnAdmin($login) -> $boolean
isGroup($group) -> $boolean
isGroupMember($group, $login) -> $boolean
isTrue($value, $default) -> $boolean
popTopicContext()
pushTopicContext($web, $topic)
sanitizeAttachmentName($fname) -> ($fileName, $origName)
setPreferencesValue($name, $val)
spaceOutWikiWord($word, $sep) -> $text
wikiNameToEmails($wikiname) -> @emails
permissionsSet($web) -> $boolean
getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url
buildWikiWord( $text ) -> $text
registerTagHandler
has two new parameters $meta
and $textRef
afterAttachmentSaveHandler(\%attrHash, $topic, $web, $error, $meta)
-- added $meta
beforeAttachmentSaveHandler(\%attrHash, $topic, $web, $meta)
= added =$meta
writeLog( $action, $extra, $web, $topic, $user )
twiki/bin
and twiki/tools
directories. This topic describes the interfaces to some of those scripts. All scripts in the twiki/bin
directory can be called from the CGI (Common Gateway Interface) environment or from the command line. The scripts in the twiki/tools
directory can only be called from the command line.
twiki/bin
directory.
guest
).
twiki/bin
directory on the perl path to run the scripts from the command line. To avoid issues with file permissions, run the scripts as the web server user such as nobody
or www
.
Parameters are passed on the command line using '-name' - for example,
$ cd /usr/local/twiki/bin $ save -topic MyWeb.MyTopic -user admin -action save -text "New text of the topic"All parameters require a value, even if that is the empty string.
Parameter | Description | Default |
---|---|---|
topic |
If this is set to a URL, TWiki will immediately redirect to that URL. Otherwise it overrides the URL and is taken as the topic name (you can pass Web.TopicName) | |
user |
Command-line only; set the name of the user performing the action. Note: this usage is inherently insecure, as it bypasses webserver login constraints. For this reason only authorised users should be allowed to execute scripts from the command line. | |
skin |
Overrides the default skin path (see TWikiSkins) | |
cover |
Specifies temporary skin path to prepend to the skin path for this script only (see TWikiSkins) |
attach
upload
. This script is part of the transactions sequence executed when a file is uploaded from the browser. it just generates the "new attachment" page for a topic.
Parameter | Description | Default |
---|---|---|
filename |
Name of existing attachment (if provided, this is a "manage attachment" action) | none (in which case this is a "new attachment" action) |
changes