configure
Resource | Required Server Environment * |
---|---|
Perl | 5.8.0 or higher (5.8.4 or higher is recommended) |
RCS | 5.7 or higher (including GNU diff ) Optional, TWiki includes a pure Perl implementation of RCS that can be used instead (although it's slower) |
GNU diff |
GNU diff 2.7 or higher is required when not using the all-Perl RcsLite. Install on PATH if not included with RCS (check version with diff -v ) Must be the version used by RCS, to avoid problems with binary attachments - RCS may have hard-coded path to diff |
GNU df |
Used by the site statistics to record disk usage statistics, optional. The df command is pre-installed on Linux and OS-X. On Windows install the CoreUtils for Windows. |
GNU patch |
For upgrades only: GNU patch is required when using the TWiki:Codev.UpgradeTWiki script |
GNU fgrep , egrep |
Modify command line parameters in configure if you use non-GNU grep programs |
zip |
Zip archive command line utility. Used by the BackupRestorePlugin to create and restore from backups. |
Cron/scheduler | • Unix: cron • Windows: cron equivalents |
Web server | Apache is well supported; see TWiki:TWiki.InstallingTWiki#OtherWebServers for other servers |
Module | Preferred version | Comment |
---|---|---|
Algorithm::Diff |
Included in TWiki distribution | |
CGI |
>=3.18 & <=4.03 | A suitable version ships with TWiki since TWiki-6.0.2 using CgiContrib, e.g. it is no longer necessary to install or downgrade this module. Versions 2.89 and 3.37, as well as version > 4.13 must be avoided. |
CGI::Carp |
>=1.26 | |
Config |
>=0 | |
Cwd |
>=3.05 | |
Data::Dumper |
>=2.121 | |
Encode |
>=2.1 | |
Error |
Included in TWiki distribution | |
File::Copy |
>=2.06 | |
File::Find |
>=1.05 | |
File::Spec |
>=3.05 | |
File::Temp |
>=0.18 | This version included in Perl 5.9.5. File::Temp needs to be updated on RedHat 5 and CentOS 5. |
FileHandle |
>=2.01 | |
HTML::Parser |
>=3.28 | Needed by the WysiwygPlugin for WYSIWYG editing |
HTML::Entities |
>=1.25 | Needed by the WysiwygPlugin for WYSIWYG editing |
IO::File |
>=1.10 | |
LWP |
Needed to install extensions in TWiki configure | |
Net::SMTP |
>=2.29 | Used for sending mail |
Text::Diff |
Included in TWiki distribution | |
Time::Local |
>=1.11 |
Module | Preferred version | Description |
---|---|---|
Archive::Tar |
May be required by the Extensions Installer in configure if command line tar or unzip is not available | |
Authen::SASL |
Used for SMTP Authentication | |
CGI::Cookie |
>=1.24 | Used for session support |
CGI::Session |
>=3.95 | Used for session support |
Crypt::SMIME |
>=0.09 | Required if S/MIME-signed administrative e-mail is enabled. |
Digest::base |
||
Digest::SHA1 |
||
JSON |
>=0 | Required if JSON objects are stored and retrieved in SetGetPlugin |
Locale::Maketext::Lexicon |
>=0 | Used for I18N support |
Net::SMTP |
>=2.29 | Used for sending mail |
URI |
Used for configure |
configure
script, or if you're still trying to get to that point, check from the command line like this:
perl -e 'use FileHandle; print $FileHandle::VERSION."\n"'
TWiki-6.0.1.tgz
for Linux)
/var/www
). Unpack the distribution in it (Example: tar xvfz TWiki-6.0.1.tgz
). The unpack will create a directory called twiki
which contains the TWiki package. In the rest of this document we assume this directory is called twiki
. chmod -R 770 twiki
. The access rules have different meaning for files and directories. This is the most common mistake installers make.
chown -R user:group /path/to/twiki
. The webserver username varies from Distributions. Examples for some major distributions: chown -R apache:apache /path/to/twiki
chown -R www-data:www-data /path/to/twiki
chown -R wwwrun:www /path/to/twiki
/usr/bin/perl
. If it's somewhere else, change the path to Perl in the first line of each script in the twiki/bin
directory.
apt-get install libcgi-pm-perl
. If needed, learn how to install CPAN modules.
.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 directory 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 makes setting up a correct and safe installation easier. 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 httpd.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.
misc/twiki_httpd_conf.txt
(nevertheless, it is better to use the generator).
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.
misc
directory 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 privileges.
configure
script from your browser (enter http://yourdomain/do/configure
into your browser address bar) admin
user password once TWiki is running. $TWiki::cfg{Password}
from LocalSite.cfg
file from {TWIKI_ROOT}/lib
directory.
configure
for the first time, you can only edit the General Path Settings
section. Save these settings, and then return to configure
to continue configuration.
{PermittedRedirectHostUrls}
{WebMasterEmail}
, and {SMTP}{MAILHOST}
must be defined to enable TWiki to send administrative emails, such as for registration and notification of topic changes. Many ISPs have introduced authentication when sending emails to fight spam so you may also have to set {SMTP}{Username}
and {SMTP}{Password}
. If you do not want to enable mailing or want to enable it later you can uncheck {EnableEmail}
.
http://yourdomain.com/do/view
and start TWiki-ing away!
pub
directory. TWiki has some built-in protection which renames files with dangerous file names by appending .txt to the file name. 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
directory should be script enabled, and the pub
directory should be HTML document enabled. misc/subdir-htaccess.txt
file can be copied as .htaccess
to the data, lib, locale, templates, tools and working directories.
misc/twiki_httpd_conf.txt
and example misc/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-6.0 Release.
Security Settings
pane of configure
: TWiki::LoginManager::TemplateLogin
for {LoginManager}
.
TWiki::Users::HtPasswdUser
for {PasswordManager}
.
configure
settings.
data/.htpasswd
file. If not, you probably got a path wrong, or the permissions may not allow the webserver user to write to that file.
Edit
link at beginning or end of topic) to check if authentication works.
LoginManager
option TWiki::LoginManager::ApacheLogin
uses a basic Apache type authentication where the browser itself prompts you for username and password. Most will find the TemplateLogin looking nicer. But ApacheLogin is required when you use Apache authentication methods like mod_ldap where all authentication is handled by an Apache module and not by the TWiki perl code. When you use ApacheLogin the apache configuration must be set up to require authentication of the some but not all the scripts in the bin directory. This section in the Apache config (or .htaccess) controls this
<FilesMatch "(attach|edit|manage|rename|save|upload|mail|logon|rest|.*auth).*"> require valid-user </FilesMatch>The TWiki:TWiki.ApacheConfigGenerator includes this section when you choose ApacheLogin. In the example
misc/twiki_httpd_conf.txt
and bin/.htaccess.txt
files this section is commented out with #. Uncomment the section when you use ApacheLogin. It is important that this section is commented out or removed when you use TemplateLogin.
data/Main/TWikiPreferences.txt
file and all your settings will be kept. Settings in Main.TWikiPreferences overrides settings in both TWiki.TWikiPreferences and any settings defined in plugin topics. See notes at the top of TWiki.TWikiPreferences for more information.
tools/mailnotify
script as described in the MailerContrib topic.
{WebMasterEmail}
email account. Obtain these as you would for any other S/MIME e-mail user.
To enable TWiki to sign administrative e-mails: /etc/pki/tls/certs
configure
script, change the following settings under Mail and Proxies: {MailProgram}
to enable an external mail program such as sendmail. Net::SMTP is not supported.
{SmimeCertificateFile}
configuration variable
{SmimeKeyFile}
configuration variable
configure
script an resolve any errors that it identifies
configure
for {Sessions}{ExpireAfter}
(turn on expert mode to see it), and install a cronjob to run the tools/tick_twiki.pl
script. Read The topic TWikiScripts#tick_twiki_pl for details how to do this.
Localization
section of configure
. For more information about these features, see TWiki:TWiki.InternationalizationSupplement.
/
to /twiki/bin/view/Intranet/WebHome
. Here is an example index.html
containing an HTML meta redirect you can use: Customize it and put it in your HTML document root on your TWiki sever:
<html> <head> <meta http-equiv="refresh" content="0;/do/view/Intranet/WebHome" /> </head> <body> Redirecting to <a href="/do/view/Intranet/WebHome">Intranet home</a>... </body> </html>2. Set the wiki logo URL When a user clicks on the logo in the upper left or on the "Home" link in the top-bar she expects to navigate to the new homepage. You can do that by defining and customizing the following setting in Main.TWikiPreferences as described in the Set TWiki Preferences section:
URL of the logo: * Set WIKILOGOURL = %SCRIPTURLPATH{view}%/Intranet/WebHome
configure
. In this section you also find a Find More Extensions button which opens an application which can install additional plugins from the TWiki.org website. If you are behind a firewall or your server has no access to the Internet it is also possible to install plugins manually. Manual installation instructions for the plugins can be found in the plugin topics on TWiki.org. Additional documentation on TWiki plugins can be found at TWiki:TWiki.TWikiPluginsSupplement.
Some plugins require that you define their settings in configure
. You fill find these under the Extensions section of configure.
configure
script and make sure you have resolved all errors, and are satisfied that you understand any warnings.
If, by any chance, you forget the "admin" password, the same used in "configure" script, then please login to the server. Delete $TWiki::cfg{Password}= ' ...';
. Set the new password using "configure" script.
Failing that, please check TWiki:TWiki.InstallingTWiki on TWiki.org, the supplemental documentation that help you install TWiki on different platforms, environments and web hosting sites. For example: Resource | Required Server Environment * |
---|---|
Perl | 5.8.0 or higher (5.8.4 or higher is recommended) |
RCS | 5.7 or higher (including GNU diff ) Optional, TWiki includes a pure Perl implementation of RCS that can be used instead (although it's slower) |
GNU diff |
GNU diff 2.7 or higher is required when not using the all-Perl RcsLite. Install on PATH if not included with RCS (check version with diff -v ) Must be the version used by RCS, to avoid problems with binary attachments - RCS may have hard-coded path to diff |
GNU df |
Used by the site statistics to record disk usage statistics, optional. The df command is pre-installed on Linux and OS-X. On Windows install the CoreUtils for Windows. |
GNU patch |
For upgrades only: GNU patch is required when using the TWiki:Codev.UpgradeTWiki script |
GNU fgrep , egrep |
Modify command line parameters in configure if you use non-GNU grep programs |
zip |
Zip archive command line utility. Used by the BackupRestorePlugin to create and restore from backups. |
Cron/scheduler | • Unix: cron • Windows: cron equivalents |
Web server | Apache is well supported; see TWiki:TWiki.InstallingTWiki#OtherWebServers for other servers |
Module | Preferred version | Comment |
---|---|---|
Algorithm::Diff |
Included in TWiki distribution | |
CGI |
>=3.18 & <=4.03 | A suitable version ships with TWiki since TWiki-6.0.2 using CgiContrib, e.g. it is no longer necessary to install or downgrade this module. Versions 2.89 and 3.37, as well as version > 4.13 must be avoided. |
CGI::Carp |
>=1.26 | |
Config |
>=0 | |
Cwd |
>=3.05 | |
Data::Dumper |
>=2.121 | |
Encode |
>=2.1 | |
Error |
Included in TWiki distribution | |
File::Copy |
>=2.06 | |
File::Find |
>=1.05 | |
File::Spec |
>=3.05 | |
File::Temp |
>=0.18 | This version included in Perl 5.9.5. File::Temp needs to be updated on RedHat 5 and CentOS 5. |
FileHandle |
>=2.01 | |
HTML::Parser |
>=3.28 | Needed by the WysiwygPlugin for WYSIWYG editing |
HTML::Entities |
>=1.25 | Needed by the WysiwygPlugin for WYSIWYG editing |
IO::File |
>=1.10 | |
LWP |
Needed to install extensions in TWiki configure | |
Net::SMTP |
>=2.29 | Used for sending mail |
Text::Diff |
Included in TWiki distribution | |
Time::Local |
>=1.11 |
Module | Preferred version | Description |
---|---|---|
Archive::Tar |
May be required by the Extensions Installer in configure if command line tar or unzip is not available | |
Authen::SASL |
Used for SMTP Authentication | |
CGI::Cookie |
>=1.24 | Used for session support |
CGI::Session |
>=3.95 | Used for session support |
Crypt::SMIME |
>=0.09 | Required if S/MIME-signed administrative e-mail is enabled. |
Digest::base |
||
Digest::SHA1 |
||
JSON |
>=0 | Required if JSON objects are stored and retrieved in SetGetPlugin |
Locale::Maketext::Lexicon |
>=0 | Used for I18N support |
Net::SMTP |
>=2.29 | Used for sending mail |
URI |
Used for configure |
configure
script, or if you're still trying to get to that point, check from the command line like this:
perl -e 'use FileHandle; print $FileHandle::VERSION."\n"'
pub
directory.)
twiki/bin
directory (e.g. because CGI bin directories can't be under your home directory and you don't have root access). You can create this directory elsewhere and configure the twiki/bin/LocalLib.cfg
file (done in Step 2). TWiki dir: | What it is: | Where to copy: | Example: |
---|---|---|---|
twiki/ | TWiki package | TWiki root directory, should be secure from public access | /home/smith/twiki/ |
twiki/bin/ | CGI bin | move to script-enabled dirctory | /home/smith/cgi/twiki/ |
twiki/lib/ | library files | leave in TWiki root | /home/smith/twiki/lib/ |
twiki/locale/ | language files | leave in TWiki root | /home/smith/twiki/locale/ |
twiki/pub/ | public files | move to HTML document enabled directory | /home/smith/html/twiki-pub/ |
twiki/data/ | topic data | leave in TWiki root | /home/smith/twiki/data/ |
twiki/templates/ | web templates | leave in TWiki root | /home/smith/twiki/templates/ |
twiki/tools/ | TWiki utlilities | leave in TWiki root | /home/smith/twiki/tools/ |
twiki/working/ | Temporary and internal files | leave in TWiki root | /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 distribution entitled misc/pub-htaccess.txt
.
.htaccess
in the bin directory that includes the following single line: SetHandler cgi-script
. This informs the server to treat all the perl scripts in the bin directory as scripts.
lib/TWiki.spec
to lib/LocalSite.cfg
$TWiki::cfg{DefaultUrlHost}
, $TWiki::cfg{ScriptUrlPath}
, $TWiki::cfg{PubUrlPath}
, $TWiki::cfg{PubDir}
, $TWiki::cfg{TemplateDir}
, $TWiki::cfg{DataDir}
, $TWiki::cfg{LocalesDir}
, and $TWiki::cfg{OS}
and make sure these settings have the correct values.
$TWiki::cfg{LoginManager}
, $TWiki::cfg{WebMasterEmail}
, $TWiki::cfg{SMTP}{MAILHOST}
, $TWiki::cfg{SMTP}{SENDERHOST}
.
twiki/lib/LocalSite.cfg
as a reference. This way you will not have old obsolete settings in the new LocalSite.cfg
.
LocalSite.cfg
file and re-run configure.
lib/TWiki.cfg
from the old TWiki installation is a good resource for some of the settings you will need but you cannot reuse the old TWiki.cfg.
DEFAULT_TYPE
setting of the CommentPlugin, create a COMMENTPLUGIN_DEFAULT_TYPE
setting in Main.TWikiPreferences.
twiki/data/Engineering
(for page content) and twiki/pub/Engineering
(for attachments).
find data -name '*,v' -exec rcs -u -M '{}' \;
find pub -name '*,v' -exec rcs -u -M '{}' \;
Main.TWikiUsers
topic to the new TWiki. If you upgrade from Cairo you can simply use the old file and add the missing new system users to the list of users. If you upgrade from TWiki-4.0.x simply use the old topic. Starting from 4.2.0 TWiki no longer ships with a Main.TWikiUsers
topic. When you register the first user TWiki now checks for an existing Main.TWikiUsers
and if it does not exist it gets created. {Register}{AllowLoginName}
to 1
.
data/.htpasswd
for authentication copy this file from the old TWiki to the new. tools/upgrade_emails.pl
.
TWiki.TWikiRegistration
. Make sure you either reuse the registration topic from the old installation or apply the same field changes to the new TWiki.TWikiRegistration
topic.
NewUserTemplate
and UserForm
in the TWiki web. If you choose to tailor anything you are strongly advised to copy NewUserTemplate
and UserForm
to the Main web and tailor the Main web copies. TWiki will look for the NewUserTemplate
in the Main web first and if it does not exist it uses the default from the TWiki web. By creating a Main.NewUserTemplate
and its Main.UserForm
you will not loose your tailorings next time you upgrade TWiki.
Main.TWikiPreferences
. This avoids having to write over files in the distribution on a later upgrade.
data/TWiki
of the old and new TWiki installation, and transfer the changes into the new TWiki install. If you can run a GUI on your server, you may find that using a visual diff tool like WinMerge, meld, kdiff3, xxdiff, etc. is helpful.
WebPreferences
topics in the old TWiki Installation with the default from the new TWiki installation and add any new Preferences that may be relevant.
WebLeftBar
topics in the old TWiki Installation with the default from the new TWiki installation and add any new feature that you desire.
twiki/bin
that allow content update, such as attach
, edit
, manage
, rename
, save
, upload
, rest
. Alternatively, if you have a recent TWiki version on the old server you can set a READONLYSKINMODE = 1
setting in Main.TWikiPreferences
to turn the skin into read-only mode.
TWiki.ChangePassword
TWiki.ResetPassword
TWiki.ChangeEmailAddress
* Set FAVICON = %PUBURLPATH%/%SYSTEMWEB%/%WEBPREFSTOPIC%/favicon.ico
* TWikiContributor - 2005-01-01 * TWikiGuest - guest - 1999-02-10 * TWikiRegistrationAgent - 2005-01-01 * UnknownUser - 2005-01-01What these users are:
Set ALLOWTOPICCHANGE = TWikiAdminGroup, TWikiRegistrationAgent
access control setting. Otherwise people will not be able to register.
%TMPL:DEF{"block"}%
and %TMPL:END%
was stripped of leading and trailing white space incl new lines.
This caused a lot of problems for skin developers when you wanted a newline before or after the block text.
From TWiki 4.1.0 this has changed so that white space is no longer stripped. Skins like PatternSkin and NatSkin have been updated so that they work with the new behavior. But if you use an older skin or have written your own you will most likely need to make some adjustments.
It is not difficult. The general rule is - if you get mysterious blank lines in your skin, the newline after the %TMPL:DEF{"block"}%
needs to be removed. Ie. the content of the block must follow on the same line as the TMPL:DEF.
The spec change have the same impact on CommentPlugin templates where you may have to remove the first line break after the TMPL:DEF. See the CommentPluginTemplate for examples of how comment template definitions should look like in TWiki-4.1.X
An example: A CommentPlugin template that adds a comment as appending a row to a table. Before the spec change this would work.
<verbatim> %TMPL:DEF{OUTPUT:tabletest}%%POS:BEFORE% |%URLPARAM{"comment"}%| -- %WIKIUSERNAME% - %DATE% | %TMPL:END% </verbatim>From Twiki 4.1.0 the old template definition will add an empty line before the new table row. To fix it simply remove the new line before the table.
<verbatim> %TMPL:DEF{OUTPUT:tabletest}%%POS:BEFORE%|%URLPARAM{"comment"}%| -- %WIKIUSERNAME% - %DATE% | %TMPL:END% </verbatim>The advantage of the spec change is that now you can add leading and trailing white space including new lines. This was not possible before.
{PassthroughDir}
and {Sessions}{Dir}
were by default set to /tmp
. These config settings have been replaced by {TempfileDir}
with the default setting value /tmp/twiki
. If the twiki
directory does not exist twiki will create it first time it needs it.
It is highly recommended no longer to use the tmp directory common to other web applications and the new default will work fine for most. You may want to delete all the old session files in /tmp after the upgrade to 4.1.1. They all start with cgisess_. It is additionally highly recommended to limit write access to the {TempfileDir}
for security reasons if you have non-admin users with login access to the webserver just like you would do with the other webserver directories.
NewUserTemplate
and UserForm
.
The NewUserTemplate
was located in the TWiki web and the UserForm
in the Main web. When upgrading TWiki these were some of the topics you had to take care not to overwrite.
From 4.2.0 the UserForm
and NewUserTemplate
are distributed in the TWiki web. If you create the two in the Main web the Main web version will be used instead. So if you tailor the user topic format or the form then you should always copy the two files to the Main web and modify the ones in the Main web. When you later upgrade TWiki your tailored template and form will not be overwritten.
Main.TWikiUsers
topic contains all the registered users. It is a topic you do not want to overwrite when you upgrade TWiki.
From 4.2.0 this file is no longer included in the TWiki distribution. When you register the first time TWiki creates the Main.TWikiUsers
topic in the Main web if it does not exist already. This means that you can now upgrade TWiki without risk of overwriting the important TWikiUsers
topic.
working
directory working
directory which by default is located in the twiki root, has been introduced which contains:
{WorkingDir}
defines the container directory for temporary files, extensions' work areas, and intermediate registration data. The default is working
under your installation root.
Take care for that change if you run your own routine to delete obsolete session files, which will now be found under working/tmp/cgisess*
.
FirstName
to First Name
(no change in %META:FIELD name
)
LastName
to Last Name
(no change in %META:FIELD name
)
OrganisationName
to Organization
OrganisationURL
to URL
Profession
to Titles
VoIP
to Skype ID
State
to Region
Address
InstantMessaging (IM)
HomePage
Comment
Department
Status Update
* Set DENYTOPICVIEW =
(nothing) in a topic means deny nobody the topic view. The reason for this behavior is that it allows public access to a topic in a restricted web, e.g. having * Set ALLOWWEBVIEW = Main.VipGroup
in WebPreferences. This is not symmetric with the fact that an empty DENYWEBVIEW is the same as an undefined DENYWEBVIEW, hence confusing.
From TWiki 6.0 on, an empty DENYTOPICVIEW means the same as not defined. To open up a topic in a restricted web, you need to use * Set ALLOWTOPICVIEW = Main.AllUsersGroup
. The Main.AllUsersGroup is new. It is a pseudo group containing all authenticated and unauthenticated users. You can use Main.AllAuthUsersGroup if you want to specify all authenticated users.
To keep publicly accessible topics in restricted webs publicly accessible, the tools/eliminate_emptydenytopic
script is provided, which replaces * Set DENYTOPIC<action> =
with * Set ALLOWTOPIC<action> = Main.AllUsersGroup
in all topics in all webs.
Note: See more changes since TWiki-6.0.0 in TWikiReleaseNotes06x00.
Back to top
.htpasswd
files on the server. These files can be unique to TWiki, or can be shared with other applications (such as an Apache webserver). A variety of password encodings are supported for flexibility when re-using existing files. See the descriptive comments in the Security Settings section of the configure interface for more details.
You can easily plug in alternate password management modules to support interfaces to other third-party authentication databases.
Main/WebPreferences
. By doing so, new users are able to register without any errors.
none
in configure) TWiki::LoginManager::TemplateLogin
in configure) TWiki::LoginManager::TemplateLogin
login manager (on the Security Settings pane).
{TemplateLogin}{PreventBrowserRememberingPassword}
that you can set to prevent browsers from remembering usernames and passwords if you are concerned about public terminal usage.
.htpasswd
files, check that a new line with the username and encrypted password is added to the .htpasswd
file. If not, you probably got a path wrong, or the permissions may not allow the webserver user to write to that file.
pub
area, unless they are only accessed through the viewfile
script. If your pub
directory is set up in the webserver to allow open access you may want to add .htaccess
files in there to restrict access.
You can create a custom version of the TWikiRegistration form by copying the topic, and then deleting or adding input tags in your copy. The name=""
parameter of the input tags must start with: "Twk0..."
(if this is an optional entry), or "Twk1..."
(if this is a required entry). This ensures that the fields are carried over into the user profile page correctly. Do not modify the version of TWikiRegistration shipped with TWiki, as your changes will be overwritten next time you upgrade.
The default new user template page is in TWiki.NewUserTemplate. The same variables get expanded as in the template topics. You can create a custom new user profile page by creating the Main.NewUserTemplate topic, which will then override the default.
TWiki::LoginManager::ApacheLogin
in configure) REMOTE_USER
environment variable, which the webserver passes to TWiki when you enable authentication in the webserver (as described in RFC 3875 - "The Common Gateway Interface v1.1").
The advantage of this scheme is that if you have an existing website authentication scheme using Apache modules, such as mod_authnz_ldap
or mod_authn_dbd
, 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::LoginManager::ApacheLogin
login manager.
.htpasswd
entries.
.htaccess
file in the twiki/bin
directory.twiki/bin/.htaccess.txt
that you can copy and change. The comments in the file explain what needs to be done..htaccess
does not have the desired effect, you may need to "AllowOverride All" for the directory in httpd.conf
(if you have root access; otherwise, e-mail web server support) pub
area, unless they are only accessed through the viewfile
script. If your pub
directory is set up to allow open access you may want to add .htaccess
files in there as well to restrict access
name=""
parameter of the input tags must start with: "Twk0..."
(if this is an optional entry), or "Twk1..."
(if this is a required entry). This ensures that the fields are carried over into the user profile page correctly. Do not modify the version of TWikiRegistration shipped with TWiki, as your changes will be overwritten next time you upgrade. .htpasswd
file. If not, you may have got a path wrong, or the permissions may not allow the webserver user to write to that file.
bin/logon
script enables this. If you are using Apache Login, the bin/logon
script must be setup in the bin/.htaccess
file to be a script which requires a valid user
. Once authenticated, it will redirect the user to the view URL for the page from which the logon
script was linked.
%SESSION_VARIABLE{ "varName" }% |
Read a session variable |
%SESSION_VARIABLE{ "varName" set="varValue" }% |
Set a session variable |
%SESSION_VARIABLE{ "varName" clear="" }% |
Clear a session variable |
%SESSION_VARIABLE{"AUTHUSER"}%
- user ID, current value:
%SESSION_VARIABLE{"SESSION_REQUEST_NUMBER"}%
- number of pages accessed by current user since login, current value:
pthoeny
. This name is normally passed to TWiki by the REMOTE_USER
environment variable, and used internally. Login Usernames are maintained by your system administrator.
PeterThoeny
, is recorded when you register using TWikiRegistration; doing so also generates a user profile page in the Main web.
NOTE: To correctly enter a WikiName - your own or someone else's - be sure to include the Main web name in front of the Wiki username, followed by a period, and no spaces, for exampleMain.WikiUsername
or%USERSWEB%.WikiUsername
. This pointsWikiUsername
to the Main web, where user profile pages are located, no matter which web it's entered in. Without the web prefix, the name appears as a NewTopic everywhere but in the Main web.
TWiki/ChangePassword
)
TWiki/ResetPassword
)
TWiki/ChangeEmailAddress
)
.htaccess
Web | Sitemap | VIEW | CHANGE | RENAME | |||
---|---|---|---|---|---|---|---|
Listed | DENY | ALLOW | DENY | ALLOW | DENY | ALLOW | |
Main | on | ||||||
TWiki | on | TWikiAdminGroup | TWikiAdminGroup | ||||
Omega34 | on | ||||||
Sandbox | on |
Main
web. To create a new group, visit TWikiGroups and enter the name of the new group ending in Group
into the "new group" form field. This will create a new group topic with two important settings: Set GROUP = < list of Users and/or Groups >
Set ALLOWTOPICCHANGE = < list of Users and/or Groups >
Set GROUP = SomeUser, OtherUser, SomeGroup
Set ALLOWTOPICCHANGE = MarketingGroup
TWikiAdminGroup
. The system administrator may have chosen a different name for this group if your local TWiki uses an alternate group mapping manager but for simplicity we will use the default name TWikiAdminGroup in the rest of this topic.
You can create new administrators simply by adding them to the TWikiAdminGroup topic. For example, Set GROUP = RobertCailliau, TimBernersLee
Set DENYWEBVIEW = < comma-delimited list of Users and Groups >
Set ALLOWWEBVIEW = < comma-delimited list of Users and Groups >
Set DENYWEBCHANGE = < comma-delimited list of Users and Groups >
Set ALLOWWEBCHANGE = < comma-delimited list of Users and Groups >
Set DENYWEBRENAME = < comma-delimited list of Users and Groups >
Set ALLOWWEBRENAME = < comma-delimited list of Users and Groups >
Set ALLOWWEBVIEW = Main.MarketingGroup
ALLOWWEBVIEW
set, this will also apply to the subweb. Also note that you will need to ensure that the parent web's FINALPREFERENCES
does not include the access control settings listed above. Otherwise you will not be able override the parent web's access control settings in sub-webs.
Creation and renaming of sub-webs is controlled by the WEBCHANGE setting on the parent web (or ROOTCHANGE for root webs). Renaming is additionally restricted by the setting of WEBRENAME in the web itself.
Note: If you restrict access to the Main, make sure to add the TWikiRegistrationAgent
so that users can register. Example: Set ALLOWWEBCHANGE = TWikiAdminGroup, TWikiRegistrationAgent
Set DENYTOPICVIEW = < comma-delimited list of Users and Groups >
Set ALLOWTOPICVIEW = < comma-delimited list of Users and Groups >
Set DENYTOPICCHANGE = < comma-delimited list of Users and Groups >
Set ALLOWTOPICCHANGE = < comma-delimited list of Users and Groups >
Set DENYTOPICRENAME = < comma-delimited list of Users and Groups >
Set ALLOWTOPICRENAME = < comma-delimited list of Users and Groups >
Set ALLOWTOPICVIEW = Main.MarketingExecGroup
Set ALLOWTOPICVIEW = Main.AllUsersGroup
Set ALLOWTOPICVIEW = Main.AllAuthUsersGroup
Set ALLOWTOPICOPERATION = Main.AllUsersGroup
tools/eliminate_emptydenytopic
is provided.
After upgrading from pre 6.0 to post 6.0, you need to run it.
Set ALLOWTOPICVIEW =
viewfile
script, which honors the TWiki access controls settings to topics. See the notes below for implications.
The preferred method to secure attachments is by editing the twiki.conf
file to include:
ScriptAlias /do /filesystem/path/to/twiki/bin Alias /pub/TWiki /filesystem/path/to/twiki/pub/TWiki Alias /pub/Sandbox /filesystem/path/to/twiki/pub/Sandbox ScriptAlias /pub /filesystem/path/to/twiki/bin/viewfileNotes:
viewfile
script. The TWiki web and Sandbox web are excluded for performance reasons.
viewfile
script sets the mime type based upon file name suffix. Unknown types are served as text/plain which can result in corrupt files.
Set DENYROOTCHANGE = < comma-delimited list of Users and Groups >
Set ALLOWROOTCHANGE = < comma-delimited list of Users and Groups >
ROOTCHANGE
access to rename an existing top-level web. You just need WEBCHANGE
in the web itself.
Set DENYTOPIC =
) canCreateWeb($cUID, $web)
method of the user mapping manager is called if the method exists.
If it returns true, TWiki goes ahead and create the web without checking access control variables.
Please read AllowWebCreateByUserMappingManager for more details.
{ForbidUserAction}
.
A good example is worth more than a lengthy explanation, so here it is:
$TWiki::cfg{ForbidUserAction} = ' AggresiveCrawler: edit, oops, search; ReadOnlyUser: !view, viewfile; TotallyForbidden: !nothing; ';In this example:
!
, only the listed scripts are permitted for the user. !
at the beginning of the list negates the list.
DYNAMIC_ACCESS_CONTROL
'on' at WebPreferences of the web, TWiki variables in access control variables mentioned above are expanded.
* Set DYNAMIC_ACCESS_CONTROL = on * Set ALLOWWEBCHANGE = %IF{"'%CALCULATE{$SUBSTRING(%TOPIC%, -6, 6)}%' = 'Public'" then="%WIKINAME%" else="CroniesGroup"}%
* Set DYNAMIC_ACCESS_CONTROL = on * Set ALLOWWEBVIEW = %IF{"'%CALCULATE{$SUBSTRING(%TOPIC%, 1, 6)}%' = 'ReqEnt' and '%FORMFIELD{Requestor}%' != '%WIKINAME%'" then="SupportGroup" else="%WIKINAME%"}%Specifically the following access control variables are subject to TWiki variable expansion in their values.
* Set DYNAMIC_ACCESS_CONTROL = on * Set MEMBERS = JaneSmith, JoeSchmoe * Set ALLOWWEBVIEW = %MEMBERS%This is not a good way to use dynamic access control but it does restrict access only to those listed in MEMBERS. However, access control doesn't work as expected when WebA.TopicB is accessed from WebC.TopicD by
%INCLUDE{WebA.TopicB}%
or other variables.
This is because %MEMBERS%
is defined in WebA and may have a different value in other webs.
You may think the following lines cheat the access control on WebA but actually not.
* Set MEMBERS = %WIKINAME% %INCLUDE{WebA.TopicB}%This is because when a topic (e.g. WebC.TopicD) is accessed from browser and the topic refers to another topic in a different web (e.g. WebA.TopicB) and the different web employs dynamic access control, access to another topic is defined being on the safer side.
* Set MEMBERS = JaneSmith, JoeSchmoe * Set ALLOWTOPICVIEW = %MEMBERS%[This is not a good way to use dynamic access control
lib/LocalSite.cfg
$TWiki::cfg{DemoteUserPreferences}= 1;and having the following line on your WebPreferences and then finalise
DENYUSERPREFEENCES
.
* Set DENYUSERPREFEENCES = allPlease read TWikiVariables#ControllingUserLevelPrefsOverride for details. Again by default, predefined variables such as
%IF{...}%
can be overridden by preferences variables.
If user preferences are disabled, ordinary users cannot attack using user preferences, but topic level preferences may cause unexpected consequences.
As such, all predefined variables need to be made un-overridable by having the following line on WebPreferences and then finalise OVERRIDABLEPREDEFINEDVARIABLES
.
* Set OVERRIDABLEPREDEFINEDVARIABLES =Please read TWikiVariables#PredefinedVariables for details.
TOPIC_ACCESS_CONTACT
varialbe on WebPreferences. e.g.
* Set TOPIC_ACCESS_CONTACT = If you need to access this site, please apply [[Main.AccessForm][here]]Please note that setting it on a topic other than WebPreferences does not take effect. This is a limitation of the current implementation.
USER:userid
and LDAPGROUP:group-name
and use them for access control. For example:
* Set ALLOWWEBCHANGE = USER:buzz, LDAPGROUP:foo-barIn a large organization, TWiki may need to depend on user and group data provided by its infrastructure. Custom user/group notations are handy in such situations though it's not trivial to implement. Please read here for details.
backuprestore
, configure
, login
, logon
and resetpasswd
with the following configure setting: $TWiki::cfg{AuthScripts} = 'attach, changes, edit, manage, oops, preview, rdiff, rdiffauth, register, rename, rest, save, search, twiki_cgi, upload, statistics, view, viewauth, viewfile';
twiki/bin
also to the {AuthScripts}
configure setting. twiki/bin
and twiki/pub
directories to all but valid users. In the Apache config file for TWiki (twiki.conf
or .htaccess
), replace the <FilesMatch "(attach|edit|...
section with this:
<FilesMatch ".*"> require valid-user </FilesMatch>Notes:
Set DENYWEBVIEW = < list of Users and Groups >
Set ALLOWWEBVIEW = < list of Users and Groups >
DENYWEBVIEW
is evaluated before ALLOWWEBVIEW
. Access is denied if the authenticated person is in the DENYWEBVIEW
list, or not in the ALLOWWEBVIEW
list. Access is granted if DENYWEBVIEW
and ALLOWWEBVIEW
are not defined.
Edit topic preference settings
under More topic actions
menu. Preferences set in this manner are not visible in the topic text, but take effect nevertheless. Access control settings added as topic preference settings are stored in the topic meta data and they override settings defined in the topic text.
Alternatively, place them in HTML comment markers, but this exposes the access setting during ordinary editing.
<!--
* Set DENYTOPICCHANGE = Main.SomeGroup
-->
all webs
search option from accessing obfuscated webs. Do so by enabling the NOSEARCHALL
variable in WebPreferences: Set NOSEARCHALL = on
$TWiki::cfg{Access}{Topic}{WebAutomation} = { DENYCHANGE => 'Main.AllUsersGroup', };In addition to
ALLOWCHANGE
, you can sepcify DENYCHANGE
, ALLOWVIEW
, DENYVIEW
, ALLOWRENAME
, and DENYRENAME
as follows.
$TWiki::cfg{Access}{Topic}{SpecialTopic} = { DENYVIEW => 'JoeSchmoe', ALLOWVIEW => 'FooGroup', };
$TWiki::cfg{Access}{Topic}{TOPICNAME}
has precedence over DENYTOPIC*
and ALLOWTOPIC*
.
For example, if the configuration for WebAutomation is there as above, there is no way to allow non-adminsitrators to change the WebAutomation topic of any web.
As a way to configure access control, this may look crude.
The reason why configured this way is that this can be part of plugin/add-on/contrib's configuration.
For example, Config.spec
of AutomationAddOn would have the following lines, with which proper access control to WebAutomation topics is implemented without the administrator knowing it.
$TWiki::cfg{Access}{Topic}{WebAutomation} = { DENYCHANGE => 'Main.AllUsersGroup', };Back to top
Formatting Command: | You write: | You get: | |||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Paragraphs: Blank lines will create new paragraphs. |
1st paragraph 2nd paragraph | 1st paragraph 2nd paragraph | |||||||||||||||||||||||||||
Headings: Three or more dashes at the beginning of a line, followed by plus signs and the heading text. One plus creates a top level heading, two pluses a second level heading, etc. The maximum heading depth is 6. You can create a table of contents with the %TOC% variable. If you want to exclude a heading from the TOC, put !! after the ---+ .
Empty headings are allowed and won't appear in the table of contents. |
---++ Sushi ---+++ Maguro ---+++!! Not in TOC |
SushiMaguroNot in TOC |
|||||||||||||||||||||||||||
Bold Text: Words get shown in bold by enclosing them in * asterisks.
|
*Bold* | Bold | |||||||||||||||||||||||||||
Italic Text: Words get shown in italic by enclosing them in _ underscores.
|
_Italic_ | Italic | |||||||||||||||||||||||||||
Bold Italic: Words get shown in bold italic by enclosing them in __ double-underscores.
|
__Bold italic__ | Bold italic | |||||||||||||||||||||||||||
Fixed Font: Words get shown in fixed font by enclosing them in = equal signs.
|
=Fixed font= |
Fixed font
|
|||||||||||||||||||||||||||
Bold Fixed Font: Words get shown in bold fixed font by enclosing them in double equal signs.
|
==Bold fixed== |
Bold fixed
|
|||||||||||||||||||||||||||
You can follow the closing bold, italic, or other (* _ __ = == ) indicator
with normal punctuation, such as commas and full stops.
Make sure there is no space between the text and the indicators. All words enclosed by the indicators need to be on the same line. |
_This works_, _this does not _ _this fails too_ |
This works, _this does not _ _this fails too_ |
|||||||||||||||||||||||||||
Separator (Horizontal Rule): Three or more three dashes at the beginning of a line.. |
------- |
|
|||||||||||||||||||||||||||
Bulleted List: Multiple of three spaces, an asterisk, and another space. For all the list types, you can break a list item over several lines by indenting lines after the first one by at least 3 spaces. |
* level 1 * level 2 * back on 1 * A bullet broken over three lines * last bullet |
|
|||||||||||||||||||||||||||
Icon List: Multiple of three spaces, an asterisk, text icon:name and another space.
Use the name of any TWikiDocGraphics icon.
|
* icon:tip Icon list * icon:led-red Full * icon:led-green OK * icon:unchecked Item 1 * icon:checked Item 2 * icon:empty No 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, |>> ... <<| multi-line syntax, 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 |>> | Nested | | table | <<| 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 | |||||||||||||||||||||||||||
External Links: URLs starting with file , ftp , gopher , http , https , irc , mailto , news , nntp and telnet are linked automatically if preceded by whitespace or parenthesis. External links are indicated with a trailing icon, and open up in a new browser tab or window; the behavior of both can be set in configure or preferences variables (see TWikiExternalLinks for details). Links can be prevented with an ! exclamation point prefix.
|
http://twiki.org https://google.com !http://escaped-link | http://twiki.org https://google.com http://escaped-link | |||||||||||||||||||||||||||
Forced Links: Use double square brackets to create forced links: Write [[link]] or [[link][label]] to force a link. Use the former for singleton words and if automatic linking is disabled. Use the latter one to specify a link label other than the link. For the link, you can use internal link references (e.g. WikiWords) and URLs (e.g. http://TWiki.org/).
URL parameters can follow a WikiWord Anchor names can be added to create a link to a specific place in a document. To "escape" double square brackets that would otherwise make a link, prefix the leading left square bracket with an exclamation point. The topic title instead of the topic name is shown for [[WikiWord]] links if the SHOWTOPICTITLELINK preferences setting is enabled.
|
[[WikiWord]] [[WikiWord?n1=v1;n2=v2]] [[WikiWord#TheAnchor]] [[WikiWord?n=5#TheAnchor]] [[WikiSyntax][wiki syntax]] [[http://gnu.org/][GNU]] [[Singleton]] escaped: ![[WikiSyntax]] | WikiWord WikiWord?n1=v1;n2=v2 WikiWord#TheAnchor WikiWord?n=5#TheAnchor wiki syntax GNU Singleton escaped: [[WikiSyntax]] | |||||||||||||||||||||||||||
Topic Title Links: Use double square brackets and a plus sign to create links with topic title: Write [[+TopicName]] or [[+Web.TopicName]] to show the topic title instead of the topic name. The topic title is defined by the form field named "Title", the topic preferences setting named TITLE, or the topic name if neither exists.
An alternative syntax is [[TopicName][$topictitle]] or [[Web.TopicName][$topictitle]] .
|
[[+BugN1234]] [[+Bugs.BugN1234]] [[BugN1234][$topictitle]] | The sky is falling The sky is falling The sky is falling | |||||||||||||||||||||||||||
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 | |||||||||||||||||||||||||||
Twitter Links: @twitter IDs are linked automatically. The link rule is defined by the {Links}{TwitterUrlPattern} configure setting.
|
@twiki | @twiki | |||||||||||||||||||||||||||
Verbatim Text: Surround code excerpts and other formatted text with <verbatim> and </verbatim> tags.
The verbatim tag disables HTML code. Use <pre> and </pre> tags instead if you want the HTML code within the tags to be interpreted.
Preferences variables (* Set NAME = value) are set within verbatim tags. |
<verbatim> class CatAnimal { void purr() { <code here> } } </verbatim> |
class CatAnimal { void purr() { <code here> } } |
|||||||||||||||||||||||||||
Literal Text: TWiki generates HTML code from TWiki shorthand. Experts surround anything that must be output literally in the HTML code, without the application of TWiki shorthand rules, with <literal>..</literal> tags.
Any HTML within literal tags must be well formed i.e. all tags must be properly closed before the end of the literal block. TWiki Variables are expanded within literal blocks. |
<literal> | Not | A | Table | <literal> |
| Not | A | Table | | |||||||||||||||||||||||||||
Protected Text: Experts protect text from mangling by WYSIWYG editors using <sticky>..</sticky> tags. Sticky tags don't have any effect on normal
topic display; they are only relevant when content has to be
protected from a WYSIWYG editor (usually because it isn't well-formed HTML, or because it
is HTML that WYSIWYG would normally filter out or modify). Protected
content appears as plain text in the WYSIWYG editor.
|
<sticky> <div> This div is required </div> </sticky> |
This div is required
|
<strike>deleted text</strike>
to get <literal>..</literal>
tags around blocks of HTML to avoid accidental interpretation of TWiki shorthand within the HTML.
<body>
and </body>
tags.
<p />
paragraph tags on empty lines, which causes problems if done between HTML tags that do not allow paragraph tags, like for example between table tags.
<...>
- of a HTML tag are on the same line, or the tag will be broken.
JavaScript Example: | CSS Example: |
---|---|
<!-- <pre> --> <script language="javascript"> <!-- // put your JavaScript code here //--> </script> <!-- </pre> --> |
<!-- <pre> --> <style type="text/css"> /* put your CSS code here */ </style> <!-- </pre> --> |
http://...
, https://...
, ftp://...
, gopher://...
, news://...
, file://...
, telnet://...
and mailto:...@...
are linked automatically.
[[URL][label]]
to get an external link with a descriptive text for the link, such as [[http://google.com/][Google home page]]
to get Google home page.
name@domain.com
are linked automatically.
%TOPIC%
is expanded to TWikiVariablesQuickStart. Some variables can take arguments in curly braces - for example, %INCLUDE{"OtherTopic" arg="value"}%
.
Many TWiki variables are built-in, and others are predefined for your convenience. TWikiVariables describes how you can also define your own TWiki Variables at the entire site, individual web, or individual topic level. Variables are fully expanded before any of the TWiki text formatting rules are applied.
Commonly used variables:
%TOC%
: Automatically generates a table of contents based on headings in a topic - see the top of this page for an example.
%WEB%
: The current web, is TWiki.
%TOPIC%
: The current topic name, is TWikiVariablesQuickStart.
%ATTACHURL%
: The attachment URL of the current topic. Example usage: If you attach a file to a topic you can refer to it as %ATTACHURL%/image.gif
to show the URL of the file or the image in your text.
%INCLUDE{"SomeTopic"}%
: Server side include, includes another topic. The current web is the default web. Example: %INCLUDE{"TWiki.SiteMap"}%
%SEARCH{"sushi"}%
: Inline search showing the search result embedded in a topic. FormattedSearch gives you control over formatting, used to create web-based applications.
%ICON{"help"}%
, %ICON{"tip"}%
, and %ICON{"warning"}%
to get: , , and , respectively.
!%SOMEVARIABLE%
to get: %SOMEVARIABLE%.
%PLUGINDESCRIPTIONS%
:
"$SUM( $ABOVE() )"
to TWiki tables or anywhere in topic text ExternalSite:Page
to link to a page on an external site based on aliases defined in a rules topic :-)
as or :eek:
as <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, e.g. '©'
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:
%T%
renders as
%CALCULATE{}%
is handled by the SpreadSheetPlugin
Categories:
|
Variables:
|
%T%
to get (a preferences variable)
%TOPIC%
to get TWikiVariables
(a predefined variable)
%CALCULATE{ "$UPPER(Text)" }%
to get TEXT
(a variable defined by a plugin)
!%TOPIC%
to get %TOPIC%
%ALLVARIABLES%
to get a full listing of all variables defined for a particular topic
%MYVAR%
, %MyVar%
, %My2ndVar%
, and %My_Var%
are valid names. Variables are case sensitive, e.g. %MyVAR%
and %MYVAR%
are not the same.
By convention all settings, predefined variables and variables handled by extensions are always UPPER-CASE.
%USERPREFSTOPIC%
in the user's subweb is read instead
$TWiki::cfg{DemoteUserPreferences}
is true, this step is deferred to a later step. On this TWiki installation, $TWiki::cfg{DemoteUserPreferences}
is false
EXTRAPREFERENCES
is defined at this point, it's regarded as having comma separated list of topics. Those topics are read in the listed order as if they were WebPreferences
$TWiki::cfg{DemoteUserPreferences}
is true as mentioned at the step 4
preview
will show the wrong thing, and you must save
the topic to see it correctly.
The syntax for setting variables is the same anywhere in TWiki (on its own TWiki bullet line, including nested bullets): [multiple of 3 spaces] * [space] Set [space] VARIABLENAME [space] = [space] value
Examples:
* Set VARIABLENAME1 = value * Set VARIABLENAME2 = valueSpaces between the = sign and the value will be ignored. You can split a value over several lines by indenting following lines with spaces - as long as you don't try to use * as the first character on the following line. Example:
* Set VARIABLENAME = value starts here and continues hereWhatever you include in your variable will be expanded on display, exactly as if it had been entered directly. Example: Create a custom logo variable
%MYLOGO%
, define the Variable on the web's WebPreferences topic, and upload a logo file, ex: mylogo.gif
. You can upload by attaching the file to WebPreferences, or, to avoid clutter, to any other topic in the same web, e.g. LogoTopic
. Sample variable setting in WebPreferences:
* Set MYLOGO = %PUBURL%/%WEB%/LogoTopic/mylogo.gifYou can also set preferences variables on a topic by clicking the link
Edit topic preference settings
under More topic actions
. Use the same * Set VARIABLENAME = value
syntax. Preferences set in this manner are not visible in the topic text, but take effect nevertheless.
$TWiki::cfg{DemoteUserPreferences}
has been introduced to avoid it.
If it's set to true, user level variables are set at the last step instead of the step 4.
But this is not enough.
To guarantee a certain result, you need to finalise critical preferences variables set at the web or topic level, which is cumbersome.
So preferences variables DENYUSERPREFEENCES
and ALLOWUSERPREFEENCES
have been introduced. DENYUSERPREFEENCES
and ALLOWUSERPREFEENCES
may have comma separated list of variable names
DENYUSERPREFEENCES
, the variable cannot be overridden at the user level. There is a special value "all", which means no preferences variables can be overridden at the user level
ALLOWUSERPREFEENCES
is set and not empty, only the listed preferences variables can be overridden. There is a special value "all", which means any preferences variable can be overridden at the user level. But actually, "all" is not necessary since a blank value or not setting ALLOWUSERPREFEENCES
has the same effect
DENYUSERPREFEENCES
takes precedence over ALLOWUSERPREFEENCES
. If a variable is listed on both, it cannot be overridden. If DENYUSERPREFEENCES
is "all", the value of ALLOWUSERPREFEENCES
doesn't matter.
* Set DENYUSERPREFERENCES = allIf you allow
INYMCEPLUGIN_DISABLE
and SKIN
to be set at the user level:
* Set ALLOWUSERPREFERENCES = TINYMCEPLUGIN_DISABLE, SKINIf you allow user preferences to set anything other than
TINYMCEPLUGIN_DISABLE
or SKIN
:
* Set DENYUSERPREFERENCES = TINYMCEPLUGIN_DISABLE, SKINPlease note
DENYUSERPREFEENCES
and ALLOWUSERPREFEENCES
affect user preferences regardless of $TWiki::cfg{DemoteUserPreferences}
.
You can set those variables at the site level while $TWiki::cfg{DemoteUserPreferences}
setting to false.
If you do so, you should finalise DENYUSERPREFEENCES
and ALLOWUSERPREFEENCES
.
Otherwise, they might be overridden by user preferences.
You will get the most benefit of DENYUSERPREFEENCES
and ALLOWUSERPREFEENCES
by setting $TWiki::cfg{DemoteUserPreferences}
to true.
That way, each web can specify how much user level preferences overriding is allowed.
* Set EXAMPLE = Example variable using %DEFAULT%, %PARAM1% and %PARAM2% * Set DEMO = Demo using %DEFAULT{ default="(undefined)" }%, %PARAM1{ default="(undefined)" }% and %PARAM2{ default="(undefined)" }%A special
%DEFAULT%
variable denotes the default (nameless) parameter of the calling variable. Variables optionally may list a default="..."
parameter that gets used in case the calling variable does not specify that parameter.
To use a parameterized variable (or call a macro), add parameters within the curly brackets, such as:
* %EXAMPLE{ "foo" PARAM1="bar" PARAM2="baz" }% * %DEMO{ "demo" PARAM2="parameter 2" }% -- note that PARAM1 is missingwhich resolves to:
%PARAM1%
gets expanded to bar
.
* Set DRINK = red wine * Set FAVORITE = My %DEFAULT{default="favorite"}% dish is %DISH{default="steak"}%, my %DEFAULT{default="favorite"}% drink is %DRINK%.The default can be defined with a default parameter (
%DISH{default="steak"}%
), or as a preferences setting (Set DRINK = ...
).
Use Variables:
%FAVORITE{ DISH="Sushi" DRINK="Sake" }%Returns:
%FAVORITE{}%Returns:
%FAVORITE{ "preferred" }%Returns:
Local
in place of Set
in the variable definition. For example, if the user sets the following in their home topic:
* Set EDITBOXHEIGHT = 10 * Local EDITBOXHEIGHT = 20Then when they are editing any other topic, they will get a 10 high edit box. However when they are editing their home topic, they will get a 20 high edit box.
Local
can be used wherever a preference needs to take a different value depending on where the current operation is being performed.
Use this powerful feature with great care! %ALLVARIABLES%
can be used to get a listing of the values of all variables in their evaluation order, so you can see variable scope if you get confused.
%BB%
- line break and bullet combined
%BB2%
- level 2 bullet with line break
%BB3%
- level 3 bullet with line break
%BB4%
- level 4 bullet with line break
%BR%
- line break
%BULLET%
- bullet sign
%CARET%
- caret symbol
%VBAR%
- vertical bar
%H%
- Help icon
%I%
- Idea icon
%M%
- Moved to icon
%N%
- New icon
%P%
- Refactor icon
%Q%
- Question icon
%S%
- Pick icon
%T%
- Tip icon
%U%
- Updated icon
%X%
- Alert icon
%Y%
- Done icon
%RED% text %ENDCOLOR%
- colored text (also %YELLOW%
, %ORANGE%
, %PINK%
, %PURPLE%
, %TEAL%
, %NAVY%
, %BLUE%
, %AQUA%
, %LIME%
, %GREEN%
, %OLIVE%
, %MAROON%
, %BROWN%
, %BLACK%
, %GRAY%
, %SILVER%
, %WHITE%
)
%REDBG% text %ENDBG%
- colored background (also %YELLOWBG%
, %ORANGEBG%
, %PINKBG%
, %PURPLEBG%
, %TEALBG%
, %NAVYBG%
, %BLUEBG%
, %AQUABG%
, %LIMEBG%
, %GREENBG%
, %OLIVEBG%
, %MAROONBG%
, %BROWNBG%
, %BLACKBG%
, %GRAYBG%
, %SILVERBG%
, %WHITEBG%
)
%SEARCH%
, are powerful and general tools.
%IF{...}%
, %SCRIPT{...}%
, and %INCLUDE{...}%
can be overridden
OVERRIDABLEPREDEFINEDVARIABLES
having a comma separated list of predefined variables specifies which predefined variables are overridable
*Set OVERRIDABLEPREDEFINEDVARIABLES =
DATE
and LANGUAGE
predefined variables can be overridden but all the other predefined variables cannot*Set OVERRIDABLEPREDEFINEDVARIABLES = DATE, LANGUAGE
%INCLUDINGTOPIC%
, %INCLUDE%
, and the mighty %SEARCH%
.
Var<name>
in the TWiki web. For example, a %LIGHTSABER%
variable has a documentation topic called VarLIGHTSABER. The topic is expected to have a specific format so that reports in this TWikiVariables topic, in TWikiVariablesSearch and in category topics work as expected.
Basic structure of a variable documentation topic:
#VarLIGHTSABER
---+++
(level 3) heading with variable name, --
, short description
Syntax:
bullet with example syntax
Parameters:
bullet with a table explaining the parameters (optional)
Example:
bullet or two with examples
Expands to:
bullet with expanded variable (optional)
Note:
bullet with notes (optional)
Category:
bullet with one or more of the TWiki variables categories:Related:
bullet with related links. Links have conditional IF so that links work properly locally in variable documentation topics and in the TWikiVariables topic
VarLIGHTSABER
topic:
#VarLIGHTSABER ---+++ LIGHTSABER -- laser sword to fend of unethical competition * The =%<nop>LIGHTSABER{}%= variable is handled by the LightsaberPlugin. * Syntax: =%<nop>LIGHTSABER{ _parameters_ }%= * Parameters: | *Parameter* | *Description* | *Default* | | =color="..."= | Color: =red=, =glue=, =green= | =white= | | =sound="..."= | Sound: =none=, =standard=, =loud= | =none= | * Example: =%<nop>LIGHTSABER{ color="red" }%= shows a red Lightsaber * Expands to: =%LIGHTSABER{ color="red" }%= * Note: The Lightsaber is a fictional weapon in the Star Wars universe, a "laser sword." * Category: FormattingAndRenderingVariables, UIAndVisualizationVariables * Related: [[%IF{"'%INCLUDINGTOPIC%'='TWikiVariables'" then="#"}%VarPLASMA][PLASMA]], LightsaberPluginBack to top
%SEARCH{...}%
is a table consisting of topic names and topic summaries. Use the format="..."
parameter to customize the search result. The format parameter typically defines a bullet or a table row containing variables, such as %SEARCH{ "food" format="| $topic | $summary |" }%
. See %SEARCH{...}%
for other search parameters, such as separator=""
.
header="..."
parameter header="| *Topic:* | *Summary:* |"
Variables that can be used in the header string:
Name: | Expands To: |
---|---|
$web |
Name of the web |
$n or $n() |
New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() |
Is a "no operation". This variable gets removed; useful for nested search |
$quot or \" |
Double quote (" ) |
$aquot |
Apostrophe quote (' ) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
$lt |
Less than sign (< ) |
$gt |
Greater than sign (> ) |
format="..."
parameter format="| $topic | $summary |"
Variables that can be used in the format string:
Name: | Expands To: |
---|---|
$web |
Name of the web |
$topic |
Topic name |
$topic(20) |
Topic name, "- " hyphenated each 20 characters |
$topic(30, -<br />) |
Topic name, hyphenated each 30 characters with separator "-<br />" |
$topic(40, ...) |
Topic name, shortened to 40 characters with "..." indication |
$topictitle |
Topic title, in order of sequence defined by: Form field named "Title", topic preference setting named TITLE, topic name |
$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. |
$text(encode:type) |
Same as above, but encoded in the specified type. Possible types are the same as in ENCODE. Though ENCODE can take the extra parameter, $text(encode:type) cannot. Example: $text(encode:html) |
$locked |
LOCKED flag (if any) |
$date |
Time stamp of last topic update, e.g. 2024-11-05 - 12:23 |
$isodate |
Time stamp of last topic update, e.g. 2024-11-05T12:23Z |
$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 TWiki variables, 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(expandvar) |
Topic summary, with %ALLTWIKI{...}% variables expanded |
$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, encode:type) |
Form field value, encoded in the specified type. Possible types are the same as in ENCODE: quote , moderate , safe , entity , html , url and csv . The encode:type parameter can be combined with other parameters described below, but it needs to be the last parameter. Example: $formfield(Description, 20, encode:html) |
$formfield(name, render:display) |
Form field value, rendered for display. For example, a form field of type color will render as a colored box. If not specified, the raw value is returned, such as a color value #336699 . The render:display parameter can be combined with other parameters, but must be used after the parameters described below. |
$formfield(name, 10) |
Form field value, "- " hyphenated each 10 characters |
$formfield(name, 20, -<br />) |
Form field value, hyphenated each 20 characters with separator "-<br />" |
$formfield(name, 30, ...) |
Form field value, shortened to 30 characters with "..." indication |
$query(query-syntax) |
Access topic meta data using SQL-like QuerySearch syntax. Example: • $query(attachments.arraysize) returns the number of files attached to the current topic • $query(attachments[name~'*.gif'].size) returns an array with size of all .gif attachments, such as 848, 1425, 923 • $query(parent.name) is equivalent to $parent |
$query(query-syntax, quote:") |
Strings in QuerySearch result are quoted with the specified quote. Useful to triple-quote strings for use in SpreadSheetPlugin's CALCULATE, such as $query(attachments.comment, quote:''') which returns a list of triple-quoted attachment comment strings -- the spreadhseet funcions will work properly even if comment strings contain commas and parenthesis |
$query(query-syntax, encode:type) |
QuerySearch result is encoded in the specified type. This is in parallel to $formfield(name, encode:type) mentioned above |
$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 |
$pattern(reg-exp, encode:type) |
A text extracted by reg-exp is encoded in the specified type. This is in parallel to $formfield(name, encode:type) mentioned above |
$count(reg-exp) |
Count of number of times a regular expression pattern appears in the text of a topic (does not search meta data). Follows guidelines for use and limitations outlined above under $pattern(reg-exp) . Example: $count(.*?(---[+][+][+][+]) .*) counts the number of <H4> headers in a page. |
$ntopics |
Number of topics found in current web. This is the current topic count, not the total number of topics |
$tntopics |
The total number of topics matched |
$nwebs |
The number of webs searched |
$nhits |
Number of hits if multiple="on" . Cumulative across all topics in current web. Identical to $ntopics unless multiple="on" |
$n or $n() |
New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() |
Is a "no operation". This variable gets removed; useful for nested search |
$quot or \" |
Double quote (" ) |
$aquot |
Apostrophe quote (' ) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
$lt |
Less than sign (< ) |
$gt |
Greater than sign (> ) |
footer="..."
parameter footer="| *Topic* | *Summary* |"
Variables that can be used in the footer string:
Name: | Expands To: |
---|---|
$web |
Name of the web |
$ntopics |
Number of topics found in current web |
$tntopics |
The total number of topics matched |
$nwebs |
The number of webs searched |
$nhits |
Number of hits if multiple="on" . Cumulative across all topics in current web. Identical to $ntopics unless multiple="on" |
$n or $n() |
New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() |
Is a "no operation". This variable gets removed; useful for nested search |
$quot or \" |
Double quote (" ) |
$aquot |
Apostrophe quote (' ) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
$lt |
Less than sign (< ) |
$gt |
Greater than sign (> ) |
default="..."
parameter default="| *Note* | Nothing found in the [[$web.WebHome][$web]] web |"
Variables that can be used in the default string:
Name: | Expands To: |
---|---|
$web |
Name of the web |
$n or $n() |
New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() |
Is a "no operation". This variable gets removed; useful for nested search |
$quot or \" |
Double quote (" ) |
$aquot |
Apostrophe quote (' ) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
$lt |
Less than sign (< ) |
$gt |
Greater than sign (> ) |
%SEARCH{}%
are evaluated once before the search. This is OK for variables that do not change, such as %SCRIPTURLPATH%
. Variables that should be evaluated once per search hit must be escaped. For example, to escape a conditional:
%IF{ "..." then="..." else="..." }%
format="$percntIF{ \"...\" then=\"...\" else=\"...\" }$percnt"
%SEARCH{ "FAQ" scope="topic" nosearch="on" nototal="on" header=" * *Topic: Summary:*" format=" * [[$topic]]: $summary" footer=" * *Topic: Summary*" }%To get this:
TopicClassification
field, an OperatingSystem
field and an OsVersion
field we could write:
| *Topic:* | *OperatingSystem:* | *OsVersion:* |
%SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" scope="text" type="regex" nosearch="on" nototal="on" format="| [[$topic]] | $formfield(OperatingSystem) | $formfield(OsVersion) |" }%
To get this:
Topic: | OperatingSystem | OsVersion |
---|---|---|
IncorrectDllVersionW32PTH10DLL | OsWin | 95/98 |
WinDoze95Crash | OsWin | 95 |
%SEARCH{ "__Back to\:__ TWikiFAQ" scope="text" type="regex" nosearch="on" nototal="on" header="TWiki FAQs:" format=" * $pattern(.*?FAQ\:[\n\r]*([^\n\r]+).*) [[$topic][Answer...]]" }%To get this: TWiki FAQs:
%SEARCH{ "culture" format=" * $topic is referenced by: (list all references)" nosearch="on" nototal="on" }%
%SEARCH{ "(topic found in first search)" format="$topic" nosearch="on" nototal="on" separator=", " }%
$percnt
to escape the leading percent of the second search
\"
to escape the double quotes
$dollar
to escape the $
of $topic
$nop
to escape the }%
sequence
%SEARCH{ "culture" format=" * $topic is referenced by:$n * $percntSEARCH{ \"$topic\" format=\"$dollartopic\" nosearch=\"on\" nototal=\"on\" separator=\", \" }$nop%" nosearch="on" nototal="on" }%To get this:
$dollarpercntSEARCH{
for level three, $dollardollarpercntSEARCH{
for level four, etc.
%SEARCH{ "\.*" scope="topic" type="regex" nosearch="on" nototal="on" sort="modified" reverse="on" format="| [[$topic]] | $wikiusername | $date |" limit="7" }%=To get this:
RegOmegaUser | SvenLofgren | 2019-08-27 - 19:13 |
TablePlugin | TWikiContributor | 2015-07-28 - 09:21 |
WebSearchAttachments | TWikiContributor | 2015-05-19 - 23:16 |
VarMETASEARCH | TWikiContributor | 2015-04-22 - 03:26 |
TopMenuSkinTopBar | TWikiContributor | 2014-06-19 - 03:01 |
TWikiDashboardAddOn | TWikiContributor | 2014-04-11 - 07:09 |
TWikiUserSetting | TWikiContributor | 2013-10-12 - 01:54 |
%CALCULATE{$SET(weekold, $TIMEADD($TIME(), -7, day))}%
%SEARCH{ "." scope="topic" type="regex" web="Main" nonoise="on" sort="modified" reverse="on" format="$percntCALCULATE{$IF($TIME($date) < $GET(weekold), <nop>, | [[$web.$topic][$topic]] | $wikiusername | $date | $rev |)}$percnt" limit="100" }%
weekold
variable to the serialized date of exactly one week ago
$percnt
makes sure that the CALCULATE gets executed once for each search hit
weekold
date
<nop>
is returned, which gets removed at the end of the TWiki rendering process
date="..."
paramter in SEARCH to restrict the date.
date=""
parameter as shown in the next example.
%SEARCH{ "." scope="topic" type="regex" web="%USERSWEB%" nonoise="on" sort="modified" reverse="on" format="| [[$web.$topic][$topic]] | $wikiusername | $date | $rev |" limit="100" date="P1w/$today" }%=To get this:
%URLPARAM{"..."}%
variable. Example:
Write this:
<form action="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%"> Find Topics: <input type="text" name="q" size="32" value="%URLPARAM{"q" encode="entity"}%" /> <input type="submit" class="twikiSubmit" value="Search" /> </form> Result: %SEARCH{ search="%URLPARAM{"q" encode="quote"}%" type="keyword" format=" * $web.$topic: %BR% $summary" nosearch="on" }%To get this: Result: Related Topics: UserDocumentationCategory, SearchHelp, VarSEARCH, VarENCODE, SearchResultsPagination, SearchPatternCookbook, RegularExpression, QuerySearch -- Contributors: TWiki:Main.PeterThoeny, TWiki:Main.CrawfordCurrie, TWiki:Main.SopanShewale Back to top
Attach
link at the bottom of the page. The Attach
screen lets you browse for a file, add a comment, and upload it. The uploaded file will show up in the File Attachment table. *.php
files are renamed to *.php.txt
so that no one can place code that would be read in a .php file.
%ATTACHFILESIZELIMIT%
variable of the TWikiPreferences, currently set at 10000 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 | History | Action | Size | Date | Who | Comment |
---|---|---|---|---|---|---|---|
txt | Sample.txt | manage | 0.1 K | 2000-07-22 - 19:37 | TWikiContributor | Just a sample | |
gif | Smile.gif | manage | 0.1 K | 2000-07-22 - 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
.
.txt
extension is appended to some filenames for security reasons
~
, $
, @
, %
are removed
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.
WebTopicEditTemplate
topic in a web, or a new topic that serves as an application specific template topic.
formtemplate
parameter in the (edit or save) URL. Initial values can then be provided in the URLs or as form values: name
, ex: ?BugPriority=1
namevalue=1
, ex: ?ColorRed=1
. <form name="newtopic" action="%SCRIPTURLPATH{"edit"}%/%WEB%/"> <input type="hidden" name="formtemplate" value="MyForm" /> New topic name <input type="text" name="topic" size="40" /> <input type="submit" class="twikiSubmit" value="Create" /> </form>
save
script instead of the edit
script in the form action. When you specify the save
script you have to use the "post" method. Example: <form name="newtopic" action="%SCRIPTURLPATH{"save"}%/%WEB%/" method="post"> ..... </form>
edit
and save
scripts understand many more parameters, see TWikiScripts#edit and TWikiScripts#save for details.
Name | Type | Size | Values | Tooltip message | Attributes |
---|
Name
, Type
and Size
columns are required. Other columns are optional. The form template must have a header row, e.g. at least | *Name* | *Type* | *Size* |
is required. Columns:
Name
is the name of the form field.
Type
, Size
and Value
describe the type, size and initial value of this form field. Type text
, checkbox
, select
and more are described in the Form Field Types section below.
Tooltip message
will be displayed when the cursor is hovered over the field in edit
view.
Attributes
may contain additional key="value" form field attributes, separated by space. hidden="1"
attribute indicates that this field is hidden, e.g. not shown in view mode. However, the field is available for editing and storing information. The deprecated H
attribute has the same function, it is still supported but might be removed in a future TWiki release. mandatory="1"
attribute 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. The deprecated M
attribute has the same function, it is still supported but might be removed in a future TWiki release.
onfocus="..."
and spellcheck=".."
.
| *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 | Values | Tooltip message | Attributes |
---|
Size
, Value
and Attributes
depend on the Type
used. Form field types:
Type | Description | Size | Value |
---|---|---|---|
text |
One-line text field | Text box width in number of characters | Initial (default) content |
textarea |
Multi-line text box | Columns x rows, such as 80x6 ; default is 40x5 |
Initial (default) content |
label |
Read-only text label | Text of the label | |
checkbox |
One or more checkboxes that can be toggled individually | Number of checkboxes shown per line | Comma-space-separated list of item labels - can be a dynamic SEARCH |
checkbox+buttons |
Like checkbox , adding [Set] and [Clear] buttons |
||
radio |
Radio buttons, mutually exclusive; only one can be selected | Number of radio buttons shown per line | Comma-space-separated list of item labels - can be a dynamic SEARCH |
combobox |
Text field & select combination box, rendered as a text input field and a button to open up a selector box | Text box width in number of characters | Comma-space-separated list of options of the select box - can be a dynamic SEARCH |
select |
Select box, rendered as a picklist or a multi-row selector box depending on the size value | • 1 : Show a picklist • Number > 1: Multi-row selector box of specified size • Range e.g. 3..10 : Multi-row selector box with variable size - the box will never be smaller than 3 items, never larger than 10, and will be 5 high if there are only 5 options |
Comma-space-separated list of options of the select box - can be a dynamic SEARCH |
select+multi |
Like select , turning multi-select on, to allow Shift+Click and Ctrl+Click to select (or deselect) multiple items |
||
select+values |
Like select , allowing definition of values that are different to the displayed text. An option is defined as value: title , where the value is the value passed on form submit, and title is the option text shown to the user. For example:| Field 9 | select+values | 3 | One, 2: Two, III: Three | Various values formats | shows but the values of options Two and Three are 2 and III , respectively. A legacy title=value syntax is supported as well, for example: One, Two=2, Three=III . |
||
select+multi+values |
Combination of select+multi and select+values |
||
color |
Single-line text box and a color picker to pick a color. The color can also be typed into the text box, such as #123456 . An attribute of type="popup" shows a button that, when clicked, opens a color picker popup. |
Text box width in number of characters | Initial (default) color |
date |
Text input field and a button next to it to pick a date from a pop-up calendar. The date can also be typed into the text box. | Text box width in number of characters | Initial (default) date |
text
type: id, max, maxlength, min, pattern, placeholder
textarea
type: autocomplete, id, maxlength, minlength, pattern, placeholder, wrap
label
type: id, max, maxlength, min
combobox
type: max, maxlength, min, pattern, placeholder
| *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.
TWIKIFORMPATH
variable.
It's referred to only when a form template is spcified without a web (TOPIC instead of WEB.TOPIC).
The webs in TWIKIFORMPATH
are examined in the listed order until the specified template is found.
TWIKIFORMPATH
may contain TWiki variables. For example:
* Set TWIKIFORMPATH = %APPLICATION_WEB%, %WEB%If
TWIKIFORMPATH
is defined, the current web is examined only if all the webs listed in it don't have the form template.
checkbox
+multi
anywhere in the name
form
(see details).
action=form
parameter to the edit URL string, such as%SCRIPTURL{edit}%/%BASEWEB%/%BASETOPIC%?t=%SERVERTIME{$epoch}%;action=form
(see details).
SubmitExpenseReport
topic where you can create new expense reports, a SubmitVacationRequest
topic, and so on. These can specify the required template topic with its associated form. Template topics has more.
A Form Template specifies the fields in a form. A Form Template is simply a page containing a TWiki table, where each row of the table specifies one form field.
%EDITFORMFIELD{ "form" type="start" action="save" topic="%BASETOPIC%" }% | Priority: | %EDITFORMFIELD{ "Priority" topic="%BASETOPIC%" }% | | Status: | %EDITFORMFIELD{ "Status" topic="%BASETOPIC%" }% | | | %EDITFORMFIELD{ "form" type="submit" value="Update" }% | %EDITFORMFIELD{ "LastUpdate" type="hidden" value="%SERVERTIME{$year-$mo-$day}%" }% %EDITFORMFIELD{ "form" type="end" }%Assuming the base topic has a BugForm with Priority and Status fields of type select, a LastUpdate field of type text, and some other fields. Above form shows a table with selectors for Priority and Status, and an Update button. On form submit, the Priority, Status and LastUpdate fields are updated in the base topic.
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" sort="modified" reverse="on" format="|<b>[[$web.$topic][$topic]]</b> |<nop>$formfield(TopicClassification) |" web="Sandbox"}%
text
fields when a topic is saved. If you need linefeeds in a field, make sure it is a textarea
.
.tmpl
.
They are usually HTML with embedded template directives.
The directives are expanded when TWiki wants to generate a user interface screen.
%TMPL:<key>%
and %TMPL:<key>{"attr"}%
.
%TMPL:INCLUDE{"file"}%
: Includes a template file. The file is found as described below.
%TMPL:DEF{"block"}%
: Define a block. All text between this and the next %TMPL:END%
directive is removed and saved for later use with %TMPL:P
.
%TMPL:END%
: Ends a block definition.
%TMPL:P{"var"}%
: Includes a previously defined block.
%{...}%
: is a comment.
twiki.tmpl
master template, like twiki.print.tmpl
, that redefines the header and footer.
%TMPL:DEF{"x"}% x%P%z%TMPL:END%
then %TMPL:P{"x" P="y"}%
will expand to xyz
.
Note that parameters can simply be ignored; for example, %TMPL:P{"x"}%
will expand to x%P%z.
Any alphanumeric characters can be used in parameter names.
You are highly recommended to use parameter names that cannot be confused with TWikiVariables.
Note that three parameter names, context
, then
and else
are reserved.
They are used to support a limited form of "if" condition that you can use to select which of two templates to use, based on a context identifier:
%TMPL:DEF{"link_inactive"}%<input type="button" disabled value="Link>%TMPL:END% %TMPL:DEF{"link_active"}%<input type="button" onclick="link()" value="Link" />%TMPL:END% %TMPL:P{context="inactive" then="inactive_link" else="active_link"}% for %CONTEXT%When the "inactive" context is set, then this will expand the "link_inactive" template; otherwise it will expand the "link_active" template. See IfStatements for details of supported context identifiers.
twiki/templates/view.tmpl
is the default template file for the twiki/bin/view
script.
You can save templates in other directories as long as they are listed in the {TemplatePath}
configuration setting.
The {TemplatePath}
is defined in the Miscellaneous section of the configure page.
You can also save templates in user topics (IF there is no possible template match in the templates
directory).
The {TemplatePath}
configuration setting defines which topics will be accepted as templates.
Templates that are included with an explicit '.tmpl'
extension are looked for only in the templates/
directory.
For instance %TMPL:INCLUDE{"example.tmpl"}%
will only return templates/example.tmpl
, regardless of {TemplatePath}
and SKIN settings.
The out-of-the-box setting of {TemplatePath}
supports the following search order to determine which template file or topic to use for a particular script or %TMPL:INCLUDE{"script"}%
statement.
The skin path is set as described in TWikiSkins.
view
, edit
View
dragon
, pattern
. All skins are checked at each stage, in the order they appear in the skin path.
Dragon
example
template file will be searched for in the following places, when the current web is Thisweb
and the skin path is print,pattern
:
templates/Thisweb/example.print.tmpl
deprecated; don't rely on it
templates/Thisweb/example.pattern.tmpl
deprecated; don't rely on it
templates/example.print.tmpl
templates/example.pattern.tmpl
templates/Thisweb/example.tmpl
deprecated; don't rely on it
templates/example.tmpl
Thisweb.PrintSkinExampleTemplate
Thisweb.PatternSkinExampleTemplate
Thisweb.ExampleTemplate
TWiki.PrintSkinExampleTemplate
TWiki.PatternSkinExampleTemplate
TWiki.ExampleTemplate
view
and edit
scripts, for example when a topic-specific template is required. Two preference variables can be used to override the templates used: VIEW_TEMPLATE
sets the template to be used for viewing a topic
EDIT_TEMPLATE
sets the template for editing a topic.
view
and edit
respectively. The template search order is as specified above.
Tip: If you want to override existing templates, without having to worry that your changes will get overwritten by the next TWiki update, change the {TemplatePath}
so that another directory, such as the %USERSWEB%
appears at the front. You can then put your own templates into that directory or web and these will override the standard templates. (Note that such will increase the lookup time for templates by searching your directory first.)
%TMPL:INCLUDE{"twiki"}%
, the templating system will include the next twiki.SKIN in the skin path.
For example, to create a customization of pattern skin, where you only want to over-ride the breadcrumbs for the view script, you can create only a view.yourlocal.tmpl:
%TMPL:INCLUDE{"view"}% %TMPL:DEF{"breadcrumb"}% We don't want any crumbs %TMPL:END%and then set SKIN=yourlocal,pattern The default
{TemplatePath}
will not give you the desired result if you put these statements in the topic Thisweb.YourlocalSkinViewTemplate
. The default {TemplatePath}
will resolve the request to the template/view.pattern.tmpl
, before it gets to the Thisweb.YourlocalSkinViewTemplate
resolution. You can make it work by prefixing the {TemplatePath}
with: $web.YourlocalSkin$nameTemplate
.
twiki.tmpl
is the default master template. It defines the following sections.
Template variable: | Defines: |
---|---|
%TMPL:DEF{"sep"}% |
"|" separator |
%TMPL:DEF{"htmldoctype"}% |
Start of all HTML pages |
%TMPL:DEF{"standardheader"}% |
Standard header (ex: view, index, search) |
%TMPL:DEF{"simpleheader"}% |
Simple header with reduced links (ex: edit, attach, oops) |
%TMPL:DEF{"standardfooter"}% |
Footer, excluding revision and copyright parts |
Topic Name: | What it is: |
---|---|
WebTopicViewTemplate | Alert page shown when you try to view a nonexistent topic. This page is usually used as a prompt to help you create a new topic. |
WebTopicNonWikiTemplate | Alert page shown when you try to view a nonexistent topic with a non-WikiName. Again, this page is used as a prompt to help you create the new topic. |
WebTopicEditTemplate | Default text used in a new topic. |
<MyCustomNamed>Template | Whenever you create a topic ending in the word "Template", it is automatically added to the list of available templates in the "Use Template" drop down field on the WebCreateNewTopic page. |
edit
script, TWiki locates a topic to use as a content template according to the following search order: templatetopic
CGI parameter Variable: | Description: |
---|---|
%DATE% |
Signature format date. See VarDATE |
%GMTIME% |
Date/time. See VarGMTIME |
%GMTIME{...}% |
Formatted date/time. See VarGMTIME2 |
%NOP% |
A no-operation variable that gets removed. Useful to prevent a SEARCH from hitting an edit template topic; also useful to escape a variable, such as %URLPA%NOP%RAM{...}% escaping URLPARAM |
%STARTSECTION{type="templateonly"}% |
Text that gets removed when a new topic based on the template is created. See notes below. |
%SERVERTIME% |
Date/time. See VarSERVERTIME |
%SERVERTIME{...}% |
Formatted date/time. See VarSERVERTIME2 |
%USERNAME% |
Login name of user who is instantiating the new topic, e.g. guest |
%URLPARAM{"name"}% |
Value of a named URL parameter. See VarURLPARAM. |
%WIKINAME% |
WikiName of user who is instantiating the new topic, e.g. TWikiGuest |
%WIKIUSERNAME% |
User name of user who is instantiating the new tpoic, e.g. Main.TWikiGuest |
%STARTSECTION{type="templateonly"}% ... %ENDSECTION{type="templateonly"}%
section. For example, you might want to write this in the template topic:
%STARTSECTION{type="templateonly"}% This template can only be changed by: * Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup %ENDSECTION{type="templateonly"}%This will restrict who can edit the template topic, but will be removed when a new topic based on that template topic is created.
%NOP%
can be used to prevent expansion of TWiki variables that would otherwise be expanded during topic creation. For example, escape %SERVERTIME%
with %SER%NOP%VERTIME%
.
type="expandvariables"
section in the template topic, such as:
...Example: If you have the following content in a template topic:
* %SYSTEMWEB%.ATasteOfTWiki - view a short introductory presentation on TWiki for beginners * %SYSTEMWEB%.WelcomeGuest - starting points on TWiki * %SYSTEMWEB%.TWikiUsersGuide - complete TWiki documentation * Sandbox.%HOMETOPIC% - try out TWiki on your own * Sandbox.%TOPIC%Sandbox - just for meyou will get this raw text in new topics based on that template topic:
* TWiki.ATasteOfTWiki - view a short introductory presentation on TWiki for beginners * TWiki.WelcomeGuest - starting points on TWiki * TWiki.TWikiUsersGuide - complete TWiki documentation * Sandbox.WebHome - try out TWiki on your own * Sandbox.JimmyNeutronSandbox - just for me
EOTC__
(EOTC followed by two underscores; EOTC stands for Expand On Topic Creation), you can have the variable expanded.
Here's an example.
%EOTC__SEARCH{"." topic="%URLPARAM{prefix}%*" nonoise="on" format="$percntINCLUDE{$topic}$percnt" separator="$n" }%This yields a series of
%INCLUDE{...}%
s, which are not expanded.
This is not achievable by an expandvariables
section.
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)
AUTOINC<n>
are preserved, but are not taken into account when calculating the next increment. Use this to create topic names that have a unique identifier (serial number) and a descriptive text.
Example: BlogAUTOINC0001-my-first-blog
- creates topic name Blog0001-my-first-blog
BlogAUTOINC0001-my-crazy-cats
- creates topic name Blog0002-my-crazy-cats
BlogAUTOINC0001-fondue-recipe
- creates topic name Blog0003-fondue-recipe
[[%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 raw text of the form:
%EDITFORMFIELD{ "new" type="start" action="edit" topic="Sandbox.%TOPIC%" }% * New example topic: %EDITFORMFIELD{ "topic" type="text" value="ExampleTopicAUTOINC0001" size="30" }% %EDITFORMFIELD{ "templatetopic" type="hidden" value="%SYSTEMWEB%.ExampleTopicTemplate" }% %EDITFORMFIELD{ "topicparent" type="hidden" value="%HOMETOPIC%" }% %EDITFORMFIELD{ "onlywikiname" type="hidden" value="on" }% %EDITFORMFIELD{ "onlynewtopic" type="hidden" value="on" }% %EDITFORMFIELD{ "form" type="submit" value="Create" }% %EDITFORMFIELD{ "form" type="end" }%Here is the equivalent form using a hand-crafted HTML form:
<form name="new" action="%SCRIPTURLPATH{edit}%/Sandbox/%HOMETOPIC%"> * New example topic: <input type="text" name="topic" value="ExampleTopicAUTOINC0001" size="30" /> <input type="hidden" name="templatetopic" value="%SYSTEMWEB%.ExampleTopicTemplate" /> <input type="hidden" name="topicparent" value="%HOMETOPIC%" /> <input type="hidden" name="onlywikiname" value="on" /> <input type="hidden" name="onlynewtopic" value="on" /> <input type="submit" class="twikiSubmit" value="Create" /> </form>Note: You can create a topic in one step, without going through the edit screen. To do that, specify the
save
script instead of the edit
script in the form action. When you specify the save script in an HTML form tag you have to use the "post" method. This is done automatically when using the EDITFORMFIELD variable. Example when using the HTML form tag:
<form name="new" action="%SCRIPTURLPATH{save}%/Sandbox/" method="post"> ... </form>The
edit
and save
scripts understand many more parameters, see TWikiScripts#edit and TWikiScripts#save for details.
TIP: You can use the %WIKIUSERNAME%
and %DATE%
variables in your topic templates to include the signature of the person creating a new topic. The variables are expanded into fixed text when a new topic is created. The standard signature is: -- %WIKIUSERNAME% - %DATE%
* Set SKIN = tagme, topmenu, pattern
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 customize, 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 we encourage you to show a small TWiki logo at the bottom of your skin:
%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.
twiki.pattern.tmpl
contains %TMPL:INCLUDE{"twiki"}%
, the templating system will include the next twiki.SKIN in the skin path (which is explained below). For example, to create a customization 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
.
Variable: | Expanded to: |
---|---|
%WEBLOGONAME% |
Filename of web logo |
%WEBLOGOIMG% |
Image URL of web logo |
%WEBLOGOURL% |
Link of web logo |
%WEBLOGOALT% |
Alt text of web logo |
%WIKILOGOURL% |
Link of page logo |
%WIKILOGOIMG% |
Image URL of page logo |
%WIKILOGOALT% |
Alt text of page logo |
%WEBBGCOLOR% |
Web-specific background color, defined in the WebPreferences |
%WIKITOOLNAME% |
The name of your TWiki site |
%SCRIPTURL% |
The script URL of TWiki |
%SCRIPTURLPATH% |
The script URL path |
%SCRIPTSUFFIX% |
The script suffix, ex: .pl , .cgi |
%WEB% |
The name of the current web. |
%TOPIC% |
The name of the current topic. |
%WEBTOPICLIST% |
Common links of current web, defined in the WebPreferences. It includes a Jump box |
%TEXT% |
The topic text, e.g. the content that can be edited |
%META{"form"}% |
TWikiForm, if any |
%META{"attachments"}% |
FileAttachment table |
%META{"parent"}% |
The topic parent |
%EDITTOPIC% |
Edit link |
%REVTITLE% |
The revision title, if any, ex: (r1.6) |
%REVINFO% |
Revision info, ex: r1.6 - 24 Dec 2002 - 08:12 GMT - TWikiGuest |
%WEBCOPYRIGHT% |
Copyright notice, defined in the WebPreferences |
%BROADCASTMESSAGE% |
Broadcast message at the beginning of your view template, can be used to alert users of scheduled downtimes; can be set in TWikiPreferences |
http://www.google.com/
to jump to an external web site. The feature is handy if you build a skin that has a select box of frequently used links, like Intranet home, employee database, sales database and such. A little JavaScript gets into action on the onchange
method of the select tag to fill the selected URL into the "Go" box field, then submits the form.
Here is an example form that has a select box and the Jump Box for illustration purposes. You need to have JavaScript enabled for this to work:
Note: Redirect to a URL only works if it is enabled in configure
(Miscellaneous, {AllowRedirectUrl}
).
styles.pattern.tmpl
.
<style type='text/css' media='all'>@import url('%PUBURLPATH%/%SYSTEMWEB%/MySkin/mystyle.css');</style>
attachtables.tmpl
template using the %TMPL:DEF
macro syntax described in TWikiTemplates. These macros are:
Macro | Description |
---|---|
ATTACH:files:header |
Standard title bar |
ATTACH:files:row |
Standard row |
ATTACH:files:footer |
Footer for all screens |
ATTACH:files:header:A |
Title bar for upload screens, with attributes column |
ATTACH:files:row:A |
Row for upload screen |
ATTACH:files:footer:A |
Footer for all screens |
Macro | Description |
---|---|
ATTACH:versions:header |
Header for versions table on upload screen |
ATTACH:versions:row |
Row format for versions table on upload screen |
ATTACH:versions:footer |
Footer for versions table on upload screen |
ATTACH:row
macros are expanded for each file in the attachment table, using the following special tags:
Tag | Description |
---|---|
%A_URL% |
viewfile URL that will recover the file |
%A_REV% |
Revision of this file |
%A_ICON% |
A file icon suitable for representing the attachment content |
%A_FILE% |
The name of the file. To get the 'pub' url of the file, use %PUBURL%/%WEB%/%TOPIC%/%A_FILE% |
%A_SIZE% |
The size of the file |
%A_DATE% |
The date the file was uploaded |
%A_USER% |
The user who uploaded it |
%A_COMMENT% |
The comment they put in when uploading it |
%A_ATTRS% |
The attributes of the file as seen on the upload screen e.g "h" for a hidden file |
view.
skin.tmpl
, where skin is the name of the skin e.g. pattern
. If no template is found, then the fallback is to use view.tmpl
. Each skin on the path is searched for in turn. For example, if you have set the skin path to local,pattern
then view.local.tmpl
will be searched for first, then view.pattern.tmpl
and finally view.tmpl
.
The basic skin is defined by a SKIN
setting:
Set SKIN = catskin, bearskin
?skin=catskin,bearskin
:
Setting SKIN
(or the ?skin
parameter in the URL) replaces the existing skin path setting, for the current page only. You can also extend the existing skin path as well, using covers.
Set COVER = ruskin
ruskin, catskin, bearskin
). There is also an equivalent cover
URL parameter. The difference between setting SKIN
vs. COVER
is that if the chosen template is not found (e.g., for included templates), SKIN
will fall back onto the next skin in line, or the default skin, if only one skin was present, while COVER
will always fall back onto the current skin.
An example would be invoking the printable mode, which is achieved by applying ?cover=print
. The view.print.tmpl
simply invokes the viewprint
template for the current skin which then can appropriately include all other used templates for the current skin. Where the printable mode be applied by using SKIN
, all skins would have the same printable appearance.
The full skin path is built up as follows: SKIN
setting (or ?skin
if it is set), then COVER
setting is added, then ?cover
.
* Set SKIN = %IF{ "'%HTTP{"User-Agent"}%'~'*iPhone*' OR '%HTTP{"User-Agent"}%'~'*Android*'" then="print, pattern" else="topmenu, pattern" }%
text
skin is reserved for TWiki internal use.
Skin names starting with rss
also have a special meaning; if one or more of the skins in the skin path starts with 'rss' then 8-bit characters will be encoded as XML entities in the output, and the content-type
header will be forced to text/xml
.
Related Topics: TWikiSkinBrowser, AdminDocumentationCategory, DeveloperDocumentationCategory, TWiki:TWiki.TWikiSkinsSupplement
-- Contributors: TWiki:Main.PeterThoeny, TWiki:Main.MikeMannix, TWiki:Main.CrawfordCurrie
Back to top
META:
tags
META:
tags.
META:
data includes program-generated info like FileAttachment and topic movement data, and user-defined TWikiForms info.
%META:<type>{key1="value1" key2="value2" ...}%
name
, this appears first for easier searching (note the order of the variables themselves is defined).
Example of Format%META:TOPICINFO{version="1.6" date="976762663" author="LastEditorWikiName" format="1.0"}% text of the topic %META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="TopicMoverWikiName" date="976762680"}% %META:TOPICPARENT{name="NavigationByTopicContext"}% %META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }% %META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }% %META:FORM{name="WebFormTemplate"}% %META:FIELD{name="OperatingSystem" value="OsWin"}% %META:FIELD{name="TopicClassification" value="PublicFAQ"}%
Key | Comment |
---|---|
version | Same as RCS version |
date | integer, unix time, seconds since start 1970 |
author | last to change topic, is the REMOTE_USER |
format | Format of this topic, will be used for automatic format conversion |
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%
Key | Comment |
---|---|
from | Full name, i.e., web.topic |
to | Full name, i.e., web.topic |
by | Who did it, is the REMOTE_USER, not WikiName |
date | integer, unix time, seconds since start 1970 |
Key | Comment |
---|---|
name | The topic from which this was created, typically when clicking on a red-link, or by filling out a form. Normally just TopicName , but it can be a full Web.TopicName format if the parent is in a different Web. |
Key | Comment |
---|---|
name | Name of file, no path. Must be unique within topic |
version | Same as RCS revision |
path | Full path file was loaded from |
size | In bytes |
date | integer, unix time, seconds since start 1970 |
user | the REMOTE_USER, not WikiName |
comment | As supplied when file uploaded |
attr | h if hidden, optional |
Key | Comment |
---|---|
movedfrom | full topic name - web.topic |
movedby | the REMOTE_USER, not WikiName |
movedto | full topic name - web.topic |
moveddate | integer, unix time, seconds since start 1970 |
Key | Comment |
---|---|
name | A topic name - the topic represents one of the TWikiForms. Can optionally include the web name (i.e., web.topic), but doesn't normally |
Key | Name |
---|---|
name | Ties to entry in TWikiForms template, is title with all bar alphanumerics and . removed |
title | Full text from TWikiForms template |
value | Value user has supplied via form |
diff
function output appears in a logical order
META:TOPICINFO
META:TOPICPARENT
(optional)
META:TOPICMOVED
(optional)
META:FILEATTACHMENT
(0 or more entries)
META:FORM
(optional)
META:FIELD
(0 or more entries; FORM required)
Raw Text
link can be clicked to show the text of a topic (i.e., as seen when editing). This is done by adding raw=on
to URL. raw=debug
shows the meta data as well as the topic data, ex: debug view for this topic
view
, preview
and edit
scripts.
You can render form fields in topic text by using the FORMFIELD variable. Example:%FORMFIELD{"TopicClassification"}%
Variable usage: | Comment: |
---|---|
%META{"form"}% |
Show form data, see TWikiForms. |
%META{"formfield"}% |
Show form field value. Parameter: name="field_name" . Example:%META{ "formfield" name="TopicClassification" }% |
%META{"attachments"}% |
Show attachments, except for hidden ones. Options: all="on" : Show all attachments, including hidden ones. |
%META{"moved"}% |
Details of any topic moves. |
%META{"parent"}% |
Show topic parent. Options: dontrecurse="on" : By default recurses up tree, at some cost. nowebhome="on" : Suppress WebHome. prefix="..." : Prefix for parents, only if there are parents, default "" . suffix="..." : Suffix, only appears if there are parents, default "" . separator="..." : Separator between parents, default is " > " . |
Behaviour
Javascript event library to create Javascript based interactions that degrade well when Javascript is not available - version 29499 (2015-11-29) yum
, apt-get
, rpm
, etc) to install dependent libraries.
If available, install CPAN (Comprehensive Perl Archive Network) libraries with the OS package manager. For example, to install IO::Socket::SSL
on Fedora/RedHat/CentOS, run yum install perl-IO-Socket-SSL
. CPAN modules can also be installed natively, see TWiki:TWiki.HowToInstallCpanModules.
%FAILEDPLUGINS%
variable can be used to debug failures. You may also want to check your webserver error log and the various TWiki log files.
ab
utility. Example on Unix:time wget -qO /dev/null /twiki/bin/view/TWiki/AbcPlugin
If you need to install an "expensive" plugin, but you only need its functionality only in a subset of your data, you can disable it elsewhere by defining the %DISABLEDPLUGINS% TWiki variable.
Define DISABLEDPLUGINS
to be a comma-separated list of names of plugins to disable. Define it in Main.TWikiPreferences to disable those plugins everywhere, in the WebPreferences topic to disable them in an individual web, or in a topic to disable them in that topic. For example,
* Set DISABLEDPLUGINS = SpreadSheetPlugin, EditTablePlugin
{PluginsOrder}
in the plugins section of configure.
Set VARCACHEPLUGIN_REFRESH = 24
%<pluginname>_<setting>%
, such as %VARCACHEPLUGIN_REFRESH%
.
To learn how this is done, use the TWiki:Plugins.VarCachePlugin documentation and Perl plugin code as a reference.
2. Use configure settings:
The administrator can set plugin settings in the configure interface. Recommended if only site administrators should be able to change settings. Chose this option to set sensitive or dangerous system settings, such as passwords or path to executables. To define plugin-specific configure settings,
lib/TWiki/Plugins/YourPlugin/
with variables, such as$TWiki::cfg{Plugins}{RecentVisitorPlugin}{ShowIP} = 0;
$showIP = $TWiki::cfg{Plugins}{RecentVisitorPlugin}{ShowIP} || 0;
Set SHORTDESCRIPTION = Show recent visitors to a TWiki site
our $SHORTDESCRIPTION = 'Show recent visitors to a TWiki site';
our $NO_PREFS_IN_TOPIC = 1;
%ACTIVATEDPLUGINS%
%PLUGINDESCRIPTIONS%
"$SUM( $ABOVE() )"
to TWiki tables or anywhere in topic text ExternalSite:Page
to link to a page on an external site based on aliases defined in a rules topic :-)
as or :eek:
as %FAILEDPLUGINS%
Plugin | Errors |
---|---|
SpreadSheetPlugin | none |
BackupRestorePlugin | none |
ColorPickerPlugin | none |
CommentPlugin | none |
DatePickerPlugin | none |
EditTablePlugin | none |
HeadlinesPlugin | none |
InterwikiPlugin | none |
JQueryPlugin | none |
NewsPlugin | none |
PreferencesPlugin | none |
SetGetPlugin | none |
SlideShowPlugin | none |
SmiliesPlugin | none |
TablePlugin | none |
TagMePlugin | none |
TinyMCEPlugin | none |
TwistyPlugin | none |
WatchlistPlugin | none |
WysiwygPlugin | none |
Handler | Plugins |
---|---|
afterEditHandler | WysiwygPlugin |
afterRenameHandler | TagMePlugin WatchlistPlugin |
afterSaveHandler | TagMePlugin WatchlistPlugin |
beforeCommonTagsHandler | EditTablePlugin PreferencesPlugin TwistyPlugin WysiwygPlugin |
beforeEditHandler | TinyMCEPlugin WysiwygPlugin |
beforeMergeHandler | WysiwygPlugin |
beforeSaveHandler | CommentPlugin NewsPlugin WatchlistPlugin WysiwygPlugin |
commonTagsHandler | SpreadSheetPlugin BackupRestorePlugin CommentPlugin EditTablePlugin JQueryPlugin SlideShowPlugin SmiliesPlugin |
initPlugin | SpreadSheetPlugin BackupRestorePlugin ColorPickerPlugin CommentPlugin DatePickerPlugin EditTablePlugin HeadlinesPlugin InterwikiPlugin JQueryPlugin NewsPlugin PreferencesPlugin SetGetPlugin SlideShowPlugin SmiliesPlugin TablePlugin TagMePlugin TinyMCEPlugin TwistyPlugin WatchlistPlugin WysiwygPlugin |
modifyHeaderHandler | WysiwygPlugin |
postRenderingHandler | PreferencesPlugin WysiwygPlugin |
preRenderingHandler | InterwikiPlugin SmiliesPlugin TablePlugin |
lib/TWiki/Func.pm
) describes all the interfaces available to plugins. Plugins should only use the interfaces described in this module.
Note: If you use other core functions not described in Func.pm
, you run the risk of creating security holes. Also, your plugin will likely break and require updating when you upgrade to a new version of TWiki.
lib/TWiki/Plugins/EmptyPlugin.pm
module.
#
from all lines of the callback.
eval
block like this:eval { require IPC::Run }
return "<font color=\"red\">SamplePlugin: Can't load required modules ($@)</font>" if $@;
lib/TWiki/Plugins/BathPlugin/
.
$NO_PREFS_IN_TOPIC
in your plugin package as that will stop TWiki from reading the plugin topic for every page. Use Config.spec or preferences settings instead. (See details).
$VERSION
variable. This should be an integer, or a subversion version id.
initPlugin
handler should check all dependencies and return 1 if the initialization is OK or 0 if something went wrong. initPlugin
handler).
$TWiki::Plugins::VERSION
in the TWiki::Plugins
module contains the TWiki plugin API version, currently 6.02. %PLUGINVERSION{}%
variable to query the plugin API version or the version of installed plugins.
%TWiki::cfg
hash than adding it as preferences in the plugin topic. configure
describes the steps
MyFirstPlugin.pm
MyFirstPlugin.txt
MyFirstPlugin
topic. Other needed Perl code is best placed in a lib/TWiki/Plugins/MyFirstPlugin/
directory.
The plugin API handles the details of connecting your Perl module with main TWiki code. When you're familiar with the Plugin API, you're ready to develop plugins.
The TWiki:Plugins.BuildContrib module provides a lot of support for plugins development, including a plugin creator, automatic publishing support, and automatic installation script writer. If you plan on writing more than one plugin, you probably need it.
lib/TWiki/Plugins/EmptyPlugin.pm
to <name>Plugin.pm
. The EmptyPlugin.pm
module contains mostly empty functions, so it does nothing, but it's ready to be used. Customize it. Refer to the Plugin API specs for more information.
If your plugin uses its own modules and objects, you must include the name of the plugin in the package name. For example, write Package MyFirstPlugin::Attrs;
instead of just Package Attrs;
. Then call it using:
use TWiki::Plugins::MyFirstPlugin::Attrs; $var = MyFirstPlugin::Attrs->new();
MyFirstPlugin
, press enter and create the new topic
OUTLINE: Doc Topic Contents
Check the plugins web on TWiki.org for the latest plugin doc topic template. Here's a quick overview of what's covered: Syntax Rules: <Describe any special text formatting that will be rendered.>" Example: <Include an example of the plugin in action. Possibly include a static HTML version of the example to compare if the installation was a success!>" Plugin Settings: <Description and settings for custom plugin %VARIABLES%, and those required by TWiki.>" Plugin Installation Instructions: <Step-by-step set-up guide, user help, whatever it takes to install and run, goes here.>" Plugin Info: <Version, credits, history, requirements - entered in a form, displayed as a table. Both are automatically generated when you create or edit a page in the TWiki:Plugins web.>"
Plugin
, ex: MyFirstPlugin.pm
, and a documentation page with the same name(MyFirstPlugin.txt
).
lib/TWiki/Plugins/MyFirstPlugin.pm
data/TWiki/MyFirstPlugin.txt
pub/TWiki/MyFirstPlugin/uparrow.gif
[a required graphic]
MyFirstPlugin.zip
) and add the entire directory structure from Step 1. The archive should look like this: lib/TWiki/Plugins/MyFirstPlugin.pm
data/TWiki/MyFirstPlugin.txt
pub/TWiki/MyFirstPlugin/uparrow.gif
MyFirstPlugin
MyFirstPlugin.zip
Dev
, ex: MyFirstPluginDev
. This is the discussion page for future development. (User support for plugins is handled in TWiki:Support.)
TWiki::Func::getWorkArea()
function, which gives you a persistent directory where you can store data files. By default they will not be web accessible. The directory is guaranteed to exist, and to be writable by the webserver user. For convenience, TWiki::Func::storeFile()
and TWiki::Func::readFile()
are provided to persistently store and retrieve simple data in this area.
TWiki::Func::saveAttachment()
function to store the data.
Recommendation for file name: _GaugePlugin_img123.gif
TWiki::Func::saveAttachment()
function to store the data.
Recommendation for file names in plugin attachment area: _Main_roundedge-ul.gif
configure
configure
rather than trying to use TWiki preferences variables. These extensions use Config.spec
files to publish their configuration requirements.
Config.spec
files are read during TWiki configuration. Once a Config.spec
has defined a configuration item, it is available for edit through the standard configure
interface. Config.spec
files are stored in the 'plugin directory' e.g. lib/TWiki/Plugins/BathPlugin/Config.spec
.
Config.spec
file Config.spec
file for an extension starts with the extension announcing what it is:
# ---+ Extensions # ---++ BathPlugin # This plugin senses the level of water in your bath, and ensures the plug # is not removed while the water is still warm.This is followed by one or more configuration items. Each configuration item has a type, a description and a default. For example:
# **SELECT Plastic,Rubber,Metal** # Select the plug type $TWiki::cfg{BathPlugin}{PlugType} = 'Plastic'; # **NUMBER** # Enter the chain length in cm $TWiki::cfg{BathPlugin}{ChainLength} = 30; # **BOOLEAN EXPERT** # Set this option to 0 to disable the water temperature alarm $TWiki::cfg{BathPlugin}{TempSensorEnabled} = 1;The type (e.g.
**SELECT**
) tells configure
to how to prompt for the value. It also tells configure
how to do some basic checking on the value you actually enter. All the comments between the type and the configuration item are taken as part of the description. The configuration item itself defines the default value for the configuration item. The above spec defines the configuration items $TWiki::cfg{BathPlugin}{PlugType}
, $TWiki::cfg{BathPlugin}{ChainLength}
, and $TWiki::cfg{BathPlugin}{TempSensorEnabled}
for use in your plugin. For example,
if( $TWiki::cfg{BathPlugin}{TempSensorEnabled} && $curTemperature > 50 ) { die "The bathwater is too hot for comfort"; }The Config.spec file is read by
configure
, which then writes LocalSite.cfg
with the values chosen by the local site admin.
A range of types are available for use in Config.spec
files:
BOOLEAN | A true/false value, represented as a checkbox |
COMMAND length | A shell command |
LANGUAGE | A language (selected from {LocalesDir} |
NUMBER | A number |
OCTAL | An octal number |
PASSWORD length | A password (input is hidden) |
PATH length | A file path |
PERL | A perl structure, consisting of arrays and hashes |
REGEX length | A perl regular expression |
SELECT choices | Pick one of a range of choices |
SELECTCLASS root | Select a perl package (class) |
STRING length | A string |
URL length | A url |
URLPATH length | A relative URL path |
EXPERT | means this an expert option |
M | means the setting is mandatory (may not be empty) |
H | means the option is not visible in configure |
lib/TWiki.spec
for many more examples.
Config.spec
files for non-plugin extensions are stored under the Contrib
directory instead of the Plugins
directory.
Note that from TWiki 5.0 onwards, CGI scripts (in the TWiki bin
directory) provided by extensions must also have an entry in the Config.spec
file. This entry looks like this (example taken from PublishContrib)
# **PERL H** # Bin script registration - do not modify $TWiki::cfg{SwitchBoard}{publish} = [ "TWiki::Contrib::Publish", "publish", { publishing => 1 } ];
PERL
specifies a perl data structure, and H
a hidden setting (it won't appear in configure
). The first field of the data value specifies the class where the function that implements the script can be found. The second field specifies the name of the function, which must be the same as the name of the script. The third parameter is a hash of initial context settings for the script.
TWiki:TWiki/SpecifyingConfigurationItemsForExtensions has supplemental documentation on configure settings.
Dev
, such as MyFirstPluginDev
. The plugin development topic is a great resource to discuss feature enhancements and to get feedback from the TWiki community.
if( $TWiki::Plugins::VERSION >= 1.1 ) { @webs = TWiki::Func::getListOfWebs( 'user,public' ); } else { @webs = TWiki::Func::getPublicWebList( ); }
TWiki::Plugins
version in which the handler was first deprecated. For example, if we need to define the endRenderingHandler
for compatibility with TWiki::Plugins
versions before 1.1, we would add this to the plugin:
package TWiki::Plugins::SinkPlugin; use vars qw( %TWikiCompatibility ); $TWikiCompatibility{endRenderingHandler} = 1.1;If the currently-running TWiki version is 1.1 or later, then the handler will not be called and the warning will not be issued. TWiki with versions of
TWiki::Plugins
before 1.1 will still call the handler as required.
Back to top
%PLUGINVERSION%
TWiki variable, and accessed in code using
$TWiki::Plugins::VERSION
. The 'Since' field in the function
documentation refers to $TWiki::Plugins::VERSION
.
Notes on use of $TWiki::Plugins::VERSION
6.00 and later:
$TWiki::Plugins::VERSION = 6.78
.
6.79
, TWiki-6.7.10 will have 6.7910
, and TWiki-6.7.11 will have 6.7911
. This ensures that the version number can sort properly.
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 honored.
Optional parameters may be supplied: \@headers
(an array ref): Additional HTTP headers of form 'name1', 'value1', 'name2', 'value2'. User-Agent header is set to "TWiki::Net/### libwww-perl/#.##" by default, where ### is the revision number of TWiki::Net and #.## is the version of LWP.
\%params
(a hash ref): Additional options.
%params
. See CPAN:LWP::UserAgent for more
details.
Name | Usage |
---|---|
agent |
=> $useragent ("User-Agent:" header) |
cookie_jar |
=> $cookies |
credentials |
=> [$netloc, $realm, $uname, $pass] |
handlers |
=> {$phase => \&cb, ...} Note: %matchspec is not available. |
local_address |
=> $address |
max_redirect |
=> $n |
max_size |
=> $bytes |
method * |
=> $method E.g. 'HEAD' |
parse_head |
=> $boolean |
requests_redirectable |
=> \@requests |
ssl_opts |
=> {$key => $value, ...} |
timeout * |
=> $secs |
LWP
.
Example:
my $response = getExternalResource($url, ['Cache-Control' => 'max-age=0'], {timeout => 10});The
$response
is an object that is known to implement the following subset of
the methods of HTTP::Response
. It may in fact be an HTTP::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')) { $text = $response->content(); # ... other methods of HTTP::Response may be called } else { # ... only the methods listed above may be called }Since: TWiki::Plugins::VERSION 1.2 Note: The optional parameters \@headers and \%params were added in TWiki::Plugins::VERSION 6.00
getExternalResource()
except that it uses
an HTTP POST method and that the additional $text
parameter is required.
The $text
is sent to the server as the body content of the HTTP request.
See getExternalResource()
for more details.
Since: TWiki::Plugins::VERSION 6.00
$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 'FirstPluginEnabled' 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 TWiki-4.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 TWiki-4.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, required, 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.
To get the login name of the currently logged in user use:
my $user = TWiki::Func::wikiToUserName( TWiki::Func::getWikiName() );Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$loginName
- Login name, e.g. 'jdoe'
. Since TWiki 4.2.1 this may also be a wiki name. This will normally be transparent, but may be relevant if you have login names that are also valid wiki names.
$dontAddWeb
- Do not add web prefix if "1"
$wikiName
Wiki name of user, e.g. 'Main.JohnDoe'
or 'JohnDoe'
userToWikiName will always return a name. If the user does not
exist in the mapping, the $loginName parameter is returned. (backward compatibility)
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$email
- email address to look up
$dontAddWeb
- Do not add web prefix if "1"
$user
- wikiname of user to look up
if( TWiki::Func::isGroupMember( "HesperionXXGroup", "jordi" )) { ... }If
$user
is undef
, it defaults to the currently logged-in user.
my $iterator = TWiki::Func::eachUser(); while ($it->hasNext()) { my $user = $it->next(); # $user is a wikiname }WARNING on large sites, this could be a long list! Since: TWiki::Plugins::VERSION 1.2
$id
- WikiName or login name of the user. If $id
is undef
, defaults to the currently logged-in user.
my $iterator = TWiki::Func::eachGroup(); while ($it->hasNext()) { my $group = $it->next(); # $group is a group name e.g. TWikiAdminGroup }WARNING on large sites, this could be a long list! Since: TWiki::Plugins::VERSION 1.2
$group
is the name of a group known to TWiki.
my $iterator = TWiki::Func::eachGroupMember('RadioheadGroup'); while ($it->hasNext()) { my $user = $it->next(); # $user is a wiki name e.g. 'TomYorke', 'PhilSelway' }WARNING on large sites, this could be a long list! Since: TWiki::Plugins::VERSION 1.2
$type
- Access type, required, e.g. 'VIEW'
, 'CHANGE'
.
$id
- WikiName of remote user, required, e.g. "PeterThoeny"
. From TWiki 4.2.1, $id may also be a login name. If $id
is '', 0 or undef
then access is always permitted.
$text
- Topic text, optional. If 'perl false' (undef, 0 or ''), topic $web.$topic
is consulted. $text
may optionally contain embedded %META:PREFERENCE
tags. Provide this parameter if: $meta
parameter.
$topic
- Topic name, required, e.g. 'PrivateStuff'
$web
- Web name, required, e.g. 'Sandbox'
$meta
- Meta-data object, as returned by readTopic
. Optional. If undef
, but $text
is defined, then access controls will be parsed from $text
. If defined, then metadata embedded in $text
will be ignored. This parameter is always ignored if $text
is undefined. Settings in $meta
override Set
settings in $text.
ThatWeb.ThisTopic
, then a call to checkAccessPermission('SPIN', 'IncyWincy', undef, 'ThisTopic', 'ThatWeb', undef)
will return true
.
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
$filter
- spec of web types to recover
$filter
may also contain the word 'public' which will further filter
out webs that have NOSEARCHALL set on them.
'allowed' filters out webs the current user can't read.
For example, the deprecated getPublicWebList function can be duplicated
as follows:
my @webs = TWiki::Func::getListOfWebs( "user,public" );Since: TWiki::Plugins::VERSION 1.1
$web
- Web name, required, e.g. 'Sandbox'
$name
- web name
$templateWeb
- flag, optional. If true, then template web names (starting with _) are considered valid, otherwise only user web names are valid.
$newWeb
is the name of the new web.
$baseWeb
is the name of an existing web (a template web). If the base web is a system web, all topics in it will be copied into the new web. If it is a normal web, only topics starting with 'Web' will be copied. If no base web is specified, an empty web (with no topics) will be created. If it is specified but does not exist, an error will be thrown.
$opts
is a ref to a hash that contains settings to be modified in
use Error qw( :try ); use TWiki::AccessControlException; try { TWiki::Func::createWeb( "Newweb" ); } catch Error::Simple with { my $e = shift; # see documentation on Error::Simple } catch TWiki::AccessControlException with { my $e = shift; # see documentation on TWiki::AccessControlException } otherwise { ... };Since: TWiki::Plugins::VERSION 1.1
use Error qw( :try ); use TWiki::AccessControlException; try { TWiki::Func::moveWeb( "Oldweb", "Newweb" ); } catch Error::Simple with { my $e = shift; # see documentation on Error::Simple } catch TWiki::AccessControlException with { my $e = shift; # see documentation on TWiki::AccessControlException } otherwise { ... };To delete a web, move it to a subweb of
Trash
TWiki::Func::moveWeb( "Deadweb", "Trash.Deadweb" );Since: TWiki::Plugins::VERSION 1.1
$time
and now. $time is a time in seconds since 1st Jan 1970, and is not
guaranteed to return any changes that occurred before (now -
{Store}{RememberChangesFor}). {Store}{RememberChangesFor}) is a
setting in configure
. Changes are returned in most-recent-first
order.
Use it as follows:
my $iterator = TWiki::Func::eachChangeSince( $web, time() - 7 * 24 * 60 * 60); # the last 7 days while ($iterator->hasNext()) { my $change = $iterator->next(); # $change is a perl hash that contains the following fields: # topic => topic name # user => wikiname - wikiname of user who made the change # time => time of the change # revision => revision number *after* the change # more => more info about the change (e.g. 'minor') }Since: TWiki::Plugins::VERSION 1.2
$web
- Web name, required, e.g. 'Sandbox'
@topics
Topic list, e.g. ( 'WebChanges', 'WebHome', 'WebIndex', 'WebNotify' )
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web
- Web name, optional, e.g. 'Main'
.
$topic
- Topic name, required, e.g. 'TokyoOffice'
, or "Main.TokyoOffice"
normalizeWebTopicName
.
Specifically, the Main is used if $web is not specified and $topic has no web specifier.
To get an expected behaviour it is recommened to specify the current web for $web; don't leave it empty.
Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
$name
- topic name
$web
Web name, e.g. "Main"
, or empty
$topic
Topic name, e.g. "MyTopic"
, or "Main.MyTopic"
( $oopsUrl, $loginName, $unlockTime )
- The $oopsUrl
for calling redirectCgiQuery(), user's $loginName
, and estimated $unlockTime
in minutes, or ( '', '', 0 ) if no lease exists. $script
The script to invoke when continuing with the edit
$web
Web name, e.g. "Main"
, or empty
$topic
Topic name, e.g. "MyTopic"
, or "Main.MyTopic"
$lock
1 to lease the topic, 0 to clear an existing lease
edit
script
always takes out a lease.
It is impossible to fully lock a topic. Concurrent changes will be
merged.
Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
$web
- web for the topic
$topic
- topic name
$meta
- reference to TWiki::Meta object
$text
- text of the topic (without embedded meta-data!!!
\%options
- ref to hash of save options \%options
may include: dontlog | don't log this change in twiki log |
forcenewrevision | force the save to increment the revision counter |
minor | True if this is a minor change, and is not to be notified |
# read topic: my( $topicMeta, $topicText ) = TWiki::Func::readTopic( $web, $topic ); # example to change topic text: $topicText =~ s/APPLE/ORANGE/g; # example to change TWiki form field: my $field = $topicMeta->get( 'FIELD', 'Title' ); if( $field ) { $field->{value} = $newTitle; $topicMeta->putKeyed( 'FIELD', $field ); } # save updated topic: TWiki::Func::saveTopic( $web, $topic, $topicMeta, $topicText, { forcenewrevision => 1 } );Note: Plugins handlers ( e.g.
beforeSaveHandler
) will be called as
appropriate.
$web
- Web name, e.g. 'Main'
, or empty
$topic
- Topic name, e.g. 'MyTopic'
, or "Main.MyTopic"
$text
- Topic text to save, assumed to include meta data
$ignorePermissions
- Set to "1"
if checkAccessPermission() is already performed and OK
$dontNotify
- Set to "1"
if not to notify users of the change
$oopsUrl
Empty string if OK; the $oopsUrl
for calling redirectCgiQuery() in case of error
This method is a lot less efficient and much more dangerous than saveTopic
.
Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
my $text = TWiki::Func::readTopicText( $web, $topic ); # check for oops URL in case of error: if( $text =~ /^http.*?\/oops/ ) { TWiki::Func::redirectCgiQuery( $query, $text ); return; } # do topic text manipulation like: $text =~ s/old/new/g; # do meta data manipulation like: $text =~ s/(META\:FIELD.*?name\=\"TopicClassification\".*?value\=\")[^\"]*/$1BugResolved/; $oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text
$web
source web - required
$topic
source topic - required
$newWeb
dest web
$newTopic
dest topic
use Error qw( :try ); try { moveTopic( "Work", "TokyoOffice", "Trash", "ClosedOffice" ); } catch Error::Simple with { my $e = shift; # see documentation on Error::Simple } catch TWiki::AccessControlException with { my $e = shift; # see documentation on TWiki::AccessControlException } otherwise { ... };
$web
- Web name, optional, e.g. 'Main'
$topic
- Topic name, required, e.g. 'TokyoOffice'
$rev
- revsion number, or tag name (can be in the format 1.2, or just the minor number)
$attachment
-attachment filename
( $date, $user, $rev, $comment )
List with: ( last update date, login name of last user, minor part of top revision number ), e.g. ( 1234561, 'phoeny', "5" )
$date | in epochSec |
$user | Wiki name of the author (not login name) |
$rev | actual rev number |
$comment | WHAT COMMENT? |
$meta->getRevisionInfo
instead if you can - it is significantly
more efficient.
Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
$web
- web for topic
$topic
- topic
$time
- time (in epoch secs) for the rev
$web
- Web name, required, e.g. 'Main'
$topic
- Topic name, required, e.g. 'TokyoOffice'
$rev
- revision to read (default latest)
( $meta, $text )
Meta data object and topic text
$meta
is a perl 'object' of class TWiki::Meta
. This class is
fully documented in the source code documentation shipped with the
release, or can be inspected in the lib/TWiki/Meta.pm
file.
This method ignores topic access permissions. You should be careful to use
checkAccessPermission
to ensure the current user has read access to the
topic.
See usage example at TWiki::Func::saveTopic.
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web
- Web name, e.g. 'Main'
, or empty
$topic
- Topic name, e.g. 'MyTopic'
, or "Main.MyTopic"
$rev
- Topic revision to read, optional. Specify the minor part of the revision, e.g. "5"
, not "1.5"
; the top revision is returned if omitted or empty.
$ignorePermissions
- Set to "1"
if checkAccessPermission() is already performed and OK; an oops URL is returned if user has no permission
$text
Topic text with embedded meta data; an oops URL for calling redirectCgiQuery() is returned in case of an error
This method is more efficient than readTopic
, but returns meta-data embedded in the text. Plugins authors must be very careful to avoid damaging meta-data. You are recommended to use readTopic instead, which is a lot safer.
Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
$web
- Web name, optional, e.g. Main
.
$topic
- Topic name, required, e.g. TokyoOffice
, or Main.TokyoOffice
$attachment
- attachment name, e.g. logo.gif
normalizeWebTopicName
.
Since: TWiki::Plugins::VERSION 1.1
$web
- web for topic
$topic
- topic
$name
- attachment name
$rev
- revision to read (default latest)
readTopic
. If the attachment does not exist, or cannot be read, undef
will be returned. If the revision is not specified, the latest version will
be returned.
View permission on the topic is required for the
read to be successful. Access control violations are flagged by a
TWiki::AccessControlException. Permissions are checked for the current user.
my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic ); my @attachments = $meta->find( 'FILEATTACHMENT' ); foreach my $a ( @attachments ) { try { my $data = TWiki::Func::readAttachment( $web, $topic, $a->{name} ); ... } catch TWiki::AccessControlException with { }; }Since: TWiki::Plugins::VERSION 1.1
$web
- web for topic
$topic
- topic to atach to
$attachment
- name of the attachment
$opts
- Ref to hash of options
$ignorePermissions
- Set to "1"
if checkAccessPermission() is already performed and OK.
$opts
may include:
dontlog |
don't log this change in twiki log |
comment |
comment for save |
hide |
if the attachment is to be hidden in normal topic view |
stream |
Stream of file to upload |
file |
Name of a file to use for the attachment data. ignored if stream is set. Local file on the server. |
filepath |
Client path to file |
filesize |
Size of uploaded data |
filedate |
Date |
try { TWiki::Func::saveAttachment( $web, $topic, 'image.gif', { file => 'image.gif', comment => 'Picture of Health', hide => 1 } ); } catch Error::Simple with { # see documentation on Error } otherwise { ... };Since: TWiki::Plugins::VERSION 1.1
$web
source web - required
$topic
source topic - required
$attachment
source attachment - required
$newWeb
dest web
$newTopic
dest topic
$newAttachment
dest attachment
use Error qw( :try ); try { # move attachment between topics moveAttachment( "Countries", "Germany", "AlsaceLorraine.dat", "Countries", "France" ); # Note destination attachment name is defaulted to the same as source } catch TWiki::AccessControlException with { my $e = shift; # see documentation on TWiki::AccessControlException } catch Error::Simple with { my $e = shift; # see documentation on Error::Simple };Since: TWiki::Plugins::VERSION 1.1
$name
- Template name, e.g. 'view'
$skin
- Comma-separated list of skin names, optional, e.g. 'print'
$text
Template text
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$name
- template file name
$skin
- comma-separated list of skins to use (default: current skin)
$web
- the web to look in for topics that contain templates (default: current web)
$def
- template name
$query
and $contentLength
parameters. Both were marked "you should not pass this parameter".
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$query
- CGI query object. Ignored, only there for compatibility. The session CGI query object is used instead.
$url
- URL to redirect to
$passthru
- enable passthrough.
$viaCache
- forcibly cache a redirect CGI query. It cuts off all the params in a GET url and replace with a "?$cache=..." param. "$viaCache" is meaningful only if "$passthru" is true.
$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 and custom css. $id
- Unique ID to prevent the same HTML from being duplicated. Plugins should use a prefix to prevent name clashes (e.g EDITTABLEPLUGIN_JSCALENDAR)
$header
- the HTML to be added to the section. The HTML must be valid in a HEAD tag - no checks are performed.
requires
optional, comma-separated list of id's of other head blocks this one depends on. Those blocks will be loaded first.
$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
$web
- name of web, optional
$topic
- name of topic, optional
%DATE%
Signature-format date
%SERVERTIME%
See TWikiVariables
%GMTIME%
See TWikiVariables
%USERNAME%
Base login name
%WIKINAME%
Wiki name
%WIKIUSERNAME%
Wiki name with prepended web
%URLPARAM{...}%
- Parameters to the current CGI query
%NOP%
No-op
commonTagsHandler
. $var
- The name of the variable, i.e. the 'MYVAR' part of %MYVAR%. The variable name must match /^[A-Z][A-Z0-9_]*$/ or it won't work.
\&fn
- Reference to the handler function.
$syntax
can be 'classic' (the default) or 'context-free'. 'classic' syntax is appropriate where you want the variable to support classic TWiki syntax i.e. to accept the standard %MYVAR{ "unnamed" param1="value1" param2="value2" }%
syntax, as well as an unquoted default parameter, such as %MYVAR{unquoted parameter}%
. If your variable will only use named parameters, you can use 'context-free' syntax, which supports a more relaxed syntax. For example, %MYVAR{param1=value1, value 2, param3="value 3", param4='value 5"}%
sub handler(\%session, \%params, $topic, $web)where:
\%session
- a reference to the TWiki session object (may be ignored)
\%params
- a reference to a TWiki::Attrs object containing parameters. This can be used as a simple hash that maps parameter names to values, with _DEFAULT being the name for the default parameter.
$topic
- name of the topic in the query
$web
- name of the web in the query
$meta
- topic meta-data to use while expanding, can be undef (Since TWiki::Plugins::VERSION 1.4)
$textRef
- reference to unexpanded topic text, can be undef (Since TWiki::Plugins::VERSION 1.4)
sub initPlugin{ TWiki::Func::registerTagHandler('EXEC', \&boo); } sub boo { my( $session, $params, $topic, $web ) = @_; my $cmd = $params->{_DEFAULT}; return "NO COMMAND SPECIFIED" unless $cmd; my $result = `$cmd 2>&1`; return $params->{silent} ? '' : $result; }would let you do this:
%EXEC{"ps -Af" silent="on"}%
Registered tags differ from tags implemented using the old TWiki approach (text substitution in commonTagsHandler
) in the following ways: commonTagsHandler
is only called later, when all system tags have already been expanded (though they are expanded again after commonTagsHandler
returns).
FRED
defines both %FRED{...}%
and also %FRED%
.
return '%SERVERTIME%';
). It won't work.
$alias
- The name .
\&fn
- Reference to the function.
sub handler(\%session)where:
\%session
- a reference to the TWiki session object (may be ignored)
TWiki::Func::registerRESTHandler('example', \&restExample);This adds the
restExample
function to the REST dispatch table
for the EmptyPlugin under the 'example' alias, and allows it
to be invoked using the URL
http://server:port/bin/rest/EmptyPlugin/example
note that the URL
http://server:port/bin/rest/EmptyPlugin/restExample
(ie, with the name of the function instead of the alias) will not work.
\&fn
- Reference to the function.
sub handler(\%session, $url) -> (\@headers, \%params)where:
\%session
- a reference to the TWiki session object (may be ignored)
$url
- a URL being requested
\@headers
and \%params
are added to the request in the same
manner as getExternalResource
, except that \%params
will not override any
entries that have been set earlier.
All the params explicitly given by the caller of getExternalResource
or
postExternalResource
will have the highest precedence.
Example:
sub initPlugin { TWiki::Func::registerExternalHTTPHandler( \&handleExternalHTTPRequest ); } sub handleExternalHTTPRequest { my ($session, $url) = @_; my @headers; my %params; # Add any necessary @headers and %params push @headers, 'X-Example-Header' => 'Value'; $params{timeout} = 5; # Return refs to both return (\@headers, \%params); }Since: TWiki::Plugins::VERSION 6.00
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 (" ) |
$aquot |
Apostrophe quote (' ) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
$lt |
Less than sign (< ) |
$gt |
Greater than sign (> ) |
$searchString
- the search string, in egrep format
$web
- The web to search in
\@topics
- reference to a list of topics to search
\%option
- reference to an options hash
\%options
hash may contain the following options: type
- if regex
will perform a egrep-syntax RE search (default '')
casesensitive
- false to ignore case (default true)
files_without_match
- true to return files only (default false). If files_without_match
is specified, it will return on the first match in each topic (i.e. it will return only one match per topic, and will not return matching lines).
my $result = TWiki::Func::searchInWebContent( "Slimy Toad", $web, \@topics, { casesensitive => 0, files_without_match => 0 } ); foreach my $topic (keys %$result ) { foreach my $matching_line ( @{$result->{$topic}} ) { ...etcSince: TWiki::Plugins::VERSION 1.1
$filename
- Full path name of file
$text
Content of file, empty if not found
NOTE: Use this function only for the Plugin workarea, not for topics and attachments. Use the appropriate functions to manipulate topics and attachments.
Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
$filename
- Full path name of file
$text
- Text to save
$web
web are moved.
Or returns the name of the trash web of the specified disk.
Each disk (file system) TWiki uses needs to have a trash web since a topic deletion may entail an attachment directory move, which is possible only within the same disk/file system.
Since: TWiki::Plugins::VERSION 6.00
$name
- Name of the expression to retrieve. See notes below
my $upper = TWiki::Func::getRegularExpression('upperAlpha'); my $alpha = TWiki::Func::getRegularExpression('mixedAlpha'); my $capitalized = qr/[$upper][$alpha]+/;Those expressions marked type 'RE' are precompiled regular expressions that can be used outside square brackets. For example:
my $webRE = TWiki::Func::getRegularExpression('webNameRegex'); my $isWebName = ( $s =~ m/$webRE/ );
Name | Matches | Type |
---|---|---|
upperAlpha | Upper case characters | String |
upperAlphaNum | Upper case characters and digits | String |
lowerAlpha | Lower case characters | String |
lowerAlphaNum | Lower case characters and digits | String |
numeric | Digits | String |
mixedAlpha | Alphabetic characters | String |
mixedAlphaNum | Alphanumeric characters | String |
wikiWordRegex | WikiWords | RE |
webNameRegex | User web names | RE |
anchorRegex | #AnchorNames | RE |
abbrevRegex | Abbreviations e.g. GOV, IRS | RE |
emailAddrRegex | email@address.com | RE |
tagNameRegex | Standard variable names e.g. %THIS_BIT% (THIS_BIT only) | RE |
$web
- Web name, identifying variable, or empty string
$topic
- Topic name, may be a web.topic string, required.
Input | Return |
---|---|
( 'Web', 'Topic' ) | ( 'Web', 'Topic' ) |
( '', 'Topic' ) | ( 'Main', 'Topic' ) |
( '', '' ) | ( 'Main', 'WebHome' ) |
( '', 'Web/Topic' ) | ( 'Web', 'Topic' ) |
( '', 'Web/Subweb/Topic' ) | ( 'Web/Subweb', 'Topic' ) |
( '', 'Web.Topic' ) | ( 'Web', 'Topic' ) |
( '', 'Web.Subweb.Topic' ) | ( 'Web/Subweb', 'Topic' ) |
( 'Web1', 'Web2.Topic' ) | ( 'Web2', 'Topic' ) |
configure
.
The symbols %USERSWEB%, %SYSTEMWEB% and %DOCWEB% can be used in the input to represent the web names set in $cfg{UsersWebName} and $cfg{SystemWebName}. For example:
Input | Return |
---|---|
( '%USERSWEB%', 'Topic' ) | ( 'Main', 'Topic' ) |
( '%SYSTEMWEB%', 'Topic' ) | ( 'TWiki', 'Topic' ) |
( '', '%DOCWEB%.Topic' ) | ( 'TWiki', 'Topic' ) |
$pre
- Arbitrary Text
$text
Since: TWiki::Plugins::VERSION 1.3 (18 Jan 2010)
$text
- Text to write; timestamp gets added
$text
- Text to write; timestamp gets added
$action
- name of the event, such as 'blacklist'
.
$extra
- arbitrary extra information to add to the event.
$web
- web name, optional. Base web is taken if empty. Ignored if web is specified in $topic
.
$topic
- topic name, optional. Can be Topic
or Web.Topic
. Base topic is taken if empty.
$user
- WikiName, login name or cUID of user, optional. Name of logged-in user is taken if not specified.
TWiki::Func::writeLog( 'blacklist', 'Magic number is missing' )
will add a log entry like this:
| 2011-01-19 - 01:13 | guest | blacklist | TWiki.TWikiRegistration | Magic number is missing | 1.2.3.4 |Note: Older plugins that use
$TWiki::cfg{LogFileName}
or call the internal TWiki
function directly should be fixed to use writeLog
.
To maintain compatibility with older TWiki releases, you can write conditional code as follows:
if( defined &TWiki::Func::writeLog ) { # use writeLog TWiki::Func::writeLog( 'myevent', $extra, $web, $topic ); } else { # deprecated code if plugin is used in older TWiki releases $TWiki::Plugins::VERSION > 1.1 ? $TWiki::Plugins::SESSION->writeLog( 'myevent', "$web.$topic", $extra ) : TWiki::Store::writeLog( 'myevent', "$web.$topic", $extra ); }
$time
- Time in epoc seconds
$format
- Format type, optional. Default e.g. '2014-12-31 - 19:30'
. Can be '$iso'
(e.g. '2014-12-31T19:30Z'
), '$rcs'
(e.g. '2014/12/31 23:59:59'
, '$http'
for HTTP header format (e.g. 'The, 2014-07-23 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'
Since: TWiki::Plugins::VERSION 1.020 (26 Feb 2004)
$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" );
$text
- Text to encode, may be empty
$extra
- Additional characters to include in the set of encoded characters, optional
$text
Entity encoded text
Since: TWiki::Plugins::VERSION 6.00
Escape special characters to HTML numeric entities. This is not a generic
encoding, it is tuned specifically for use in TWiki.
HTML4.0 spec:
"Certain characters in HTML are reserved for use as markup and must be
escaped to appear literally. The "<" character may be represented with
an entity, <. Similarly, ">"
is escaped as >, and "&" is escaped
as &. If an attribute value contains a
double quotation mark and is delimited by double quotation marks, then the
quote should be escaped as ".
Other entities exist for special characters that cannot easily be entered
with some keyboards..."
This method encodes HTML special and any non-printable ASCII
characters (except for \n and \r) using numeric entities.
FURTHER this method also encodes characters that are special in TWiki
meta-language.
$extras is an optional param that may be used to include additional
characters in the set of encoded characters. It should be a string
containing the additional chars.
$text
- Text to decode, may be empty
$text
Entity decoded text
Since: TWiki::Plugins::VERSION 6.00
$text
- Text to encode, may be empty
$text
URL encoded text
Since: TWiki::Plugins::VERSION 6.00
Encoding is done by converting characters that are illegal in
URLs to their %NN equivalents. This method is used for encoding
strings that must be embedded verbatim in URLs; it cannot
be applied to URLs themselves, as it escapes reserved
characters such as = and ?.
RFC 1738, Dec. '94:
...Only alphanumerics [0-9a-zA-Z], the special characters $-_.+!*'(), and reserved characters used for their reserved purposes may be used unencoded within a URL.Reserved characters are $&+,/:;=?@ - these are also encoded by this method. This URL-encoding handles all character encodings including ISO-8859-*, KOI8-R, EUC-* and UTF-8. This may not handle EBCDIC properly, as it generates an EBCDIC URL-encoded URL, but mainframe web servers seem to translate this outbound before it hits browser - see CGI::Util::escape for another approach.
$text
- Text to decode, may be empty
$text
URL decoded text
Since: TWiki::Plugins::VERSION 6.00
TWiki::Plugins
version in which the handler was first deprecated. For example, if we need to define the endRenderingHandler
for compatibility with TWiki::Plugins
versions before 1.1, we would add this to the plugin:
package TWiki::Plugins::SinkPlugin; use vars qw( %TWikiCompatibility ); $TWikiCompatibility{endRenderingHandler} = 1.1;If the currently-running TWiki version is 1.1 or later, then the handler will not be called and the warning will not be issued. TWiki with versions of
TWiki::Plugins
before 1.1 will still call the handler as required.
The following functions are retained for compatibility only. You should
stop using them as soon as possible.
getScriptUrl
instead.
Return: $path
URL path of TWiki scripts, e.g. "/cgi-bin"
WARNING: you are strongly recommended not to use this function, as the
{ScriptUrlPaths} URL rewriting rules will not apply to urls generated
using it.
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web
- Web name, e.g. 'Main'
. The current web is taken if empty
$topic
- Topic name, e.g. 'WebNotify'
$template
- Oops template name, e.g. 'oopsmistake'
. The 'oops' is optional; 'mistake' will translate to 'oopsmistake'.
$param1
... $param4
- Parameter values for %PARAM1% ... %PARAMn% variables in template, optional
$url
URL, e.g. "http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked¶m1=joe"
DEPRECATED since 1.1, the recommended approach is to throw an oops exception.
use Error qw( :try ); throw TWiki::OopsException( 'toestuckerror', web => $web, topic => $topic, params => [ 'I got my toe stuck' ]);(this example will use the
oopstoestuckerror
template.)
If this is not possible (e.g. in a REST handler that does not trap the exception)
then you can use getScriptUrl
instead:
my $url = TWiki::Func::getScriptUrl($web, $topic, 'oops', template => 'oopstoestuckerror', param1 => 'I got my toe stuck'); TWiki::Func::redirectCgiQuery( undef, $url ); return 0;Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web
- Web name, required, e.g. 'Sandbox'
getPreferencesValue
instead to determine
what permissions are set on the web, for example:
foreach my $type ( 'ALLOW', 'DENY' ) { foreach my $action ( 'CHANGE', 'VIEW' ) { my $pref = $type . 'WEB' . $action; my $val = getPreferencesValue( $pref, $web ) || ''; if( $val =~ /\S/ ) { print "$pref is set to $val on $web\n"; } } }
getListOfWebs
instead.
Get list of all public webs, e.g. all webs that do not have the NOSEARCHALL
flag set in the WebPreferences
Return: @webs
List of all public webs, e.g. ( 'Main', 'Know', 'TWiki' )
Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
formatTime
instead.
Format the time to GM time $time
- Time in epoc seconds
$format
- Format type, optional. Default e.g. '31 Dec 2002 - 19:30'
, can be 'iso'
(e.g. '2002-12-31T19:30Z'
), 'rcs'
(e.g. '2001/12/31 23:59:59'
, 'http'
for HTTP header format (e.g. 'Thu, 23 Jul 1998 07:21:56 GMT'
)
$text
Formatted time string
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$dir
Data directory, e.g. '/twiki/data'
This function violates store encapsulation and is therefore deprecated.
Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
$dir/Web/TopicName
Return: $dir
Pub directory, e.g. '/htdocs/twiki/pub'
This function violates store encapsulation and is therefore deprecated.
Use readAttachment
and saveAttachment
instead.
Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
commonTagsHandler($text, $topic, $web)
endRenderingHandler($text)
outsidePREHandler($text)
insidePREHandler($text)
startRenderingHandler($text, $web)
checkAccessPermission($type, $login, $topicText, $topicName, $webName) -> $boolean
expandCommonVariables($text, $topic, $web) -> $text
extractNameValuePair($attrs, $name) -> $value
formatGmTime($time) -> $text
getCgiQuery() -> $query
getDataDir() -> $dir
getDefaultUserName() -> $loginName
getMainWebname() -> $name
getOopsUrl($web, $topic, $template, @theParams) -> $url
getPreferencesFlag($key) -> $boolean
getPreferencesValue($key, $web) -> $value
getPublicWebList() -> @webs
getPubDir() -> $dir
getPubUrlPath() -> $path
getRevisionInfo($webName, $topic, $rev, $attachment) -> ($date, $user, $rev, $comment)
getScriptUrl($web, $topic, $script) -> $url
getScriptUrlPath() -> $path
getSessionValue($key) -> $value
getSkin() -> $skin
getTopicList($web) -> @topics
getTwikiWebname() -> $name
getUrlHost() -> $host
getViewUrl($web, $topic) -> $url
getWikiName() -> $wikiName
getWikiUserName($text) -> $wikiName
getWikiToolName() -> $name
internalLink($preamble, $web, $topic, $linkText, $anchor, $createLink) -> $text
isGuest() -> $boolean
permissionsSet($web) -> $boolean
readFile($filename) -> $text
readTemplate($name, $skin) -> $text
readTopic($webName, $topic) -> ($meta, $text)
redirectCgiQuery($query, $url)
renderText($text, $web) -> $text
saveFile($filename, $text)
setSessionValue($key, $value)
topicExists($web, $topic) -> $boolean
userToWikiName($user, $dontAddWeb) -> $wikiName
webExists($web) -> $boolean
wikiToUserName($wiki) -> $loginName
writeDebug($text)
writeHeader()
writeWarning($text)
afterEditHandler($text, $topic, $web)
beforeEditHandler($text, $topic, $web)
beforeSaveHandler($text, $topic, $web)
initializeUserHandler($loginName, $url, $pathInfo)
redirectCgiQueryHandler($query, $url)
registrationHandler($web, $wikiName, $loginName)
writeHeaderHandler($query)
checkTopicEditLock($web, $topic) ->($oopsUrl, $loginName, $unlockTime)
readTopicText($web, $topic, $rev, $ignorePermissions) -> $text
saveTopicText($web, $topic, $text, $ignorePermissions, $dontNotify) -> $oopsUrl
setTopicEditLock($web, $topic, $lock) -> $oopsUrl
afterCommonTagsHandler($text, $topic, $web)
afterSaveHandler($text, $topic, $web, $error)
beforeCommonTagsHandler($text, $topic, $web)
earlyInitPlugin()
afterAttachmentSaveHandler(\%attrHash, $topic, $web, $error, $meta)
beforeAttachmentSaveHandler(\%attrHash, $topic, $web, $meta)
checkDependencies($moduleName, $dependenciesRef) -> $error
extractParameters($attr) -> %params
formatTime($time, $format, $timezone) -> $text
getPluginPreferencesFlag($key) -> $boolean
getPluginPreferencesValue($key) -> $value
getRegularExpression($regexName) -> $pattern
mergeHandler($diff, $old, $new, \%info) -> $text
modifyHeaderHandler(\%headers, $query)
postRenderingHandler($text)
preRenderingHandler($text, \%map)
renderFormFieldForEditHandler($name, $type, $size, $value, $attributes, $possibleValues) -> $html
renderWikiWordHandler($linkText, $hasExplicitLinkLabel, $web, $topic) -> $linkText
endRenderingHandler($text)
startRenderingHandler($text, $web)
addToHEAD($id, $header)
attachmentExists($web, $topic, $attachment) -> $boolean
clearSessionValue($key) -> $boolean
checkDependencies($moduleName, $dependenciesRef) -> $error
createWeb($newWeb, $baseWeb, $opts)
expandTemplate($def ) -> $string
expandVariablesOnTopicCreation($text) -> $text
getContext() -> \%hash
getListOfWebs($filter) -> @webs
getScriptUrl($web, $topic, $script, @params) -> $url
getRevisionAtTime($web, $topic, $time) -> $rev
getWorkArea($pluginName) -> $directorypath
isValidWikiWord($text) -> $boolean
loadTemplate($name, $skin, $web) -> $text
moveAttachment($web, $topic, $attachment, $newWeb, $newTopic, $newAttachment)
moveTopic($web, $topic, $newWeb, $newTopic)
moveWeb($oldName, $newName)
normalizeWebTopicName($web, $topic) ->($web, $topic)
readAttachment($web, $topic, $name, $rev) -> $data
registerRESTHandler($alias, \&fn,)
registerTagHandler($var, \&fn, $syntax)
saveAttachment($web, $topic, $attachment, $opts)
saveTopic($web, $topic, $meta, $text, $options) -> $error
searchInWebContent($searchString, $web, \@topics, \%options) -> \%map
sendEmail($text, $retries) -> $error
wikiToEmail($wikiName) -> $email
writeHeader($query, $contentLength)
checkDependencies($moduleName, $dependenciesRef) -> $error
formatGmTime($time, $format) -> $text
getDataDir() -> $dir
getOopsUrl( $web, $topic, $template, @params ) -> $url
getPubDir() -> $dir
getPublicWebList() -> @webs
getScriptUrlPath() -> $path
afterSaveHandler($text, $topic, $web, $error, $meta)
beforeSaveHandler($text, $topic, $web, $meta)
afterRenameHandler($oldWeb, $oldTopic, $oldAttachment, $newWeb, $newTopic, $newAttachment)
afterCommonTagsHandler($text, $topic, $web, $meta)
beforeCommonTagsHandler($text, $topic, $web, $meta)
commonTagsHandler($text, $topic, $web, $included, $meta)
decodeFormatTokens($str) -> $unencodedString
eachChangeSince($web, $time) -> $iterator
eachGroup() -> $iterator
eachGroupMember($group) -> $iterator
eachMembership($wikiname) -> $iterator
eachUser() -> $iterator
emailToWikiNames($email, $dontAddWeb) -> @wikiNames
expandCommonVariables($text, $topic, $web, $meta) -> $text
getCanonicalUserID( $user ) -> $cUID
getExternalResource($url) -> $response
getSessionKeys() -> @keys
isAnAdmin($login) -> $boolean
isGroup($group) -> $boolean
isGroupMember($group, $login) -> $boolean
isTrue($value, $default) -> $boolean
popTopicContext()
pushTopicContext($web, $topic)
sanitizeAttachmentName($fname) -> ($fileName, $origName)
setPreferencesValue($name, $val)
spaceOutWikiWord($word, $sep) -> $text
wikiNameToEmails($wikiname) -> @emails
permissionsSet($web) -> $boolean
getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url
buildWikiWord( $text ) -> $text
registerTagHandler
has two new parameters $meta
and $textRef
afterAttachmentSaveHandler(\%attrHash, $topic, $web, $error, $meta)
-- added $meta
beforeAttachmentSaveHandler(\%attrHash, $topic, $web, $meta)
= added =$meta
writeLog( $action, $extra, $web, $topic, $user )
viewRedirectHandler( $session, $web, $topic )
isAnAdmin( $user, $topic, $web ) -> $boolean
-- added $topic
and $web
expandVariablesOnTopicCreation( $text, $web, $topic ) -> $text
-- added $web
and $topic
postExternalResource( $url, $text, \@headers, \%params ) -> $response
registerExternalHTTPHandler( \&fn )
getContentMode( $web ) -> $contentMode
webWritable( $web ) -> $boolean
getDiskList() -> @diskIDs
getDiskInfo($web, $siteName) -> ($dataDir, $pubDir, $diskID)
trashWebName(web => $web | disk => $diskID) -> $trashWebName
entityEncode( $text, $extra ) -> $text
entityDecode( $text ) -> $text
urlEncode( $text ) -> $text
urlDecode( $text ) -> $text
viewFileRedirectHandler( $session, $web, $topic )
topicTitleHandler( $session, $web, $topic, $titleRef )
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 -method POST -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 authorized users should be allowed to execute scripts from the command line. | TWikiAdminGroup |
method |
Commad-line only; set the HTTP request method. Some scripts requires the POST method under certain circumstances. In such a case, you need to specify the POST method to run the script from a command line. | GET |
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') |
|
template |
Specify a different skin template, overriding the 'edit' template the edit script would normally use. Use this for specialized templates in a TWiki Application. This parameter is not commonly used. | |
contenttype |
Optional parameter that defines the application type to write into the CGI header. Defaults to text/html . May be used to invoke alternative client applications |
|
anyname |
Any parameter can passed to the new topic; if the template topic contains %URLPARAM{"anyname"}% , it will be replaced by its value |
|
breaklock |
If set, any lease conflicts will be ignored, and the edit will proceed even if someone is already editing the topic. | |
redirectto |
If the user continues from edit to save, and if the save (or cancels the edit) process is successful, save will redirect to this topic or URL. The parameter value can be a TopicName , a Web.TopicName , or a URL.Note: Redirect to a URL only works if it is enabled in configure (Security setup > Miscellaneous {AllowRedirectUrl} ). |
|
t |
Provide a unique URL each time a topic is edited, typically specifying parameter t=%SERVERTIME{$epoch}% in an edit link. This is done to prevent browsers from caching an edit session, which could result in editing outdated content. The parameter name and value is arbitrary, but must be unique each time. |
Status
the parameter name is Status
. X
characters in the topic name will be converted on save to a number such that the resulting topic name is unique in the target web.
EDIT_SKIN
, which is used as the value of the cover
parameter in edit
URLs. This allows you to override the default edit skin on a web, topic or user basis.
login
Parameter | Description | Default |
---|---|---|
origurl |
URL that was being accessed when an access violation occurred. the login process will redirect to this URL if it is successful | none |
username |
username of user logging in | none |
password |
password of user logging in | none |
logon
manage
Parameter | Description | Default |
---|---|---|
action |
One of createweb , renameweb , deleteUserAccount , editSettings or saveSettings |
none |
manage
script can only be called via http POST method for createweb
renameweb
, and deleteUserAccount
.
action=createweb
Parameter | Description | Default |
---|---|---|
newweb |
Name of the new web | '' |
baseweb |
Name of the web to copy to create the new web | '' |
webbgcolor |
value for WEBBGCOLOR | '' |
sitemapwhat |
Value for SITEMAPWHAT | '' |
nosearchall |
Value for NOSEARCHALL | '' |
action=renameweb
Parameter | Description | Default |
---|---|---|
newsubweb |
Name of the web after move | '' |
newparentweb |
New parent web name | '' |
confirm |
If defined, requires a second level of confirmation. Supported values are "getlock", "continue", and "cancel" | '' |
action=editSettings
action=saveSettings
Parameter | Description | Default |
---|---|---|
text |
Text of the topic | '' |
originalrev |
Revision that the edit started on | Most recent revision |
redirectto |
If the savesettings process is successful, save will redirect to this topic or URL. The parameter value can be a TopicName , a Web.TopicName , or a URL.Note: Redirect to a URL only works if it is enabled in configure (Security setup > Miscellaneous {AllowRedirectUrl} ). |
action=bulkRegister
Parameter | Description | Default |
---|---|---|
OverwriteHomeTopics |
Whether to overwrite existing home topics or not | false |
EmailUsersWithDetails |
Whether to mail registered users or not | false |
LogTopic |
Topic to save the log in | Same as topic name, with 'Result' appended. |
action=changePassword
Parameter | Description | Default |
---|---|---|
username |
god alone knows | none |
oldpassword |
current password | none |
password |
new password | none |
passwordA |
new password confirmation | none |
email |
new email address | none |
password, =passwordA
and email
are optional. If neither or password
and passwordA
is set, then the user password is left unchanged. If email
is unset, their email is left unchanged.
action=resetPassword
Parameter | Description | Default |
---|---|---|
LoginName |
list of usernames to reset | none - error if not set |
Introduction |
message to be sent alongside the reset, most often used to announce to the user that they have been given an account. | '' |
action=deleteUserAccount
Parameter | Description | Default |
---|---|---|
password |
Users' password | none |
oops
oops
templates are used with the oops
script to generate system messages. This is done to make internationalization or other local customizations simple.
The oops
script supports the following parameters:
Parameter | Description | Default |
---|---|---|
template |
Name of the template file to display | |
def |
Optional, can be set to the name of a single definition within template . This definition will be instantiated in the template wherever %INSTANTIATE% is seen. This lets you use a single template file for many messages. For an example, see oopsmanagebad.tmpl . |
|
paramN |
Where N is an integer from 1 upwards. These values will be substituted into template for %PARAM1% etc. |
preview
save
script.
rdiff
Parameter | Description | Default |
---|---|---|
rev1 | the higher revision | |
rev2 | the lower revision | |
render | the rendering style {sequential, sidebyside, raw, debug} | DIFFRENDERSTYLE, sequential |
type | {history, diff, last} history diff, version to version, last version to previous | diff |
context | number of lines of context |
register
Parameter | Description | Default |
---|---|---|
action |
register or verify or resetPassword or approve |
|
topicparent |
The parent topic of the new user profile page | {UsersTopicName} configure setting |
register
script can only be called via http POST method, not GET. Make sure to specify the "post"
method if you call the register
script via a form action.
rename
Parameter | Description | Default |
---|---|---|
skin |
skin(s) to use | |
newweb |
new web name | |
newtopic |
new topic name | |
breaklock |
||
attachment |
||
confirm |
if defined, requires a second level of confirmation | |
currentwebonly |
if defined, searches current web only for links to this topic | |
nonwikiword |
if defined, a non-wikiword is acceptable for the new topic name | |
redirectto |
If the rename process is successful, rename will redirect to this topic or URL. The parameter value can be a TopicName , a Web.TopicName , or a URL.Note: Redirect to a URL only works if it is enabled in configure (Security setup > Miscellaneous {AllowRedirectUrl} ). |
|
disablefixlinks |
Bypass fixing WikiWord links in the rename destination topic if rename is done across webs. Fixing links in the renamed topic such as from SomeLink to Otherweb.SomeLink is usually desirable so that links in the copied topic still point to the same target | off (links are fixed) |
rename
script can only be called via http POST method, not GET. Make sure you specify method="post"
if you call the rename
script via a form action.
copy
Parameter | Description | Default |
---|---|---|
newweb |
destination web name | current web |
newtopic |
destination topic name | current topic |
nonwikiword |
if defined, a non-wikiword is acceptable for the destination topic name | |
redirectto |
If the copy process is successful, copy will redirect to this topic or URL. The parameter value can be a TopicName , a Web.TopicName , or a URL.Note: Redirect to a URL only works if it is enabled in configure (Security setup > Miscellaneous {AllowRedirectUrl} ). |
|
overwrite |
By default, copy does not happen if the destination topic already exists. If this parameter is 'on' , the destination topic is deleted if exists before copying takes place |
off (no overwrite) |
disablefixlinks |
Bypass fixing WikiWord links in the copy destination topic if copy is done across webs. Fixing links in the copied topic such as from SomeLink to Otherweb.SomeLink is usually desirable so that links in the copied topic still point to the same target | off (links are fixed) |
mdrepo
rest
TWiki::Func::registerRESTHandler
method. The rest
script will print the result directly to the browser unless the endPoint
parameter is specified, in which case it will output a redirect to the given topic.
The rest
script supports the following parameters:
username |
If TemplateLogin , or a similar login manager not embedded in the web server, is used, then you need to pass a username and password to the server. The username and password parameters are used for this purpose. |
password |
See username |
topic |
If defined as the full name (including web) of a topic, then when the script starts up plugins will be passed this as the "current" topic. If not defined, then Main.WebHome will be passed to plugins. |
endPoint |
Where to redirect the response once the request is served, in the form "Web.Topic" |
rest
script should always require authentication in any TWiki that has logins. Otherwise there is a risk of opening up major security holes. So make sure you add it to the list of authenticated scripts if you are using ApacheLogin
.
rest
script assumes that it will be called with URL in the form:
http://my.host/bin/rest/<subject>/<verb>
where <subject>
must be the WikiWord name of one of the installed TWikiPlugins, and the <verb>
is the alias for the function registered using the TWiki::Func::registerRESTHandler
method. The <subject>
and <verb>
are then used to lookup and call the registered function.
<subject>
and <verb>
are checked for illegal characters exactly in the same way as the web and topic names.
As an example, the EmptyPlugin has registered a function to be used with the rest
script under the subject EmptyPlugin and the verb example. Click below to see the rest
script in action (run as TWikiGuest).
Call the Plugin
Note that for Plugins to register REST handlers, they must be enabled in configure
.
save
save
script performs a range of save-related functions, as selected by the action
parameter.
Parameter | Description | Default |
---|---|---|
action_save=1 |
default; save, return to view, dontnotify is off |
|
action_quietsave=1 |
save, and return to view, dontnotify is on |
|
action_checkpoint |
save and redirect to the edit script, dontnotify is on |
|
action_cancel |
exit without save, return to view | |
action_preview |
preview edited text | |
action_addform |
Redirect to the "change form" page. | |
action_replaceform... |
Redirect to the "change form" page. | |
action_delRev |
Administrators only delete the most recent revision of the topic - all other parameters are ignored. You have to be an administrator to use this, and not all store implementations will support it. | |
action_repRev |
Administrators only replace the text of the most recent revision of the topic with the text in the text parameter. text must included embedded meta-data tags. All other parameters are ignored. You have to be an administrator to use this, and not all store implementations will support it. |
|
onlynewtopic |
If set, error if topic already exists | |
onlywikiname |
If set, error if topic name is not a WikiWord | |
dontnotify |
if defined, suppress change notification | |
templatetopic |
Name of a topic to use as a template for the text and form (new topic only) | |
text |
New text of the topic | |
forcenewrevision |
if set, forces a revision even if TWiki thinks one isn't needed | |
topicparent |
If 'none' remove any current topic parent. If the name of a topic, set the topic parent to this. | |
formtemplate |
if defined, use the named template for the form (will remove the form is set to 'none') | |
editaction |
When action is checkpoint , add form or replace form... , this is used as the action parameter to the edit script that is redirected to after the save is complete. |
|
originalrev |
Revision on which the edit started. | |
edit |
The script to use to edit the topic when action is checkpoint |
edit |
editparams |
The parameter string to use to edit the topic | |
redirectto |
The save process will redirect to this topic or URL if it is successful. (Typically this would be the URL that was being viewed when edit was invoked). The parameter value can be a TopicName , a Web.TopicName , or a URL.Note: Redirect to a URL only works if it is enabled in configure (Security setup > Miscellaneous {AllowRedirectUrl} ). |
view topic being edited |
oops
page.
The parameters are interpreted in according to the following rules.
X
characters in the topic name will be converted to a number such that the resulting topic name is unique in the target web.
save
, checkpoint
, quietsave
, or preview
: text
parameter, if it is defined, templatetopic
, if it is defined, (new topic only)
formtemplate
, if defined templatetopic
, if defined, (new topic only)
templatetopic
, if defined, (new topic only)
text
and originalrev
is > 0 and is not the same as the revision number of the most recent revision. If merging is enabled both the topic and the meta-data are merged.
Form field values are passed in parameters named 'field' - for example, if I have a field Status
the parameter name is Status
.
Note: The save
script can only be called via http POST method, not GET. Make sure to specify the "post"
method if you call the save
script via a form action. Example:
<form name="new" action="%SCRIPTURLPATH{save}%/Sandbox/" method="post"> ... </form>It is not possible to call
save
from an <a href="">
link.
search
%SEARCH%
functionality driven by the following CGI parameters:
Parameter: | Description: | Default: |
---|---|---|
"text" |
Search term. Is a keyword search, literal search or regular expression search, depending on the type parameter. SearchHelp has more |
required |
search="text" |
(Alternative to above) | N/A |
web="Name" web="Main, Know" web="all" |
Comma-separated list of webs to search. See VarSEARCH for more details. | Current web |
topic="WebPreferences" topic="*Bug" |
Limit search to topics: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. | All topics in a web |
excludetopic="Web*" excludetopic="WebHome, WebChanges" |
Exclude topics from search: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. | None |
type="keyword" type="literal" type="regex" |
Do a keyword search like soap "web service" -shampoo ; a literal search like web service ; or RegularExpression search like soap;web service;!shampoo |
%SEARCHVAR- DEFAULTTYPE% preferences setting (literal) |
scope="topic" scope="text" scope="all" |
Search topic name (title); the text (body) of topic; or all (both) | "text" |
sort="topic" sort="created" sort="modified" sort="editby" sort="parent" sort= |
Sort the results of search by the topic names, topic creation time, last modified time, last editor, parent topic name, or named field of TWikiForms. The sorting is done web by web; in case you want to sort across webs, create a formatted table and sort it with TablePlugin's initsort | Sort by topic name |
limit="all" limit="16" |
Limit the number of results returned. This is done after sorting if sort 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 search header Topics: Changed: By: |
Show search header |
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 tag on the same line will be rendered as part of the table generated by the search, if appropriate. |
off |
separator=", " |
Line separator between hits | Newline "$n" |
statistics
Parameter | Description | Default |
---|---|---|
webs |
comma-separated list of webs to run stats on | all accessible webs |
logdate |
YYYYMM to generate statistics for | current month |
upload
multipart/form-data
format.
Parameter | Description | Default |
---|---|---|
hidefile |
If defined, will not show file in attachment table | |
filepath |
Local (client) path name of the file being uploaded. This is used to look up the data for the file in the HTTP query. | |
filename |
Deprecated, do not use | |
filecomment |
Comment to associate with file in attachment table | |
createlink |
If defined, will create a link to file at end of topic | |
changeproperties |
If defined, this is a property change operation only - no file will be uploaded. | null |
updatefield |
If defined and if the value matches the name of a form field, it will update that form field with the format defined by the updateformat parameter. |
|
updateformat |
Format of the value of the form field indicated by the updatefield parameter. The default is the name of the attached file, but can be set to include more, such as the path to the image, %PUBURL%/%BASEWEB%/%BASETOPIC%/$filename . |
$filename |
curl
to upload files from the command line using this script.
Note: The upload
script can only be called via http POST method, not GET.
view
Parameter | Description | Default |
---|---|---|
raw=on |
Shows the text of the topic in a scrollable textarea | |
raw=debug |
As raw=on , but also shows the metadata (forms etc) associated with the topic. |
|
raw=text |
Shows only the source of the topic, as plain text (Content-type: text/plain). Only shows the body text, not the form or other meta-data. | |
raw=expandvariables |
Similar to raw=text but TWiki variables are expanded. |
|
raw=all |
Shows only the source of the topic, as plain text (Content-type: text/plain), with embedded meta-data. This may be useful if you want to extract the source of a topic to a local file on disc. | |
section |
Allows to view only a part of the topic delimited by a named section (see VarSTARTSECTION). If the given section is not present, no topic content is displayed. | |
contenttype |
Allows you to specify a different Content-Type: (e.g. contenttype=text/plain ) |
|
rev |
Revision to view (e.g. rev=45 ) |
|
template |
Allows you to specify a different skin template, overriding the 'view' template the view script would normally use. The default template is view . For example, you could specify /twiki/bin/view/TWiki/TWikiScripts?template=edit. This is mainly useful when you have specialized templates for a TWiki Application. |
|
topic |
redirects to show the specified Web.Topic, or, redirects to a URL, if allowed by {AllowRedirectUrl} and {PermittedRedirectHostUrls} configure settings |
|
createifnotexist |
If createifnotexist is set to 1 and in case the topic does not exist, it is created automatically on view. Useful to create topics automatically based on a specific template (see example below). Behind the scene, the view script redirects first to the save script, passing along all URL parameters. Thus all URL parameters of the save script can be used, such as templatetopic , topicparent and redirectto . Next, the save script creates the topic and redirects back to the view script (or displays an error in case there were any issues creating the topic). |
|
extralog |
Add additional text to TWiki log, next to the user agent string. Useful to log actions by cache scripts and crawlers. |
createifnotexist
to link to the bookmark page of a user, and to create the page on the fly if needed:[[%SCRIPTURL{view}%/%USERSWEB%/%WIKINAME%Bookmarks?createifnotexist=1&templatetopic=%SYSTEMWEB%.UserBookmarksTemplate&topicparent=%WIKINAME%][Bookmarks]]
For historical reasons, the view
script has a special interpretation of the text
skin. In earlier TWiki versions the skin=text
parameter was used like this:
http://.../view/MyWeb/MyTopic?skin=text&contenttype=text/plain&raw=on
which shows the topic as plain text; useful for those who want to download plain text for the topic.
Using skin=text
this way is DEPRECATED, use raw=text
instead.
viewfile
pub
) directory using a URL. However if it contains sensitive information, you will want to protect attachments using TWikiAccessControls. In this case, you can use the viewfile
script to give access to attachments while still checking access controls.
Parameter | Description | Default |
---|---|---|
filename |
name of attachment | |
rev |
Revision to view | |
debug |
Put debug info to the debug log |
filename
parameter, you can append the attachment name
to the end of the URL path (after the topic) e.g. http://www.omega34.dyndns.org/twiki/bin/viewfile/Webname/TopicName/Attachment.gif
In that case, determining the attachment file name is non-trivial -- please consider a file name having multiple dots and a file name having no dots.
As such, the process of determining the file name is put on the debug log if debug=1
URL parameter is supplied.
twiki/tools
directory.
geturl.pl
wget
and curl
commands. geturl.pl <host> <path> [<port> [<header>]]
geturl.pl some.domain /some/dir/file.html 80
http://some.domain:80/some/dir/file.html
rewriteshebang.pl
#!/usr/bin/perl
shebang lines specific to your local Perl installation. It will rewrite the first line of all your TWiki cgi scripts so they use a different shebang line. Use it if your perl is in a non-standard location, or you want to use a different interpreter (such as 'speedy').
tick_twiki.pl
0 0 * * 0 cd /usr/twiki/bin && perl ../tools/tick_twiki.pl
Note: The script has to be run by a user who can write files created by the webserver user.
Related Topics: AdminDocumentationCategory, DeveloperDocumentationCategory
-- Contributors: TWiki:Main.ArthurClemens, TWiki:Main.CrawfordCurrie, TWiki:Main.MichaelDaum, TWiki:Main.PeterThoeny, TWiki:Main.RafaelAlvarez, TWiki:Main.SvenDowideit, TWiki:Main.ThomasWeigert, TWiki:Main.WillNorris
Back to top
%TEXT%
, which is expanded to the raw text of the page
%SET{"VARIABLE" value="VALUE"}%
and %CALCULATE{"$SET(VARIABLE, VALUE)"}%
in an INCLUDE'd topic take effect since %INCLUDE{...}%
, %SET{...}%
, and %CALCULATE{...}%
are variables expanded in a later stage.
But " * Set VARIABLE = VALUE"
in an INCLUDE'd topic doesn't have a chance to be read.
%TMPL:XXX{...}%
or %TMPL:XXX%
.
%SET{"foo" value="abc"}% %GET{"foo"}% %SET{"foo" value="def"}% %GET{"foo"}%Result:
abc def
%CALCULATE{...}%
and %GET{...}%
.
Those don't make structural difference to how a TWiki topic is written.
Those variables are introduced by calling e.g. TWiki::Func::registerTagHandler('CALCULATE', \&_CALCULATE)
in initPlugin()
in the plugin code file.
Some plugins extend TWiki markup.
For example, the table notation in TWiki (an example shown below) is provided by the TablePlugin. Though the table notation is regarded as an integral part of TWiki markup, it is implemented by a plugin rather than the TWiki core.
| One One | One Two | One Three | | ^ | Two Two | Two Three | | Three One | ^ | Three Three |There are various places in the TWiki core where functions provided by plugins are called. For example, TablePlugin has a function named
preRenderingHandler()
defined.
It's called before the TWiki markup to HTML conversion takes place.
As you can imagine, if a plugin has postRenderingHandler()
defined, it's called after the core TWiki markup to HTML processing.
A plugin may have commonTagsHandler()
defined, which is called immediately after normal TWiki variables are expanded.
Since a commonTagsHandler()
may yield TWiki variables, normal TWiki variable expansion is conducted again after that.
SpreadSheetPlugin has commonTagsHandler()
defined to process %CALC{...}%
. You may think %CALC{...}%
can be implemented simply by TWiki::Func::registerTagHandler()
but it cannot be since %CALC{...}%
needs to look outside its parameters to do things such as %CALC{"$SUM($ABOVE())"}%
.
In addition to preRenderingHandler()
, postRenderingHandler()
, and commonTagsHandler()
, there are other functions called from TWiki core as well.
You can see the complete list of such functions on EmptyPlugin.pm in the EmptyPlugin.
Back to top
mailnotify
is called by a background process at regular intervals. The script sends an automated e-mail to subscribed users if topics were changed in a web since the script was last run.
%NOTIFYTOPIC%
*
subscriber [ :
topics ]
Where subscriber can be a WikiName, an E-mail address, or a
group name. If subscriber contains any characters that are not legal in
an email address, then it must be enclosed in 'single' or "double" quotes. Please note that the guest user TWikiGuest does not have an email address mapped to it, and will never receive email regardless of the configuration of that user.
topics is an optional space-separated list of topics:
*
in a topic name, where it is treated as a wildcard character. A *
will match zero or more other characters - so, for example, Fred*
will match all topic names starting with Fred
, *Fred
will match all topic names ending with Fred
, and *
will match all topic names.
* daisy.cutter@flowers.comSubscribe Daisy to all changes to topics that start with
Web
.
* daisy.cutter@flowers.com : Web*Subscribe Daisy to changes to topics starting with
Petal
, and their immediate children, WeedKillers and children to a depth of 3, and all topics that match start with Pretty
and end with Flowers
e.g. PrettyPinkFlowers
* DaisyCutter: Petal* (1) WeedKillers (3) Pretty*FlowersSubscribe StarTrekFan to changes to all topics that start with
Star
except those that end in Wars
, sInTheirEyes
or shipTroopers
.
* StarTrekFan: Star* - *Wars - *sInTheirEyes - *shipTroopersSubscribe Daisy to the full content of NewsLetter whenever it has changed
* daisy@flowers.com: NewsLetter?Subscribe buttercup to NewsLetter and its immediate children, even if it hasn't changed.
* buttercup@flowers.com: NewsLetter! (1)Subscribe GardenGroup (which includes Petunia) to all changed topics under AllnewsLetters to a depth of 3. Then unsubscribe Petunia from the ManureNewsLetter, which she would normally get as a member of GardenGroup:
* GardenGroup: AllNewsLetters? (3) * petunia@flowers.com: - ManureNewsLetterSubscribe
IT:admins
(a non-TWiki group defined by a custom user mapping) to all changes to Web* topics.
* 'IT:admins' : Web*In addition to single quotes ('), double quotes (") do the same job for a non-TWiki group. A user may be listed many times in the WebNotify topic. Where a user has several lines in WebNotify that all match the same topic, they will only be notified about changes that topic once (though they will still receive individual mails for news topics). If a group is listed for notification, the group will be recursively expanded to the e-mail addresses of all members. Warning: Because an email address is not linked to a user name, there is no way for TWiki to check access controls for subscribers identified by email addresses. A subscriber identified by an email address alone will only be sent change notifications if the topic they are subscribed to is readable by guest users. You can limit what email addresses can be used in WebNotify, or even block use of emails altogether, using the
{MailerContrib}{EmailFilterIn} setting in =configure
.
Tip: List names in alphabetical order to make it easier to find the names.
Note for System Administrators: Notification is supported by an add-on to the TWiki kernel called the MailerContrib. See the MailerContrib topic for details of how to set up this service.
Note: If you prefer a news feed, point your reader to WebRss (for RSS 1.0 feeds) or WebAtom (for ATOM 1.0 feeds). Learn more at WebRssBase and WebAtomBase, respectively.
You can also use %USERSWEB%
instead of Main
, but this is not necessary even if you have renamed the main web by configuring {MainWebName}
in configure.
SEARCH
. The number of topics listed by the limit
parameter.:
%SEARCH{ ".*" web="TWiki" type="regex" nosearch="on" sort="modified" reverse="on" limit="50" }%
%SEARCH{}%
.
SEARCH
:
%SEARCH{ "\.*" scope="topic" type="regex" nosearch="on" }%
%STATISTICSTOPIC%
TWiki also generates overall site usage statistics in Main.SiteStatistics (do not create that page, it is created automatically based on SiteStatisticsTemplate). On a monthly basis, the following items are recorded using system data and TWiki log data across all webs: Number of webs, number of topics, number of attachments, number of topic views, number of topic updates, number of files uploads, data size, pub size, disk use, number of users, number of groups, number of plugins installed compared to total number of plugins available, and the 10 top contributors.
{Log}{view}
, {Log}{save}
and {Log}{upload}
are set in configure. This will generate log file entries (see below).
twiki/bin/statistics
script from a cron job - once a day is recommended. This will update the SiteStatistics and the WebStatistics topics in all webs.
nobody
or www-data
. Example crontab entry: 0 0 * * * (cd /path/to/twiki/bin; ./statistics >/dev/null 2>&1)
nobody
: Run the utility twiki/tools/geturl.pl
in your cron job and specify the URL of the twiki/bin/statistics
script as a parameter. Example: 0 0 * * * (cd /path/to/twiki/tools; ./geturl.pl mydomain.com /urlpath/to/twiki/bin/statistics >/dev/null 2>&1)
geturl.pl
will do a TWiki CGI request as the TWikiGuest user, so if you use this workaround, the WebStatistics topics you are updating will have to be writable by TWikiGuest.
cd twiki/bin; ./statistics -logdate 2011-05 -webs TWiki,Sandbox
{Stats}{DisableInvocationFromBrowser}
config parameter is false (it's false in this installation), the twiki/bin/statistics
script can also be executed as a CGI script - just enter the URL in your browser. Examples: /twiki/bin/statistics
/twiki/bin/statistics/Main
/twiki/bin/statistics/Main?logdate=2024-11
/twiki/bin/statistics?logdate=2024-11;webs=ProjectX,ProjectY,ProjectZ
Topic | Column and part | Configuration parameter | Default |
---|---|---|---|
WebStatistics of webs | Affiliation breakdown in "Topic views", "Topic saves", and "File uploads" columns | {Stats}{TopAffiliation} |
10 |
"Most popular topic views" column | {Stats}{TopViews} |
10 | |
"Top viewers" column | {Stats}{TopViewers} |
10 | |
"Top contributors for tpoic save and uploads" column | {Stats}{TopContrib} |
10 | |
Main.SiteStatistics | The list of webs viewed the most number of times in the "Webs Viewed" column | {Stats}{SiteTopViews} |
0 |
The list of webs updated the most number of times in the "Webs Updated" column | {Stats}{SiteTopUpdates} |
0 | |
Affiliation breakdown in "Topic Views", "Topic Saves", and "File Uploads" columns | {Stats}{SiteTopAffiliation} |
10 | |
"Top Viewers" column | {Stats}{SiteTopViewers} |
10 | |
"Top Contributors" column | {Stats}{SiteTopContrib} |
10 |
Month: | Topic views: |
Topic saves: |
File uploads: |
Most popular topic views: |
Top viewerss: | Top contributors for topic save and uploads: |
---|---|---|---|---|---|---|
2013-08 | 10325 (150 unique users) 6921 R&D 1736 Operation 927 Sales 623 Management 98 Unknown |
7 (3 unique users) 7 R&D |
3 (1 unique users) 3 R&D |
6941 WebHome 872 WebSearch 848 ToolSiteMap 376 ToolDashboard 223 WebSearchAdvanced 185 ContRequests 127 WebTopicList 89 ToolPersonalWebs 72 ToolMasquerading 70 TWikiAdminUser |
525 PeterThoeny 49 MahiroAndo 9 HdeyoImazu |
5 HdeyoImazu 1 MahiroAndo 1 PeterThoeny |
getAffiliation($cUID)
object method in the current user mapping handler. It's supposed return the affiliation (division, department, etc.) of the $cUID
. If the affiliation is unknown, it returns undef
.
{Stats}{Breakdown}
configuration papameter true by putting the following line in lib/LocalSite.cfg
. $TWiki::cfg{Stats}{Breakdown} = 1;
{Stats}{ExcludedWebRegex}
config parameter as follows.
$TWiki::cfg{Stats}{ExcludedWebRegex} = '^(Trash(x\d+x)?\d*|Sandbox\d*)\b';You may wonder when this is needed. There are webs not worth updating WebStatistics such as the Trash web. When a web is deleted, it becomes a subweb of the Trash web. By default, not only the Trash web but also subwebs of the Trash web are subject to WebStatistics update. On a large TWiki site, you may have dozens of Trash webs - you may rotate Trash webs and you may be UsingMultipleDisks (each disk requires its own Trash - e.g. Trashx1x and Trashx2x). If you have Trash, Trash1, ..., Trash10 for rotation and if you use 3 disks for TWiki, you end up having 33 Trashes.
statistics
script every day, you increase the revision of each WebStatistics by one every day. If a topic has hundreds of revision, some operations such as getting the original creator of the topic takes long.
There is an option to prevent the boundless growth of WebStatistics.
If you set $TWiki::cfg{Stats}{TopicPerYear}
true, the statistics
script writes the result to WebStatisticsYYYY where YYYY is the current year (e.g. WebStatistics2024) instead of WebStatistics. The parameter is false by default. {Stats}{TopicPerYear}
to true but before you run the statistics
script, you should run twiki/tools/switch2yearlystats
to rename WebStatistics of all webs to WebStatisticsYYYY of the year. In case WebStatistics is not in the same format as its current template, it's renamed to WebStatistics0000.
{Stats}{TopicPerYear}
is true: twiki/tools/switch2yearlystats
renames Main.SiteStatistics to Main.SiteStatisticsYYYY of the year or Main.SiteStatistics0000.
statistics
script doesn't work well.
By running tools/convert_stats_twiki6
after upgrade, all statistics topics are converted for the current version of statistics
.
{Stats}{SiteTopContrib}
.
Prior to TWiki 6.0, it was specified by {Stats}{TopContrib}
.
If you have a custom {Stats}{TopContrib}
value, you need to set {Stats}{SiteTopContrib}
as well. Otherwise, the number of "Top Contributors" on SiteStatistics becomes the default value, which is 10.
log<year><month>.txt
twiki/logs/log202411.txt
| <time in GMT> | <wikiusername> | <action> | <web>.<topic> | <extra info> | <IP address> |
| 05 Nov 2024 - 12:23 | Main.TWikiGuest | view | TWiki.WebRss | | 66.124.232.02 |
Script | Action name | Extra info |
---|---|---|
attach | attach | when viewing attach screen of previous uploaded attachment: filename |
changes | changes | |
edit | edit | when editing non-existing topic: (not exist) |
login, logon, attach, edit, register, rest, view, vewfile | sudologin , sudologout | Login name of administrator user who is logging in or out |
manage | changepasswd | Login name of user who's password is changed |
mdrepo | mdrepo | operation and its arguments |
rdiff | rdiff | higher and lower revision numbers: 4 3 |
register | regstart | WikiUserName, e-Mail address, LoginName: user attempts to register |
register | register | E-mail address: user successfully registers |
register | bulkregister | WikiUserName of new, e-mail address, admin ID |
rename | rename | when moving topic: moved to Newweb.NewTopic |
rename | renameweb | when renaming a web: moved to Newweb |
rename | move | when moving attachment: Attachment filename moved to Newweb.NewTopic |
resetpasswd | resetpasswd | Login name of user who's password is reset |
save | save | when replacing existing revision: repRev 3 when user checks the minor changes box: dontNotify when user changes attributes to an exising attachment: filename.ext |
save | cmd | special admin parameter used when saving |
search | search | search string |
upload | upload | filename |
view | view | when viewing non-existing topic: (not exist) when viewing previous topic revision: r3 |
viewfile | viewfile | Attachment name and revision: File.txt, r3 |
Net::SMTP
module if it is installed on your system. Set this with the {SMTP}{MAILHOST}
setting in configure.
{SMTP}{SENDERHOST}
configure setting to set the mail sender host - some SMTP installations require this.
$ sudo setsebool -P httpd_can_sendmail on
$ sudo setsebool -P httpd_can_network_connect on
sendmail
, if the Net::SMTP
module is not installed or not functioning properly. Set the program path in {MailProgram}
and set {SMTP}{MAILHOST}
to an empty value in configure.
The notify e-mail uses the default changes.tmpl
template, or a skin if activated in the TWikiPreferences.
mailnotify also relies on two hidden files in each twiki/data/Web
directory: .changes
and .mailnotify.
Make sure both are writable by your web server process. .changes
contains a list of changes; go ahead and make this empty. .mailnotify
contains a timestamp of the last time notification was done.
cron
table so that mailnotify
is called in an interval of your choice. Please consult man crontab
of how to modify the table that schedules program execution at certain intervals. Example:
% crontab -e 0 1 * * * (cd /path/to/twiki; perl -I bin tools/mailnotify -q)The above line will run mailnotify nightly at 01:00. The
-q
switch suppresses all normal output. Details at MailerContrib.
For ISP installations: Many ISPs don't allow hosted accounts direct cron access, as it's often used for things that can heavily load the server. Workaround scripts are available.
On Windows: You can use a scheduled task if you have administrative privileges. TWiki:Codev/CronTabWin is a free scheduler for Windows.
Trash
web.
[More topic actions]
(bottom right of page) on the topic to be changed, then, in the new screen, on [Delete topic]
or [Rename/move topic]
. You can now rename and/or move/delete in one operation:
[Rename/Move]
: the topic will be renamed and links to the topic updated as requested. [Rename/Move]
.
Rename/Move/Delete
- an instruction line and undo link will appear at the bottom of the modified topic. This allows you to revert from the last modification only.
Trash
web - they are NOT physically erased from the server. All webs share Trash
- in case of a name conflict with a topic already Trash
, the user is alerted and asked to choose a new name.
The Trash
web should be be cleared periodically, by archiving (saving) the text and RCS files if required (recommended), then deleting them from the Trash
directory.
Trash
directory is all that's required for maintenance, it's possible to grant Trash
admin privileges to multiple users, while strictly limiting server access.
%META:TOPICMOVED{...}%
. Customize something like this:
%METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%Note: Do not modify the TWiki.WebTopicViewTemplate - modifications would be lost on the next TWiki upgrade. Instead, create a WebTopicViewTemplate in the Main web with the same content and modify it to your needs.
%SEARCH%
, with a special template, finds and displays all occurrences of the topic name in other topics, site-wide. These referring links are by default automatically changed to the new topic and/or web name. This includes relevant TWikiMetaData definitions. <pre>
and <verbatim>
are honored - no changes are made to text within these areas.
topic
. Next, all webs (including the current one) are listed that match web.topic
. All webs will be searched during rename, even if NOSEARCHALL
is defined on a web, though access permissions will of course be honored.
Changed references are kept are as short as possible, ex: topic
is used in preference to web.topic
.
VIEW
, CHANGE
and RENAME
access to that topic. To alter referring topics, you need CHANGE
access. See TWikiAccessControl for information on setting up access permissions.
search
can show matches that will not be updated due to case differences. Other mismatches with actual rendered output are also possible as the approaches are so different.
The following shows some limitations of square bracket processing.
[[Old Topic]] => [[NewTopic][Old Topic]] [[old topic]] => [[NewTopic][old topic]] [[old t opic]] => not changed [[OldTopic]] => [[NewTopic]]Related Topics: UserDocumentationCategory, AdminDocumentationCategory Back to top
http://twiki.example.com/do/view/Sandbox/WebNotify
tells us that we view topic WebNotify located in the Sandbox web.
Tip: The URL of a web's homepage ends in /WebHome
by default. The name of the homepage topic can safely be omitted to make for shorter and more legible links. For example, http://twiki.example.com/do/view/Sandbox
links to the homepage of the Sandbox web.
_default
).