configure
Resource | Required Server Environment * |
---|---|
Perl | 5.6.1 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 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 |
Cron/scheduler | � Unix: cron � Windows: cron equivalents |
Web server | Apache is well supported; see TWiki:TWiki.InstallingTWiki#OtherWebServers for other servers |
Module | Preferred version |
---|---|
Algorithm::Diff (included) | |
CGI::Carp | >=1.26 |
Config | >=0 |
Cwd | >=3.05 |
Data::Dumper | >=2.121 |
Error (included) | |
File::Copy | >=2.06 |
File::Find | >=1.05 |
File::Spec | >=3.05 |
File::Temp | (included with perl 5.6 and later) |
FileHandle | >=2.01 |
IO::File | >=1.10 |
Text::Diff (included) | |
Time::Local | >=1.11 |
Module | Preferred version | Description |
---|---|---|
CGI::Cookie | >=1.24 | Used for session support |
CGI::Session | >=3.95 | Used for session support |
Digest::base | ||
Digest::SHA1 | ||
Jcode | Used for I18N support with perl 5.6 | |
Locale::Maketext::Lexicon | >=0 | Used for I18N support |
Net::SMTP | >=2.29 | Used for sending mail |
Unicode::Map | Used for I18N support with perl 5.6 | |
Unicode::Map8 | Used for I18N support with perl 5.6 | |
Unicode::MapUTF8 | Used for I18N support with perl 5.6 | |
Unicode::String | Used for I18N support with perl 5.6 | |
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"'
TWikiUpgradeGuide
instead.
Both this document and the TWikiUpgradeGuide are also available in the root of the distribution as HTML files. For this reason links to pages inside your own TWiki are written like TWiki.WebHome
and not like live web links.
TWikiUpgradeGuide.html
included in the root of your TWiki distribution.
Upgrading from a recent TWiki4 release is much simpler. Upgraders from earlier TWiki4 versions can follow the steps described in TWiki:TWiki.UpgradingTWiki04x00PatchReleases to ensure a safe upgrade without accidently overwriting customizations.
One of the more difficult tasks is installation of addition CPAN libraries. See TWiki:TWiki.HowToInstallCpanModules for detailed information on how to install CPAN libraries.
If you need help, ask a question in the TWiki:Support web or on TWiki:Codev.TWikiIRC (irc.freenode.net, channel #twiki)
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) configure
for the first time, you can only edit the section General Path Settings
. Save these settings, and then return to configure
to continue configuration.
{PermittedRedirectHostUrls}
{WebMasterEmail}
, and {SMTP}{MAILHOST}
must be defined to enable TWiki to send registration emails. 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 3 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 4.2
TWiki.TWikiUserAuthentication
, and TWiki:TWiki.TWikiUserAuthenticationSupplement.
These are the steps for enabling "Template Login" which asks for a username and password in a web page, and processes them using the Apache 'htpasswd' password manager. Users can log in and log out.
Security Settings
pane of configure
: TWiki::Client::TemplateLogin
for {LoginManager}
.
TWiki::Users::HtPasswdUser
for {PasswordManager}
.
configure
settings.
TWiki.TWikiRegistration
topic.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.
TWiki.TWikiUserAuthentication
, TWiki:TWiki.TWikiUserAuthenticationSupplement, and TWiki:TWiki.SecuringTWikiSite for further information about managing users and security of your TWiki site.
Note! The other LoginManager
option TWiki::Client::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.
TWikiAdminGroup
. It is the WikiName and not the login name you add to the group. Editing the Main.TWikiAdminGroup
topic requires that you are an administrator. So to add the first administrator you need to login using the internal TWiki admin user login and the password you defined in configure.
Main.TWikiAdminGroup
topic
Main.TWikiAdminGroup
of how to become an admin
TWiki.TWikiPreferences
. Read through it and identify any additional settings or changes you think you might need. You can edit the settings in TWiki.TWikiPreferences
but these will be overwritten when you later upgrade to a newer TWiki version. Instead copy any settings or variables that you want to customize from TWiki.TWikiPreferences
and paste them into Main.TWikiPreferences
. When you later upgrade TWiki simply avoid overwriting the 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 top of TWiki.TWikiPreferences
for more information.
tools/mailnotify
script as described in the TWiki.MailerContrib
topic.
TWiki.TWikiSiteTools
topic.
configure
for {Sessions}{ExpireAfter} and install let cron 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.
TWiki.NewUserTemplate
topic (and its TWiki.UserForm
). It contains additional resources you can use to: TWiki.UserForm
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.
If you added or removed fields from the user form you may also need to tailor TWiki.TWikiRegistration
.
TWiki.InstalledPlugins
.
You activate installed plugin in the Plugins section of 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 documenation 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.
TWiki.PatternSkinCustomization
At the official TWiki website you can find more resources. A good place to start for exploring what's possible is TWiki:TWiki.TWikiAdminCookBook which offers tips and tricks for customizing your TWiki site. Many of these are appropriate to implement immediately after installing TWiki and before adding content so now's a good time to look at these.
TWiki.ChangePassword
TWiki.ResetPassword
TWiki.ChangeEmailAddress
TWiki.TWikiPreferences
to Main.TWikiPreferences
and alter the copied text to your need.
WebPreferences
in each web. E.g. adding a confidencial classification to a very restricted web.
TWiki.WebPreferences
covers the documentation that comes with TWiki and is covered by the original TWiki Copyright and GPL License. You will normally leave this unchanged.
configure
script and make sure you have resolved all errors, and are satisfied that you understand any warnings.
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.4 or higher is recommended. TWiki will run in perl 5.6.1 but only with Wysiwyg editor disabled. Wysiwyg requires unicode support which is provided by perl 5.8.1 and forward. |
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 |
Other external programs | fgrep, egrep |
Cron/scheduler | • Unix: cron • Windows: cron equivalents |
Web server | Apache is well supported; for information on other servers, see TWiki:TWiki.InstallingTWiki#OtherWebServers. |
Module | Preferred version |
---|---|
Algorithm::Diff (included) | |
CGI | 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 |
Error (included) | |
File::Copy | >=2.06 |
File::Find | >=1.05 |
File::Spec | >=3.05 |
FileHandle | >=2.01 |
IO::File | >=1.10 |
Text::Diff (included) | |
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 | |
CGI::Cookie | >=1.24 | Used for session support |
CGI::Session | >=3.95 | Highly recommended! Used for session support |
Digest::base | ||
Digest::SHA1 | ||
Jcode | Used for I18N support with perl 5.6 | |
Locale::Maketext::Lexicon | >=0 | Used for I18N support |
Net::SMTP | >=2.29 | Used for sending mail |
Unicode::Map | Used for I18N support with perl 5.6 | |
Unicode::Map8 | Used for I18N support with perl 5.6 | |
Unicode::MapUTF8 | Used for I18N support with perl 5.6 | |
Unicode::String | Used for I18N support with perl 5.6 | |
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/TWikiSkinBrowser
and more at TWiki:Plugins.SkinPackage.
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}
.
lib/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.
Main.TWikiPreferences
instead
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 adviced 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
Set ALLOWTOPICCHANGE = TWikiAdminGroup, TWikiRegistrationAgent
. Otherwise people will not be able to register.
<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*
.
.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 [[/twiki/bin/configure][configure] interface for more details.
You can easily plug in alternate password management modules to support interfaces to other third-party authentication databases.
none
in configure) TWiki::Client::TemplateLogin
in configure) TWiki::Client::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 home 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 home page by creating the Main.NewUserTemplate? topic, which will then override the default.
TWiki::Client::ApacheLogin
in configure) 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.
mod_auth
TWiki::Client::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 home 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" }% %SESSION_VARIABLE{ "varName" set="varValue" }% %SESSION_VARIABLE{ "varName" clear="" }%Note that you cannot override access controls preferences this way.
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 personal home 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 home 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
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 = Main.SomeUser, Main.OtherUser, Main.SomeGroup
Set ALLOWTOPICCHANGE = Main.KasabianGroup
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 = Main.ElizabethWindsor, Main.TonyBlair
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 >
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 =
Set DENYTOPICVIEW =
mod_rewrite
module, and configure your webserver to redirect accesses to attachments to the TWiki viewfile
script. For example,
ScriptAlias /twiki/bin/ /filesystem/path/to/twiki/bin/ Alias /twiki/pub/ /filesystem/path/to/twiki/pub/ RewriteEngine on RewriteCond %{REQUEST_URI} !^/+twiki/+pub/+TWiki/+.+ RewriteRule ^/+twiki/+pub/+([^/]+)/+((([^/]+)/+)+)(.+) /twiki/bin/viewfile/$1/$4?filename=$5 [L,PT]That way all the controls that apply to the topic also apply to attachments to the topic. Other types of webserver have similar support. Note: Images embedded in topics will load much slower since each image will be delivered by the
viewfile
script.
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.
all webs
search option from accessing obfuscated webs. Do so by enabling the NOSEARCHALL
variable in WebPreferences: Set NOSEARCHALL = on
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.
Back to top<!--
* Set DENYTOPICCHANGE = Main.SomeGroup
-->
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, but 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.
|
_This works_, _this does not _ |
This works, _this does not _ |
|||||||||||||||||||||||||
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> } } |
|||||||||||||||||||||||||
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: You can create a forced internal link by enclosing words in double square brackets. Text within the brackets may contain optional spaces; the topic name is formed by capitalizing the initial letter and by removing the spaces; for example, [[text formatting FAQ]] links to topic TextFormattingFAQ. You can also refer to a different web and use anchors.
To "escape" double square brackets that would otherwise make a link, prefix the leading left square bracket with an exclamation point. |
[[wiki syntax]] [[Main.TWiki groups]] escaped: ![[wiki syntax]] | wiki syntax Main.TWiki groups escaped: [[wiki syntax]] | |||||||||||||||||||||||||
Specific Links: You can create a link where you specify the link text and the URL separately using nested square brackets [[reference][text]] . Internal link references (e.g. WikiSyntax) and URLs (e.g. http://TWiki.org/) are both supported.
The rules described under Forced Links apply for internal link references.
Anchor names can be added as well, to create a link to a specific place in a topic. |
[[WikiSyntax][wiki syntax]] [[http://gnu.org][GNU]] | wiki syntax GNU | |||||||||||||||||||||||||
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 | |||||||||||||||||||||||||
Literal content: 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 content: 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.
http://...
, https://...
, ftp://...
, gopher://...
, news://...
, file://...
, telnet://...
and mailto:...@...
are linked automatically.
name@domain.com
are linked automatically.
[[Square bracket rules]]
let you easily create non-WikiWord links. [[http://yahoo.com Yahoo home page]]
as an easier way of doing external links with descriptive text for the link, such as Yahoo home page.
%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. You can also define your own
TWiki Variables at the entire site, individual web, or individual topic level. For more information,
go to TWikiVariables
TWiki Variables are fully expanded before any of the TWiki text formatting rules are applied.
Documentation Graphics: There are many graphics available to use in your topics. Use %ICON{"help"}%
, %ICON{"tip"}%
, and %ICON{"warning"}%
to get: , , and , respectively. TWikiDocGraphics lists them all.
To "escape" a variable, prefix it with an exclamation mark. Write: !%SOMEVARIABLE%
to get: %SOMEVARIABLE%.
%PLUGINDESCRIPTIONS%
:
"$SUM( $ABOVE() )"
to TWiki tables and other topic text ExternalSite:Page
text to external sites based on aliases defined in a rules topic :-)
or for :eek:
<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 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:Spaces 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.
Set VARIABLENAME = value
Set VARIABLENAME = value
Example:Whatever you include in your Variable will be expanded on display, exactly as if it had been entered directly.* Set VARIABLENAME = value starts here and continues here
Example: Create a custom logo variableYou can also set preferences variables on a topic by clicking the link
- To place a logo anywhere in a web by typing
%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.gif
Edit topic preference settings
under More topic actions
. Preferences set in this manner are not visible in the topic text, but take effect nevertheless.
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.
%BR%
- line break
%BULLET%
- bullet sign
%BB%
- line break and bullet combined
%BB2%
- indented line break and bullet
%RED% text %ENDCOLOR%
- colored text (also %YELLOW%
, %ORANGE%
, %PINK%
, %PURPLE%
, %TEAL%
, %NAVY%
, %BLUE%
, %AQUA%
, %LIME%
, %GREEN%
, %OLIVE%
, %MAROON%
, %BROWN%
, %BLACK%
, %GRAY%
, %SILVER%
, %WHITE%
)
%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
%SEARCH%
, are powerful and general tools.
%INCLUDINGTOPIC%
, %INCLUDE%
, and the mighty %SEARCH%
.
%ACTIVATEDPLUGINS%
%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%
http://www.twiki.faced.ufba.br/twiki/pub/TWiki/VarATTACHURL
%ATTACHURL%/image.gif
%ATTACHURLPATH%
/twiki/pub/TWiki/VarATTACHURLPATH
%AUTHREALM%
%TOPIC%
if there is no INCLUDE
%BASETOPIC%
%WEB%
in case there is no include.
%BASEWEB%
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%
.
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%
.
%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
%COMMENT%
without parameters shows a simple text box.
Name | Description | Default |
---|---|---|
type | This is the name of the template to use for this comment. Comment templates are defined in a TWiki template - see Customisation, below. 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%
11 Nov 2024
%DISPLAYTIME%
11 Nov 2024 - 08:02
%GMTIME%
%DISPLAYTIME{"format"}%
%DISPLAYTIME{"$hou:$min"}%
expands to 08:02
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%/%TWIKIWEB%/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 | ||||||||||||||||
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="entity" | Encode special characters into HTML entities, like a double quote into " . Does not encode \n or \r . | type="url" |
type="html" | As type="entity" except it also encodes \n and \r | type="url" |
type="quotes" | Escape double quotes with backslashes (\" ), does not change other characters | type="url" |
type="url" | Encode special characters for URL parameter use, like a double quote into %22 | (this is the default) |
%ENCODE{"spaced name"}%
expands to spaced%20name
<input type="text" name="address" value="%ENCODE{ "any text" type="entity" }%" />
%SEARCH{ "%ENCODE{ "string with "quotes"" type="quotes" }%" noheader="on" }%
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"}%
Parameter: | Description: |
---|---|
"name" | Name of the section. |
type="..." | Type of the section being terminated; supported types "section" , "include" , "templateonly" . |
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
.
%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. $value expands to the field value, and $title expands to the fieldname (also expands $name, $attributes, $type, $size and $definingTopic) | "$value" |
default="..." | Text shown when no value is defined for the field | "" |
alttext="..." | Text shown when field is not found in the form | "" |
%FORMFIELD{"ProjectName" topic="Projects.SushiProject" default="(not set)" alttext="ProjectName field found"}%
%GMTIME%
11 Nov 2024 - 11:02
%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 "Local" (if set to servertime) | GMT |
$iso | ISO format timestamp | 2024-11-11T11:02:09Z |
$rcs | RCS format timestamp | 2024/11/11 11:02:09 |
$http | E-mail & http format timestamp | Mon, 11 Nov 2024 11:02:09 GMT |
$epoch | Number of seconds since 00:00 on 1st January, 1970 | 1731322929 |
%GMTIME{"$day $month, $year - $hour:$min:$sec"}%
expands to 11 Nov, 2024 - 11:02:09
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%
%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%
www.twiki.faced.ufba.br
%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"}%
%ICON{"name"}%
%ICON{"flag-gray"}%
returns
%ICON{"pdf"}%
returns
%ICON{"smile.pdf"}%
returns
%ICON{"/dont/you/dare/smile.pdf"}%
returns
%ICON{"http://twiki.org/doc/xhtml.xsl"}%
returns
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 http://www.twiki.faced.ufba.br/twiki/pub/TWiki/TWikiDocGraphics/arrowbright.gif
%ICONURL{"novel.pdf"}%
returns http://www.twiki.faced.ufba.br/twiki/pub/TWiki/TWikiDocGraphics/pdf.gif
%ICONURL{"/queen/boheme.mp3"}%
returns http://www.twiki.faced.ufba.br/twiki/pub/TWiki/TWikiDocGraphics/mp3.gif
%ICONURLPATH{"name"}%
%ICONURLPATH{"locktopic"}%
returns /twiki/pub/TWiki/TWikiDocGraphics/locktopic.gif
%ICONURLPATH{"eggysmell.xml"}%
returns /twiki/pub/TWiki/TWikiDocGraphics/xml.gif
%ICONURLPATH{"/doc/xhtml.xsl"}%
returns /twiki/pub/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 |
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 | |
PARONE="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 %PARONE% and %PARTWO% being defined within the included topic. |
disableremovescript
parameter)
%TOPIC%
in case there is no include
%INCLUDINGTOPIC%
%WEB%
if there is no INCLUDE.
%INCLUDINGWEB%
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%
%LOGOUT%
%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 cannot 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. | Show a single form field |
"form" | none | 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. | Generates the list of attachments |
"moved" | none | 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 " > " . | Generates the parent link |
%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"}%
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%
.
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 and other topic text ExternalSite:Page
text to external sites based on aliases defined in a rules topic :-)
or for :eek:
%PLUGINVERSION{"name"}%
to get the version of a specific plugin
%PLUGINVERSION{"InterwikiPlugin"}%
expands to $Rev: 14913 (17 Sep 2007) $
%PLUGINVERSION%
to get the version of the API
1.2
%PUBURL%
http://www.twiki.faced.ufba.br/twiki/pub
%PUBURL%/%WEB%/OtherTopic/image.gif
%PUBURLPATH%
/twiki/pub
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%
.
%QUERYPARAMS{...}%
format="..."
format string for each entry, default $name=$value
separator="..."
separator string, default separator="$n"
(newline)
encoding="..."
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 |
Double quote (" ) (\" also works) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
%QUERYPARAMS{format="<input type='hidden' name='$name' value='$value' encoding="entity" />"}%
%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%
.
%REMOTE_ADDR%
34.204.176.71
%REMOTE_PORT%
52838
%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%
r2 - 27 Mar 2005 - 10:14:15 - TWikiContributor
%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="1.5" | Specific revison number | Latest revision |
Variable: | Unit: | Example |
---|---|---|
$web | Name of web | Current web |
$topic | Topic name | Current topic |
$rev | Revison number. Prefix r1. to get the usual r1.5 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 | 21 Sep 2006 |
$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
viewauth.cgi
)
%SCRIPTNAME%
view
.pl
or .cgi
%SCRIPTSUFFIX%
%SCRIPTURL%
http://www.twiki.faced.ufba.br/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"}%
http://www.twiki.faced.ufba.br/twiki/bin/script
%SCRIPTURL{"viewauth"}%/%WEB%/%TOPIC%
which expands to http://www.twiki.faced.ufba.br/twiki/bin/viewauth/TWiki/TWikiVariables
%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 |
header="..." format="..." | Custom format results: see FormattedSearch for usage, variables & examples | Results in table |
expandvariables="on" | Expand variables before applying a FormattedSearch on a search hit. Useful to show the expanded text, e.g. to show the result of a SpreadSheetPlugin %CALC{}% instead of the formula | Raw text |
multiple="on" | Multiple hits per topic. Each hit can be formatted. The last token is used in case of a regular expression ";" and search | Only one hit per topic |
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 the format="" parameter contains a $pattern() that captures more than one line, i.e. contents of a textfield in a form. | "$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%
11 Nov 2024 - 08:02
%GMTIME%
%SERVERTIME{"format"}%
%SERVERTIME{"$hou:$min"}%
expands to 08:02
%SESSIONID%
%SESSIONVAR%
%SESSION_VARIABLE{"name"}%
%SESSION_VARIABLE{"name" set="value"}%
%SESSION_VARIABLE{"name" clear=""}%
AUTHUSER
session variable, and is read-only
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. This is used to embed text that you do not want expanded when a new topic based on the template topic is created. See TWikiTemplates for more information.
%STARTSECTION{"name"}% ................ %ENDSECTION{"name"}%
%STARTSECTION{type="include"}% ........ %ENDSECTION{type="include"}%
%STARTSECTION{type="templateonly"}% ... %ENDSECTION{type="templateonly"}%
Parameter: | Description: | Default |
---|---|---|
"name" | Name of the section. Must be unique inside a topic. | Generated name |
type="..." | Type of the section; type "section" , "include" or "templateonly" | "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
%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%
.
%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
%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
%SYSTEMWEB%
instead.
%URLPARAM{"name"}%
Parameter: | Description: | Default: |
---|---|---|
"name" | The name of a URL parameter | required |
default="..." | Default value in case parameter is empty or missing | empty string |
newline="<br />" | Convert newlines in textarea to other delimiters | no conversion |
encode="entity" | Encode special characters into HTML entities. See ENCODE for more details. | no encoding |
encode="url" | Encode special characters for URL parameter use, like a double quote into %22 | no encoding |
encode="quote" | Escape double quotes with backslashes (\" ), does not change other characters; required when feeding URL parameters into other TWiki variables | no encoding |
multiple="on" multiple="[[$item]]" | If set, gets all selected elements of a <select multiple="multiple"> tag. A format can be specified, with $item indicating the element, e.g. multiple="Option: $item" | first element |
separator=", " | Separator between multiple selections. Only relevant if multiple is specified | "\n" (new line) |
%URLPARAM{"skin"}%
returns print
for a .../view/TWiki/TWikiVariables?skin=print
URL
%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
%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%
TWiki
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) | "" |
%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
%SCRIPTURLPATH{"view"}%
%WIKILOGOURL%
defined in WebPreferences instead.
%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-4.2.2, Wed, 06 Aug 2008, build 17396
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 |
Double quote (" ) (\" also works) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar 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, shortended to 40 characters with "..." indication |
$parent |
Name of parent topic; empty if not set |
$parent(20) |
Name of parent topic, same hyphenation/shortening like $topic() |
$text |
Formatted topic text. In case of a multiple="on" search, it is the line found for each search hit. |
$locked |
LOCKED flag (if any) |
$date |
Time stamp of last topic update, e.g. 11 Nov 2024 - 11:02 |
$isodate |
Time stamp of last topic update, e.g. 2024-11-11T11:02Z |
$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, shortended to 30 characters with "..." indication |
$pattern(reg-exp) |
A regular expression pattern to extract some text from a topic (does not search meta data; use $formfield instead). In case of a multiple="on" search, the pattern is applied to the line found in each search hit.� Specify a RegularExpression that covers the whole text (topic or line), which typically starts with .* , and must end in .* � Put text you want to keep in parenthesis, like $pattern(.*?(from here.*?to here).*) � Example: $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the 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. |
$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 |
Double quote (" ) (\" also works) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
%SEARCH{ "FAQ" scope="topic" nosearch="on" nototal="on" header=" * *Topic: Summary:*" format=" * [[$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:
PosPetroGroup | GustavoGomes | 14 Jan 2015 - 15:47 |
TWikiRegistration | NadilsonSantana | 27 Jan 2012 - 10:36 |
WysiwygPlugin | TWikiContributor | 10 Aug 2008 - 12:02 |
WelcomeGuest | TWikiContributor | 03 Jun 2008 - 18:38 |
WysiwygPluginSettings | TWikiContributor | 22 Jan 2008 - 00:21 |
WikiReferences | TWikiContributor | 12 Aug 2007 - 05:07 |
WikiWord | TWikiContributor | 18 Jul 2007 - 01:58 |
%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"}%" /> <input type="submit" class="twikiSubmit" value="Search" /> </form> Result: %SEARCH{ search="%URLPARAM{"q"}%" format=" * $web.$topic: %BR% $summary" nosearch="on" }%To get this: Result: Related Topics: UserDocumentationCategory, SearchHelp, TWikiVariables#VarSEARCH, SearchPatternCookbook, RegularExpression -- Contributors: TWiki:Main.PeterThoeny, TWiki:Main.CrawfordCurrie 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 120000 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: /twiki/pub/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 /twiki/pub/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>
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
is the name of the form field.
The Type
, Size
and Value
fields describe the legal values for this field, and how to display them. Type
checkbox
specifies one or more checkboxes. The Size
field specifies how many checkboxes will be displayed on each line. The Value
field should be a comma-separated list of item labels. Type
checkbox+buttons
will add Set and Clear buttons to the basic checkbox
type.
Type
radio
is like checkbox
except that radio buttons are mutually exclusive; only one can be selected.
Type
label
specifies read-only label text. The Value
field should contain the text of the label.
Type
select
specifies a select box. The Value
field should contain a comma-separated list of options for the box. The Size
field can specify a fixed size for the box (e.g. 1
, or a range e.g. 3..10
. If you specify a range, then the box will never be smaller than 3 items, never larger than 10, and will be 5 high if there are only 5 options. select
type: select+multi
turns multiselect on for the select, to allow Shift+Click and Ctrl+Click to select (or deselect) multiple items.
select+values
allows the definition of values that are different to the displayed text. For example: | Field 9 | select+values | 5 | One, Two=2, Three=III, Four | Various values formats |shows but the values or options
Two
and Three
are 2
and III
respectively.select+multi+values
Type
text
specifies a one-line text field. Size
specifies the text box width in number of characters. Value
is the initial (default) content when a new topic is created with this form template.
Type
textarea
specifies a multi-line text box. The Size
field should specify columns x rows, e.g. 80x6
; default size is 40x5. As for text
, the Value
field specifies the initial text
Type
date
specifies a single-line text box and a button next to it; clicking on the button will bring up a calendar from which the user can select a date. The date can also be typed into the text box. Size
specifies the text box width in characters. As for text
, the Value
field specifies the initial text
Tooltip message
is a message that will be displayed when the cursor is hovered over the field in edit
view.
Attributes
specifies special attributes for the field. Multiple attributes can be entered, separated by spaces. H
indicates that this field should not be 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
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.
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. 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.
%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 |
%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"}%
markers are used to embed text that you do not want expanded when a new topic based on the template topic is created. For example, you might want to write 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 get 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 e.g.i escape %SERVERTIME%
with %SER%NOP%VERTIME%
.
All other variables are unchanged, e.g. are carried over "as is" into the new topic.
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>See TWikiScripts#edit for details of the parameters that the
edit
script understands.
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 Go 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 "Go" 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 ? questionmark 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 15675 (11 Aug 2008) %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 SHORTDESCRIPTION = Control attributes of tables and sorting of table columns
%<pluginname>_<var>%
, such as %TABLEPLUGIN_SHORTDESCRIPTION%
. They can also be redefined with the %<pluginname>_<var>%
setting at a lower level in the Main.TWikiPreferences or at the web level. For an easier upgrade it is recommended to customize plugin preferences variables in Main.TWikiPreferences only.
%ACTIVATEDPLUGINS%
%PLUGINDESCRIPTIONS%
"$SUM( $ABOVE() )"
to TWiki tables and other topic text ExternalSite:Page
text to external sites based on aliases defined in a rules topic :-)
or for :eek:
%FAILEDPLUGINS%
Plugin | Errors |
---|---|
SpreadSheetPlugin | none |
AlbumOfSnapsPlugin | none |
ApprovalPlugin | none |
AttachmentList? |
TWiki::Plugins::AttachmentList could not be loaded. Errors were: Can't locate TWiki/Plugins/AttachmentList.pm in @INC (@INC contains: /var/www/twiki422/lib . /etc/perl /usr/local/lib/perl/5.10.0 /usr/local/share/perl/5.10.0 /usr/lib/perl5 /usr/share/perl5 /usr/lib/perl/5.10 /usr/share/perl/5.10 /usr/local/lib/site_perl /var/www/twiki422/lib/CPAN/lib//arch /var/www/twiki422/lib/CPAN/lib//5.10.0/x86_64-linux-gnu-thread-multi /var/www/twiki422/lib/CPAN/lib//5.10.0 /var/www/twiki422/lib/CPAN/lib/) at (eval 47) line 1. BEGIN failed--compilation aborted at (eval 47) line 1. ---- |
AttachmentListPlugin | none |
BatchUploadPlugin |
TWiki::Plugins::BatchUploadPlugin could not be loaded. Errors were: Can't locate Archive/Zip.pm in @INC (@INC contains: /var/www/twiki422/lib . /etc/perl /usr/local/lib/perl/5.10.0 /usr/local/share/perl/5.10.0 /usr/lib/perl5 /usr/share/perl5 /usr/lib/perl/5.10 /usr/share/perl/5.10 /usr/local/lib/site_perl /var/www/twiki422/lib/CPAN/lib//arch /var/www/twiki422/lib/CPAN/lib//5.10.0/x86_64-linux-gnu-thread-multi /var/www/twiki422/lib/CPAN/lib//5.10.0 /var/www/twiki422/lib/CPAN/lib/) at /var/www/twiki422/lib/TWiki/Plugins/BatchUploadPlugin.pm line 28. BEGIN failed--compilation aborted at /var/www/twiki422/lib/TWiki/Plugins/BatchUploadPlugin.pm line 28. Compilation failed in require at (eval 51) line 1. BEGIN failed--compilation aborted at (eval 51) line 1. ---- |
CaptchaPlugin | none |
CommentPlugin | none |
CounterPlugin | none |
EditTablePlugin | none |
EmptyPlugin | none |
ImageGalleryPlugin | none |
ImagePlugin | none |
InterwikiPlugin | none |
MultiEditPlugin |
TWiki::Plugins::MultiEditPlugin could not be loaded. Errors were: Can't locate TWiki/Contrib/EditContrib.pm in @INC (@INC contains: /var/www/twiki422/lib . /etc/perl /usr/local/lib/perl/5.10.0 /usr/local/share/perl/5.10.0 /usr/lib/perl5 /usr/share/perl5 /usr/lib/perl/5.10 /usr/share/perl/5.10 /usr/local/lib/site_perl /var/www/twiki422/lib/CPAN/lib//arch /var/www/twiki422/lib/CPAN/lib//5.10.0/x86_64-linux-gnu-thread-multi /var/www/twiki422/lib/CPAN/lib//5.10.0 /var/www/twiki422/lib/CPAN/lib/) at /var/www/twiki422/lib/TWiki/Plugins/MultiEditPlugin.pm line 28. BEGIN failed--compilation aborted at /var/www/twiki422/lib/TWiki/Plugins/MultiEditPlugin.pm line 28. Compilation failed in require at (eval 81) line 1. BEGIN failed--compilation aborted at (eval 81) line 1. ---- |
NewsPlugin | none |
PreferencesPlugin | none |
RenderListPlugin | none |
SendEmailPlugin | none |
SlideShowPlugin | none |
SmiliesPlugin | none |
TablePlugin | none |
TagMePlugin | none |
TinyMCEPlugin | none |
TopicTranslationsPlugin | none |
TwistyPlugin | none |
WysiwygPlugin | none |
Handler | Plugins |
---|---|
afterEditHandler | WysiwygPlugin |
afterSaveHandler | TagMePlugin |
beforeAttachmentSaveHandler | ApprovalPlugin |
beforeCommonTagsHandler | ApprovalPlugin EditTablePlugin PreferencesPlugin TopicTranslationsPlugin WysiwygPlugin |
beforeEditHandler | ApprovalPlugin TinyMCEPlugin WysiwygPlugin |
beforeMergeHandler | WysiwygPlugin |
beforeSaveHandler | ApprovalPlugin CaptchaPlugin CommentPlugin NewsPlugin WysiwygPlugin |
commonTagsHandler | SpreadSheetPlugin AlbumOfSnapsPlugin CaptchaPlugin CommentPlugin CounterPlugin EditTablePlugin ImageGalleryPlugin ImagePlugin SlideShowPlugin SmiliesPlugin TagMePlugin TopicTranslationsPlugin |
initPlugin | SpreadSheetPlugin AlbumOfSnapsPlugin ApprovalPlugin AttachmentListPlugin CaptchaPlugin CommentPlugin CounterPlugin EditTablePlugin EmptyPlugin ImageGalleryPlugin ImagePlugin InterwikiPlugin NewsPlugin PreferencesPlugin RenderListPlugin SendEmailPlugin SlideShowPlugin SmiliesPlugin TablePlugin TagMePlugin TinyMCEPlugin TopicTranslationsPlugin TwistyPlugin WysiwygPlugin |
modifyHeaderHandler | WysiwygPlugin |
postRenderingHandler | EditTablePlugin PreferencesPlugin WysiwygPlugin |
preRenderingHandler | InterwikiPlugin SmiliesPlugin TablePlugin |
startRenderingHandler | RenderListPlugin WysiwygPlugin This handler is deprecated - please check for updated versions of the plugins that use it! |
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.
DISABLE_
from the function name.
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
if you possibly can, as that will stop TWiki from reading the plugin topic for every page. Use Config.spec instead.
$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 1.2. %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.>"
- Plugins Preferences <If user settings are needed, explain... Entering values works exactly like TWikiPreferences and WebPreferences: six (6) spaces and then:>"
- Set <EXAMPLE = value added>
Plugin
, 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 a plugin starts with the plugin announcing what it is:
# ---+ 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** # Turn this option off 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, and
configure
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 are also used for other (non-plugin) extensions. in this case they are stored under the Contrib
directory instead of the Plugins
directory.
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 checkAccessPermissions('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'
$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)
$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 |
my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic ) $text =~ s/APPLE/ORANGE/g; TWiki::Func::saveTopic( $web, $topic, $meta, $text, { 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
checkAccessPermissions
to ensure the current user has read access to the
topic.
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
- CGI query object. If not given, the default CGI query will be used (optional, in most cases you should not pass this parameter)
$contentLength
- Length of content (optional, in most cases you should not pass this parameter)
$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.
$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
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 (defaulkt 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' ) |
$text
- Text to write; timestamp gets added
$text
- Text to write; timestamp gets added
$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 qw( ALLOW DENY ) { foreach my $action qw( 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)
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
changes
script can receive one parameter:
Parameter | Description | Default |
---|---|---|
minor |
If 0, show only major changes. If 1, show all the changes (both minor and major) | 0 |
%SEARCH%
, while this script reads the changes
file in each web, making it much faster.
NOTE: The result from changes
script and the topic WebChanges can be different, if the changes
file is deleted from a web. In particular, in new installations the changes
script will return no results while the WebChanges topic will.
configure
configure
is the browser script used for inspection and configuration of the TWiki configuration. None of the parameters to this script are useable for any purpose except configure
. See configure.
edit
edit
script understands the following parameters, typically supplied by HTML input fields:
Parameter | Description | Default |
---|---|---|
action |
Optional. Use the editaction template instead of the standard edit. If action=text, then hide the form. If action=form hide the normal text area and only edit the form. You can change the Edit/Edit Raw buttons to always append the action parameter in skins like Pattern and Classic by setting the topic or preference variable EDITACTION to the value text or form . To edit the topic once the EDITACTION is defined as form simply remove the action=form from the browser URL of the edit script and reload the edit window |
|
onlynewtopic |
If set, error if topic already exists | |
onlywikiname |
If set, error if topic name is not a WikiWord | |
templatetopic |
The name of the template topic, copied to get the initial content (new topic only) | |
text |
Initial text for the topic | |
topicparent |
The parent topic | |
formtemplate |
Name of the form to instantiate in the topic. Overrides the form set in the templatetopic if defined. (will remove the form is set to 'none') |
|
contenttype |
Optional parameter that defines the application type to wr |