 Log In
|
Start of topic | Skip to actions
TWiki Reference Manual (Wed, 08 Feb 2006 build 8740)This page contains all documentation topics as one long, complete reference sheet.Doubleclick anywhere to return to the top of the page.
TWiki System RequirementsServer and client requirements Low client and server base requirements are core features that keep TWiki widely deployable, particularly across a range of browser platforms and versions. Many Plugins and contrib modules exist which enhance and expand TWiki's capabilities; they may have additional requirements.Server RequirementsTWiki is written in Perl 5, uses a number of shell commands, and requires RCS (Revision Control System), a GNU Free Software package. TWiki is developed in a basic Linux/Apache environment. It also works with Microsoft Windows, and should have no problem on any other platform that meets the requirements.
Required CPAN ModulesThe following Perl modules are used by TWiki:
Optional CPAN ModulesThe following Perl modules may be used by TWiki:
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"' Client RequirementsThe TWiki standard installation has relatively low browser requirements:
Important note about TWiki Plugins
TWiki Installation GuideInstallation instructions for the TWiki 4.0 production release. TWiki should be fine with any web server and OS that meet the system requirements. The following installation instructions are written for experienced system administrators; please review the AdminSkillsAssumptions before you install TWiki. If you need help, ask a question in the TWiki:Support web or on TWiki:Codev.TWikiIRC (irc.freenode.net, channel #twiki) Hint: TWiki:TWiki.InstallingTWiki on TWiki.org has supplemental documentation that help you install TWiki on different platforms, environments and web hosting sites.
Basic Installation
http://yourdomain.com/twiki/bin/view and start TWiki-ing away!
Next StepsOnce you have your TWiki running, you can move on to customise it for your users.
Troubleshooting
TWiki Upgrade GuideUpgrade from the previous TWiki 01-Sep-2004 Prodcution Release to TWiki-4.0.0OverviewTWiki-4.0.0 is a major new release. You can chose between an automated upgrade using a script or a manual update.Upgrade Requirements
Major Changes Compared to TWiki Release 01-Sep-2004See TWikiReleaseNotes04x00x00.Automated Upgrade ProcedureIf you would prefer to do things manually, or if you made custom modifications to distributed files (except topics), then skip to the manual upgrade procedure below. The upgrade script is called"UpgradeTwiki", and is found in the root of the distribution. It can be run by any user, though you will need to make sure you correct the permissions so that the webserver user can write all files in the new installation when you have finished. The upgrade script does not write to your existing installation.
The upgrade script will upgrade the TWiki core only. Plugins will need to be upgraded separately.
Note: To upgrade from a Beta, do not use UpgradeTWiki. Instead follow the steps outlined in Upgrading a Beta, below.
It will:
UpgradeTwiki will give you the final instructions.
Visit TWiki:Codev.KnownIssuesOfTWiki04x00x00 and fix known issues that apply to you.
There are a few points worth noting:
UpgradeTwiki more robust.
Manual Upgrade ProcedureThe following steps are a rough guide to upgrading only. It is impossible to give detailed instructions, as what you have to do may depend on whether you can configure the webserver or not, and how much you have changed distributed files in your current TWiki release.
Upgrading a BetaIf you followed the recommendations and avoided modifying any distributed files, then this is quite straightforward:
TWiki User AuthenticationTWiki site access control and user activity tracking optionsOverviewAuthentication, or "login", is the process by which a user lets TWiki know who they are. Authentication isn't just to do with access control. TWiki uses authentication to identify users, so it can keep track of who made changes, and manage a wide range of personal settings. With authentication enabled, users can personalise TWiki and contribute as recognised individuals, instead of shadows. TWiki authentication is very flexible, and can either stand alone or integrate with existing authentication schemes. You can set up TWiki to require authentication for every access, or only for changes. Authentication is also essential for access control. Quick Authentication Test - Use the %WIKIUSERNAME% variable to return your current identity:
 Tip: TWiki:TWiki.TWikiUserAuthenticationSupplement on TWiki.org has supplemental documentation on user authentication.
Password ManagementAs shipped, TWiki supports the Apache 'htpasswd' password manager. This manager supports the use of.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.
New User RegistrationNew user registration uses the password manager to set and change passwords. It is also responsible for the new user verification process. the registration process supports single user registration via the TWikiRegistration page, and bulk user registration via the BulkRegistration page (for admins only). The registration process is responsible for creating user topics.Login ManagementLogin management controls the way users have to log in. There are three basic options; no login, login via a TWiki login page, and login using the webserver authentication support. You can select your chosen login through the Security Settings pane in theconfigure interface.
No LoginDoes exactly what it says on the tin. Forget about authentication to make your site completely public - anyone can browse and edit freely, in classic Wiki style. All visitors are given the TWikiGuest default identity, so you can't track individual user activity. Note: This setup is not recommended on public websites for security reasons; anyone would be able to change system settings and perform tasks usually restricted to the TWikiAdminGroup.
Template LoginTemplate Login asks for a username and password in a web page, and processes them using whatever Password Manager you choose. Users can log in and log out.Enabling Template Login
At this time TWikiAccessControls cannot control access to files in the 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 deleting or adding input tags. The name="" parameter of the input tags must start with: "Twk0..." (if this is an optional entry), or "Twk1..." (if this is a required entry). This ensures that the fields are carried over into the user home page correctly.
You can customize the default user home page in NewUserTemplate. The same variables get expanded as in the template topics
Apache LoginUsing this method TWiki does not authenticate users internally. Instead it depends on theREMOTE_USER environment variable, which is set when you enable authentication in the webserver.
The advantage of this scheme is that if you have an existing website authentication scheme using Apache modules such as mod_auth_ldap or mod_auth_mysql you can just plug in directly to them.
The disadvantage is that because the user identity is cached in the browser, you can log in, but you can't log out again unless you restart the browser.
TWiki maps the REMOTE_USER that was used to log in to the webserver to a WikiName using the table in TWikiUsers. This table is updated whenever a user registers, so users can choose not to register (in which case their webserver login name is used for their signature) or register (in which case that login name is mapped to their WikiName).
The same private .htpasswd file used in TWiki Template Login can be used to authenticate Apache users, using the Apache Basic Authentication support. This allows the TWiki registration support to maintain usernames and passwords.
Enabling Apache Login using
You can use any other Apache authentication module that sets REMOTE_USER. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Web | Sitemap | VIEW | CHANGE | RENAME | |||
|---|---|---|---|---|---|---|---|
| Listed | DENY | ALLOW | DENY | ALLOW | DENY | ALLOW | |
| Main ... | on | TWikiGuest | TWikiGuest | ||||
| TWiki ... | on | TWikiGuest | TWikiAdminGroup | TWikiAdminGroup | |||
| BettyWalls ... | off | TWikiGuest | TWikiAdminGroup, BettyWalls | TWikiGuest | TWikiAdminGroup, BettyWalls | ||
| HRPM ... | on | TWikiGuest | TWikiGuest | ||||
| PerlClass ... | on | TWikiGuest | TWikiGuest | ||||
| RichmondPM ... | on | TWikiGuest | TWikiGuest | ||||
Main web, such as the TWikiAdminGroup. To create a new group, visit TWikiGroups and enter the name of the new group ending in Group into the "new group" form field. This will create a new group topic with two important settings: Set GROUP = list of Users and/or Groups
Set ALLOWTOPICCHANGE = list of Users and/or Groups
Set GROUP = Main.SomeUser, Main.OtherUser, Main.SomeGroup
Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup
Note: TWiki has strict formatting rules. Make sure you have three spaces, an asterisk, and an extra space in front of any access control rule.
TWikiAdminGroup. The name of this topic is defined by the {SuperAdminGroup} configure setting. Example group setting: Set GROUP= Main.ElizabethWindsor, Main.TonyBlair
Set DENYWEBVIEW = comma-delimited list of Users and Groups
Set ALLOWWEBVIEW = comma-delimited list of Users and Groups
Set DENYWEBCHANGE = comma-delimited list of Users and Groups
Set ALLOWWEBCHANGE = comma-delimited list of Users and Groups
Set DENYWEBRENAME = comma-delimited list of Users and Groups
Set ALLOWWEBRENAME = comma-delimited list of Users and Groups
For Web level access rights setting any of these settings to an empty value has the same effect as not setting them at all. Please note that the documentation of TWiki 4.0 and earlier versions of TWiki 4.1 did not reflect the actual implementation, e.g. an empty ALLOWWEBVIEW does not prevent anyone from viewing the web, and an empty DENYWEBVIEW does not allow all to view the web.
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
Be careful with empty values for any of these.
Set ALLOWTOPICVIEW = Set DENYTOPICVIEW = Setting to an empty value has caused confusion and great debate and it has been decided that the empty setting syntax will be replaced by something which is easier to understand in the 4.2 version of TWiki.
See "How TWiki evaluates ALLOW/DENY settings" below for more on how ALLOW and DENY interacts.
mod_rewrite module, and configure your webserver to redirect accesses to attachments to the TWiki viewfile script. For example,
ScriptAlias /twiki/bin/ /filesystem/path/to/twiki/bin/ Alias /twiki/pub/ /filesystem/path/to/twiki/pub/ RewriteEngine on RewriteRule ^/twiki/pub/TWiki/(.*)$ /twiki/pub/TWiki/$1 [L,PT] RewriteRule ^/twiki/pub/([^\/]+)/([^\/]+)/([^\/]+)$ /twiki/bin/viewfile/$1/$2?filename=$3 [L,PT]That way all the controls that apply to the topic also apply to attachments to the topic. Other types of webserver have similar support. Note: Images embedded in topics will load much slower since each image will be delivered by the
viewfile script.
Attention: Use this with caution. This is deprecated and will likely change in the next release.
all webs search option from accessing obfuscated webs. Do so by enabling the NOSEARCHALL variable in WebPreferences: Set NOSEARCHALL = on
Note: Obfuscating a web without view access control is very insecure, as anyone who knows the URL can access the web.
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 in case DENYWEBVIEW and ALLOWWEBVIEW is not defined.
NOSEARCHALL variable in its WebPreferences topic: Set NOSEARCHALL = on
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 in case DENYWEBVIEW and ALLOWWEBVIEW is not defined.
NOSEARCHALL variable in its WebPreferences topic: Set NOSEARCHALL = on
| Formatting Command: | You write: | You get: | |||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Paragraphs: Blank lines will create new paragraphs. |
1st paragraph 2nd paragraph | 1st paragraph 2nd paragraph | |||||||||||||||||||||||||
|
Headings: Three or more dashes at the beginning of a line, followed by plus signs and the heading text. One plus creates a top level heading, two pluses a second level heading, etc. The maximum heading depth is 6. You can create a table of contents with the %TOC% variable. If you want to exclude a heading from the TOC, put !! after the ---+.
Empty headings are allowed, but won't appear in the table of contents.
|
---++ Sushi ---+++ Maguro ---+++!! Not in TOC |
SushiMaguroNot in TOC |
|||||||||||||||||||||||||
|
Bold Text: Words get shown in bold by enclosing them in * asterisks.
|
*Bold* | Bold | |||||||||||||||||||||||||
|
Italic Text: Words get shown in italic by enclosing them in _ underscores.
|
_Italic_ | Italic | |||||||||||||||||||||||||
|
Bold Italic: Words get shown in bold italic by enclosing them in __ double-underscores.
|
__Bold italic__ | Bold italic | |||||||||||||||||||||||||
|
Fixed Font: Words get shown in fixed font by enclosing them in = equal signs.
|
=Fixed font= |
Fixed font
|
|||||||||||||||||||||||||
|
Bold Fixed Font: Words get shown in bold fixed font by enclosing them in |
==Bold fixed== |
Bold fixed
|
|||||||||||||||||||||||||
You can follow the closing bold, italic, or other (* _ __ = ==) indicator
with normal punctuation, such as commas and full stops.
Make sure there is no space between the text and the indicators.
|
_This works_, _this does not _ |
This works, _this does not _ |
|||||||||||||||||||||||||
|
Verbatim (Literal) Text: Surround code excerpts and other formatted text with <verbatim> and </verbatim> tags. verbatim tags disable HTML code. Use <pre> and </pre> tags instead if you want the HTML code within the tags to be interpreted. NOTE: Preferences variables (* Set NAME = value) are set within verbatim tags.
|
<verbatim>
class CatAnimal {
void purr() {
<code here>
}
}
</verbatim>
|
class CatAnimal {
void purr() {
<code here>
}
}
|
|||||||||||||||||||||||||
|
Separator (Horizontal Rule): Three or more three dashes at the beginning of a line.. |
------- |
|
|||||||||||||||||||||||||
|
Bulleted List: Multiple of three spaces, an asterisk, and another space. For all the list types, you can break a list item over several lines by indenting lines after the first one by at least 3 spaces.
|
* level 1
* level 2
* back on 1
* A bullet
broken over
three lines
* last bullet
|
|
|||||||||||||||||||||||||
|
Numbered List: Multiple of three spaces, a type character, a dot, and another space. Several types are available besides a number:
|
1. Sushi 1. Dim Sum 1. Fondue A. Sushi A. Dim Sum A. Fondue i. Sushi i. Dim Sum i. Fondue |
|
|||||||||||||||||||||||||
|
Definition List: Three spaces, a dollar sign, the term, a colon, a space, followed by the definition. |
$ 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.
The TablePlugin provides the |^| multiple-span row functionality and additional rendering features
|
| *L* | *C* | *R* | | A2 | B2 | C2 | | A3 | B3 | C3 | | multi span ||| | A5-7 | 5 | 5 | |^| six | six | |^| seven | seven | | split\ | over\ | 3 lines | | A9 | B9 | C9 | |
|
|||||||||||||||||||||||||
|
WikiWord Links: CapitalizedWordsStuckTogether (or WikiWords) will produce a link automatically if preceded by whitespace or parenthesis. If you want to link to a topic in a different web write Otherweb.TopicName. 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.
It's generally a good idea to use the TWikiVariables %TWIKIWEB% and %MAINWEB% instead of TWiki and Main.
|
WebStatistics Sandbox.WebNotify Sandbox.WebHome | WebStatistics WebNotify Sandbox | |||||||||||||||||||||||||
|
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. To link to an anchor name use the [[MyTopic#MyAnchor]] syntax. You can omit the topic name if you want to link within the same topic.
|
[[WikiWord#NotThere]] [[#MyAnchor][Jump]] #MyAnchor To here | WikiWord#NotThere Jump To here | |||||||||||||||||||||||||
|
Forced Links: You can create a forced internal link by enclosing words in double square brackets. Text within the brackets may contain optional spaces; the topic name is formed by capitalizing the initial letter and by removing the spaces; for example, [[text formatting FAQ]] links to topic TextFormattingFAQ. You can also refer to a different web and use anchors.
To "escape" double square brackets that would otherwise make a link, prefix the leading left square bracket with an exclamation point.
|
[[wiki syntax]] [[Main.TWiki users]] escaped: ![[wiki syntax]] | wiki syntax Main.TWiki users escaped: [[wiki syntax]] | |||||||||||||||||||||||||
|
Specific Links: You can create a link where you specify the link text and the URL separately using nested square brackets [[reference][text]]. Internal link references (e.g. WikiSyntax) and URLs (e.g. http://TWiki.org/) are both supported.
The rules described under Forced Links apply for internal link references.
Anchor names can be added as well, to create a link to a specific place in a topic.
|
[[WikiSyntax][wiki syntax]] [[http://gnu.org][GNU]] | wiki syntax GNU | |||||||||||||||||||||||||
|
Prevent a Link: Prevent a WikiWord from being linked by prepending it with an exclamation point. |
!SunOS | SunOS | |||||||||||||||||||||||||
|
Disable Links: You can disable automatic linking of WikiWords by surrounding text with <noautolink> and </noautolink> tags. It is possible to turn off all auto-linking with a NOAUTOLINK preferences setting.
|
<noautolink> RedHat & SuSE </noautolink> | RedHat & SuSE | |||||||||||||||||||||||||
|
Mailto Links: E-mail addresses are linked automatically. To create e-mail links that have more descriptive link text, specify subject lines or message bodies, or omit the e-mail address, you can write [[mailto:user@domain][descriptive text]].
|
a@b.com [[mailto:a@b.com]\ [Mail]] [[mailto:?subject=\ Hi][Hi]] | a@b.com Mail Hi | |||||||||||||||||||||||||
<strike>deleted text</strike> to get There are a few usability and technical considerations to keep in mind: Script tags may be filtered out, at the discretion of your TWiki administrator.
<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 an HTML tag are on the same line, or the tag will be broken.
TWiki converts shorthand notation to HTML for display. To copy a fully marked-up page, simply view the source in your browser and save the contents. If you need to save HTML frequently, you may want to check out TWiki:Plugins/PublishAddOn.
<script> tags for your TWiki applications. However note that your TWiki administrator can disable <script> in topics, and may have chosen to do so for security considerations. TWiki markup and TWikiVariables are not expanded inside script tags.
http://..., https://..., ftp://..., gopher://..., news://..., file://..., telnet://... and mailto:...@... are linked automatically.
name@domain.com are linked automatically.
[[Square bracket rules]] let you easily create non-WikiWord links. [[http://yahoo.com Yahoo home page]] as an easier way of doing external links with descriptive text for the link, such as Yahoo home page.
% that are expanded on the fly.
%TOC% : Automatically generates a table of contents based on headings in a topic - see the top of this page for an example.
%WEB% : The current web, is TWiki.
%TOPIC% : The current topic name, is TextFormattingRules.
%ATTACHURL% : The attachment URL of the current topic. Example usage: If you attach a file to a topic you can refer to it as %ATTACHURL%/image.gif to show the URL of the file or the image in your text.
%INCLUDE{"SomeTopic"}% : Server side include, includes another topic. The current 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, useful for creating web-based applications.
%BR% to start a new line.
%RED% Red %ENDCOLOR% and %BLUE% blue %ENDCOLOR% colors to get: Red and blue colors.
%H% Help, %T% Tip, %X% Alert to get: Help, Tip, Alert. For more info see TWikiDocGraphics.
!%SOMEVARIABLE% to get: %SOMEVARIABLE%.
%PLUGINDESCRIPTIONS%:
"$SUM( $ABOVE() )" to tables located in wiki.fini topics.ExternalSite:Page text to external sites based on aliases defined in a rules topic=[[URL or TopicName][Link Text][Options]]==
or :cool: for :cool:<filename> is not displayed. How can I show it as it is? '<' and '>' characters have a special meaning in HTML, they define HTML tags. You need to escape them, so write '<' instead of '<', and '>' instead of '>'. 'prog <filename>' to get 'prog <filename>'.
'&' character sometimes not displayed? '&' character has a special meaning in HTML, it starts a so called character entity, i.e. '©' is the © copyright character. You need to escape '&' to see it as it is, so write '&' instead of '&'. 'This & that' to get 'This & that'.
%VARIABLE% or %VARIABLE{ parameter="value" }% - that expand into content whenever a topic is rendered for viewing. There are two types of variables: %CALC{}% variable)
%T% to get (a preferences variable)
%TOPIC% to get TWikiVariables (a predefined variable)
%CALC{ "$UPPER(Text)" }% to get TEXT (a variable defined by Plugin)
!%TOPIC% to get %TOPIC%
%ALLVARIABLES% to get a full listing of all variables defined for a particular topic
[multiple of 3 spaces] * [space] Set [space] VARIABLENAME [space] = [space] value
Examples:Spaces between the = sign and the value will be ignored. You can split a value over several lines by indenting following lines with spaces - as long as you don't try to use * as the first character on the following line.
Set VARIABLENAME = value
Set VARIABLENAME = value
Example:
* Set VARIABLENAME = value starts here
and continues here
Whatever you include in your Variable will be expanded on display, exactly as if it had been entered directly.
Example: Create a custom logo variableYou can also set preferences variables on a topic by clicking the link
- To place a logo anywhere in a web by typing
%MYLOGO%, define the Variable on the web's WebPreferences topic, and upload a logo file, ex:mylogo.gif. You can upload by attaching the file to WebPreferences, or, to avoid clutter, to any other topic in the same web, e.g.LogoTopic. Sample variable setting in WebPreferences:
Set MYLOGO = %PUBURL%/%WEB%/LogoTopic/mylogo.gif
Edit topic preference settings under More topic actions. Preferences set in this manner are not visible in the topic text, but take effect nevertheless.
Local in place of Set in the variable definition. For example, if the user sets the following in their home topic:
* Set EDITBOXHEIGHT = 10 * Local EDITBOXHEIGHT = 20Then when they are editing any other topic, they will get a 10 high edit box. However when they are editing their home topic, they will get a 20 high edit box.
Local can be used wherever a preference needs to take a different value depending on where the current operation is being performed.
Use this powerful feature with great care! %ALLVARIABLES% can be used to get a listing of the values of all variables in their evaluation order, so you can see variable scope if you get confused.
%BR% - line break
%BULLET% - bullet sign
%BB% - line break and bullet combined
%BB2% - indented line break and bullet
%RED% text %ENDCOLOR% - colored text (also %YELLOW%, %ORANGE%, %PINK%, %PURPLE%, %TEAL%, %NAVY%, %BLUE%, %AQUA%, %LIME%, %GREEN%, %OLIVE%, %MAROON%, %BROWN%, %BLACK%, %GRAY%, %SILVER%, %WHITE%)
%H% - Help icon
%I% - Idea icon
%M% - 
Moved to icon
%N% - 
New icon
%P% - 
Refactor icon
%Q% - Question icon
%S% - 
Pick icon
%T% - Tip icon
%U% - 
Updated icon
%X% - Alert icon
%Y% - 
Done icon
%SEARCH%, are powerful and general tools.
Predefined variables can be overridden by preferences variables
Plugins may extend the set of predefined variables (see individual Plugins topics for details)
Take the time to thoroughly read through ALL preference variables. If you actively configure your site, review variables periodically. They cover a wide range of functions, and it can be easy to miss the one perfect variable for something you have in mind. For example, see %INCLUDINGTOPIC%, %INCLUDE%, and the mighty %SEARCH%.
%ACTIVATEDPLUGINS%
%ALLVARIABLES%
%ATTACHURL%
http://www.fini.net/pub/TWiki/TWikiVariablesAtoM
%ATTACHURL%/image.gif
%ATTACHURLPATH%
/pub/TWiki/TWikiVariablesAtoM
configure. This is used in certain password encodings, and in login templates as part of the login prompt.
%AUTHREALM%
%TOPIC% if there is no INCLUDE
%BASETOPIC%
%WEB% in case there is no include.
%BASEWEB%
%DATE%
08 Feb 2012
Note: When used in a template topic, this variable will be expanded when the template is used to create a new topic. See TWikiTemplates#TemplateTopicsVars for details.
%DISPLAYTIME%
08 Feb 2012 - 07:13
%GMTIME%
%DISPLAYTIME{"format"}%
%DISPLAYTIME{"$hou:$min"}% expands to 07:13
"\n") and linefeed ("\r")
"<", ">", "&", single quote (') and double quote (")
"%", "[", "]", "@", "_", "*", "=" and "|"
%ENCODE{"string"}%
| Parameter: | Description: | Default: |
|---|---|---|
"string" | String to encode | required (can be empty) |
type="entity" | Encode special characters into HTML entities, like a double quote into " | URL encoding |
type="url" | Encode special characters for URL parameter use, like a double quote into %22 | (this is the default) |
%ENCODE{"spaced name"}% expands to spaced%20name
Note: Values of HTML input fields must be entity encoded, for example:<input type="text" name="address" value="%ENCODE{ "any text" type="entity" }%" />
%ENDSECTION{"name"}%
%ENDSECTION{type="include"}%
| Parameter: | Description: |
|---|---|
"name" | Name of the section. |
type="..." | Type of the section being terminated; supported types "section", "include", "templateonly". |
STARTSECTION is named, the corresponding ENDSECTION must also be named with the same name. If the STARTSECTION specifies a type, then the corresponding ENDSECTION must also specify the same type. If the section is unnamed, ENDSECTION will match with the nearest unnamed %STARTSECTION% of the same type above it.
%FAILEDPLUGINS%
%FORMFIELD{"fieldname"}%
| Parameter: | Description: | Default: |
|---|---|---|
"fieldname" | The name of a TWiki form field | required |
topic="..." | Topic where form data is located. May be of the form Web.TopicName | Current topic |
format="..." | Format string. $value expands to the field value, and $title expands to the field title | "$value" |
default="..." | Text shown when no value is defined for the field | "" |
alttext="..." | Text shown when field is not found in the form | "" |
%FORMFIELD{"ProjectName" topic="Projects.SushiProject" default="(not set)" alttext="ProjectName field found"}%
%GMTIME%
08 Feb 2012 - 13:13
Note: When used in a template topic, this variable will be expanded when the template is used to create a new topic. See TWikiTemplates#TemplateTopicsVars for details.
%GMTIME{"format"}%
| Variable: | Unit: | Example |
|---|---|---|
$seconds | seconds | 59 |
$minutes | minutes | 59 |
$hours | hours | 23 |
$day | day of month | 31 |
$wday | day of the Week (Sun, Mon, Tue, Wed, Thu, Fri, Sat) | Thu |
$dow | day of the week (Sun = 0) | 2 |
$week | number of week in year (ISO 8601) | 34 |
$month | month in ISO format | Dec |
$mo | 2 digit month | 12 |
$year | 4 digit year | 1999 |
$ye | 2 digit year | 99 |
$tz | either "GMT" (if set to gmtime), or "Local" (if set to servertime) | GMT |
$iso | ISO format timestamp | 2012-02-08T13:13:27Z |
$rcs | RCS format timestamp | 2012/02/08 13:13:27 |
$http | E-mail & http format timestamp | Wed, 08 Feb 2012 13:13:27 GMT |
$epoch | Number of seconds since 00:00 on 1st January, 1970 | 1328706807 |
%GMTIME{"$day $month, $year - $hour:$min:$sec"}% expands to 08 Feb, 2012 - 13:13:27
Note: When used in a template topic, this variable will be expanded when the template is used to create a new topic. See TWikiTemplates#TemplateTopicsVars for details.
%HOMETOPIC%
WebHome, renders as WebHome
%HTTP%
%HTTP{"Header-name"}%
%HTTP% | |
%HTTP{"Accept-language"}% | en-us,en;q=0.5 |
%HTTP{"User-Agent"}% | CCBot/1.0 (+http://www.commoncrawl.org/bot.html) |
Note: You can see the HTTP headers your browser sends to the server on a number of sites e.g. http://www.ericgiguere.com/tools/http-header-viewer.html
%HTTP% but operates on the HTTPS environment variables present when the SSL protocol is in effect. Can be used to determine whether SSL is turned on.
%HTTPS%
%HTTPS{"Header-name"}%
%HTTP_HOST%
www.fini.net
%ICON{"name"}%
%ICON{"flag-gray"}% returns 
%ICON{"pdf"}% returns 
%ICON{"smile.pdf"}% returns
%ICON{"/dont/you/dare/smile.pdf"}% returns
%ICON{"http://twiki.org/doc/xhtml.xsl"}% returns 
arrowbright, 
bubble, choice-yes, 
hand
bmp, 
doc, 
gif, 
hlp, 
html, 
mp3, pdf, 
ppt, 
txt, 
xls, 
xml, 
zip
%ICON{"name"}% generates the full HTML img tag. Specify image name or full filename (see ICON for details on filenames.)
%ICONURL{"name"}%
%ICONURL{"arrowbright"}% returns http://www.fini.net/pub/TWiki/TWikiDocGraphics/arrowbright.gif
%ICONURL{"novel.pdf"}% returns http://www.fini.net/pub/TWiki/TWikiDocGraphics/pdf.gif
%ICONURL{"/queen/boheme.mp3"}% returns http://www.fini.net/pub/TWiki/TWikiDocGraphics/mp3.gif
%ICONURLPATH{"name"}%
%ICONURLPATH{"locktopic"}% returns /pub/TWiki/TWikiDocGraphics/locktopic.gif
%ICONURLPATH{"eggysmell.xml"}% returns /pub/TWiki/TWikiDocGraphics/xml.gif
%ICONURLPATH{"/doc/xhtml.xsl"}% returns /pub/TWiki/TWikiDocGraphics/xsl.gif
%IF{"CONDITION" then="THEN" else="ELSE"}% shows "THEN" if "CONDITION" evaluates to TRUE, otherwise "ELSE" will be shown
%IF{"defined FUNFACTOR" then="FUNFACTOR is defined" else=" is not defined"}% renders as ==
%INCLUDE{"page" ...}%
| Parameter: | Description: | Default: |
|---|---|---|
"SomeTopic" | The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}% | |
"Web.Topic" | A topic in another web, i.e. %INCLUDE{"TWiki.SiteMap"}% | |
"http://..." | A full qualified URL, i.e. %INCLUDE{"http://twiki.org:80/index.html"}%. Supported content types are text/html and text/plain. if the URL resolves to an attachment file on the server this will automatically translate to a server-side include. | |
pattern="..." | A RegularExpression pattern to include a subset of a topic or page | none |
rev="2" | Include a previous topic revision; N/A for URLs | top revision |
warn="off" | Warn if topic include fails: Fail silently (if off); output default warning (if set to on); else, output specific text (use $topic for topic name) | %INCLUDEWARNING% preferences setting |
section="name" | Includes only the specified named section, as defined in the included topic by the STARTSECTION and ENDSECTION variables | |
PARONE="val 1" | Any other parameter will be defined as a variable within the scope of the included topic. The example parameters on the left will result in %PARONE% and %PARTWO% being defined within the included topic. |
%TOPIC% in case there is no include
%INCLUDINGTOPIC%
%WEB% if there is no INCLUDE.
%INCLUDINGWEB%
LANGUAGE preference is set, it's used as user's language instead of any language detected from the browser.
LANGUAGE at a non per-user way, so each user can choose his/her preferred language.
PO files) to TWiki. Those are the languages in which TWiki's user interface is available.
%LANGUAGES{...}%
| Parameter: | Description: | Default: |
|---|---|---|
format | format for each item. See below for variables available in the format string. | " * $langname" |
separator | separator between items. | "\n" (newline) |
marker="selected" | Text for $marker if the item matches selection | "selected" |
selection="%LANGUAGE%" | Current language to be selected in list | (none) |
format variables: | Variable | Meaning |
|---|---|
$langname | language's name, as informed by the translators |
$langtag | language's tag. Ex: en, pt-br, etc. |
<select>%LANGUAGES{format="<option $marker value='$langtag'>$langname</option>" selection="%LANGUAGE%"}%</select> creates an option list of the available languages with the current language selected
%LOCALSITEPREFS%
Main.TWikiPreferences, renders as TWikiPreferences
%LOGIN%
Log In
%LOGOUT%
%MAKETEXT{"string" args="..."}
| Parameter | Description | Default |
|---|---|---|
"text" or string="text" | The text to be displayed. | none |
args="param1, param2" | a comma-separated list of arguments to be interpolated in the string, replacing the [_N] placeholders in it. | none |
%MAKETEXT{string="Notes:"}% %MAKETEXT{"Contact [_1] if you have any questions." args="%WIKIWEBMASTER%"}% %MAKETEXT{"Did you want to [[[_1]][reset [_2]'s password]]?" args="%TWIKIWEB%.ResetPassword,%WIKIUSERNAME%"}% string to the current user's language only if it has such string in its translation table for that language.
&) followed by one letter (one of a...z, A...Z) (say, X) in the translatable string will be translated to <span class='twikiAccessKey'>X</span>. This is used to implement access keys. If you want to write an actual amperstand that stays just before a letter, write two consecutive amperstands (&&): they will be transformed in just one.
_) are reserved. You cannot use translatable phrases starting with an underscore.
%VARIABLES% inside the translatable strings (since they will get expanded before the %MAKETEXT{...}% itself is handled).
%MAINWEB%
Main
formfield item is the most likely to be useful to casual users.
%META{ "item" ...}%
| Item | Options | Description |
|---|---|---|
"formfield" | name="..." - name of the field. The field value can be shortened as described in FormattedSearch for $formfield | Show a single form field |
"form" | none | Generates the table showing the form fields. See Form Templates |
"attachments" | all="on" to show hidden attachments | Generates the table showing the attachments |
"moved" | none | Details of any topic moves |
"parent" | dontrecurse="on": By default recurses up tree, this has some cost. nowebhome="on": Suppress WebHome. prefix="...": Prefix that goes before parents, but only if there are parents, default "". suffix="...": Suffix, only appears if there are parents, default "". separator="...": Separator between parents, default is " > ". | Generates the parent link |
%METASEARCH{...}%
| Parameter: | Description: | Default: |
|---|---|---|
type="topicmoved" | What sort of search is required? "topicmoved" if search for a topic that may have been moved "parent" if searching for topics that have a specific parent i.e. its children "field" if searching for topics that have a particular form field value (use the name and value parameters to specify which field to search) | required |
web="%WEB%" | Wiki web to search: A web, a list of webs separated by whitespace, or all webs. | current web |
topic="%TOPIC%" | The topic the search relates to, for topicmoved and parent searches | current topic |
name | form field to search, for field type searches. May be a regular expression (see SEARCH). | |
value | form field value, for field type searches. May be a regular expression (see SEARCH). | |
title="Title" | Text that is prefixed to any search results | empty |
default="none" | Default text shown if no search hit | empty |
%METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%
%METASEARCH{type="parent" web="%WEB%" topic="%TOPIC%" title="Children: "}%
%METASEARCH{type="field" name="Country" value="China"}%
%NOP% %NOP{...}% deprecated Note: This is deprecated. Do not use it. Use %STARTSECTION{type="templateonly"}% .. %ENDSECTION{type="templateonly"}% instead (see TWikiTemplates for more details).
%NOTIFYTOPIC%
WebNotify, renders as WebNotify
%PLUGINDESCRIPTIONS%
"$SUM( $ABOVE() )" to tables located in wiki.fini topics.ExternalSite:Page text to external sites based on aliases defined in a rules topic=[[URL or TopicName][Link Text][Options]]== or :cool: for :cool:%PLUGINVERSION{"name"}% to get the version of a specific plugin
%PLUGINVERSION{"InterwikiPlugin"}% expands to $Rev: 8713$
%PLUGINVERSION% to get the version of the API
1.1
%PUBURL%
http://www.fini.net/pub
%PUBURL%/%WEB%/OtherTopic/image.gif
%PUBURLPATH%
/pub
Note: URLs built this way are typically restricted in length, typically to 2048 characters. If you need more space than this, you will need to use an HTML form and %URLPARAM{}%.
%QUERYSTRING%
%REMOTE_ADDR%
38.107.179.232
%REMOTE_PORT%
44264
%REMOTE_USER%
%REVINFO%
r2 - 26 Oct 2005 - 20:50 - TWikiContributor
%REVINFO{"format"}%
| Parameter: | Description: | Default: |
|---|---|---|
"format" | Format of revision information, see supported variables below | "r1.$rev - $date - $wikiusername" |
web="..." | Name of web | Current web |
topic="..." | Topic name | Current topic |
rev="1.5" | Specific revison number | Latest revision |
| Variable: | Unit: | Example |
|---|---|---|
$web | Name of web | Current web |
$topic | Topic name | Current topic |
$rev | Revison number. Prefix r1. to get the usual r1.5 format | 5 |
$date | Revision date | 11 Jul 2004 |
$username | Login username of revision | jsmith |
$wikiname | WikiName of revision | JohnSmith |
$wikiusername | WikiName with Main web prefix | Main.JohnSmith |
%REVINFO{"$date - $wikiusername" rev="1.1"}% returns revision info of first revision
viewauth.cgi)
%SCRIPTNAME%
view
.pl or .cgi
%SCRIPTSUFFIX%
%SCRIPTURL%
http://www.fini.net/bin
%SCRIPTURL{"script"}%
http://www.fini.net/bin/script
%SCRIPTURL{"viewauth"}%/%WEB%/%TOPIC% which expands to http://www.fini.net/bin/viewauth/TWiki/TWikiVariables
Note: In most cases you should use %SCRIPTURLPATH{"script"}% instead, as it works with URL rewriting much better
%SCRIPTURL%, but doesn't include the protocol and host part of the URL
%SCRIPTURLPATH%
/bin
%SCRIPTURL{"script"}%, but doesn't include the protocol and host part of the URL
%SCRIPTURLPATH{"script"}%
/bin/script
%SEARCH{"text" ...}%
| 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. The special word all means all webs that doe not have the NOSEARCHALL variable set to on in their WebPreferences. You can specifically exclude webs from an all search using a minus sign - for example, web="all,-Secretweb". | Current web |
topic="WebPreferences" topic="*Bug" | Limit search to topics: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. | All topics in a web |
excludetopic="Web*" excludetopic="WebHome, WebChanges" | Exclude topics from search: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. | None |
type="keyword" type="literal" type="regex" | Do a keyword search like soap "web service" -shampoo; a literal search like web service; or RegularExpression search like soap;web service;!shampoo | %SEARCHVAR- DEFAULTTYPE% preferences setting (literal) |
scope="topic" scope="text" scope="all" | Search topic name (title); the text (body) of topic; or all (both) | "text" |
order="topic" order="created" order="modified" order="editby" order= | Sort the results of search by the topic names, topic creation time, last modified time, last editor, or named field of TWikiForms. The sorting is done web by web; if you want to sort across webs, create a formatted table and sort it with TablePlugin's initsort. Note that dates are sorted most recent date last (i.e at the bottom of the table). | Sort by topic name |
limit="all" limit="16" | Limit the number of results returned. This is done after sorting if order is specified | All results |
date="..." | limits the results to those pages with latest edit time in the given TimeInterval. | 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, unless seach is inline and a format is specified (Cairo compatibility) |
nototal="on" | Do not show number of topics found | Show number |
zeroresults="off" | Suppress all output if there are no hits | zeroresults="on", displays: "Number of topics: 0" |
noempty="on" | Suppress results for webs that have no hits. | Show webs with no hits |
header="..." format="..." | Custom format results: see FormattedSearch for usage, variables & examples | Results in table |
expandvariables="on" | Expand variables before applying a FormattedSearch on a search hit. Useful to show the expanded text, e.g. to show the result of a SpreadSheetPlugin %CALC{}% instead of the formula | Raw text |
multiple="on" | Multiple hits per topic. Each hit can be formatted. The last token is used in case of a regular expression ";" and search | Only one hit per topic |
nofinalnewline="on" | If on, the search variable does not end in a line by itself. Any text continuing immediately after the search variable on the same line will be rendered as part of the table generated by the search, if appropriate. | off |
recurse="on" | Recurse into subwebs, if subwebs are enabled. | off |
separator=", " | Line separator between hits | Newline "$n" |
%SEARCH{"wiki" web="Main" scope="topic"}%
%SEARCH{"FAQ" scope="topic" nosearch="on" nototal="on" header="| *Topic: * | *Summary: * |" format="| $topic | $summary |"% (displays results in a table with header - details)
Hint: If the TWiki:Plugins.TablePlugin is installed, you may set a %TABLE{}% variable just before the %SEARCH{}% to alter the output of a search. Example: %TABLE{ tablewidth="90%" }%
%SERVERTIME%
08 Feb 2012 - 07:13
Note: When used in a template topic, this variable will be expanded when the template is used to create a new topic. See TWikiTemplates#TemplateTopicsVars for details.
%GMTIME%
%SERVERTIME{"format"}%
%SERVERTIME{"$hou:$min"}% expands to 07:13
Note: When used in a template topic, this variable will be expanded when the template is used to create a new topic. See TWikiTemplates#TemplateTopicsVars for details.
%SESSION_VARIABLE{"name"}%
%SESSION_VARIABLE{"name" set="value"}%
%SESSION_VARIABLE{"name" clear=""}%
Hint: The users ID is in the AUTHUSER session variable, and is read-only
%SESSIONID%
%SESSIONVAR%
%SPACEDTOPIC%
TWiki%20*Variables%20*Nto%20*Z
Note: This is a deprecated variable. It can be duplicated with %ENCODE{%SPACEOUT{"%TOPIC%" separator=" *"}%}%
%SPACEOUT{ "%TOPIC%" }%
TWiki Variables
| Parameter: | Description: | Default: |
|---|---|---|
separator | The separator to put between words e.g. %SPACEOUT{"DogsCatsBudgies" separator=", "}% -> Dogs, Cats, Budgies | ' ' |
Hint: Spaced out WikiWords are not automatically linked. To SPACEOUT a WikiWord but preserve the link use "double bracket" format. For example, [[WebHome][%SPACEOUT{"WebHome"}%]] expands to Web Home
%STOPINCLUDE% variable. A normal view of the topic shows everything exept the %STARTINCLUDE% variable itself.
%STARTSECTION{type="include"}% instead
%STARTINCLUDE%
%STARTSECTION{}% and %ENDSECTION{}%.
type="section" - the default, used for a generic section, such as a named section used by INCLUDE.
type="include" - like %STARTINCLUDE% ... %STOPINCLUDE% except that you can have as many include blocks as you want (%STARTINCLUDE% is restricted to only one).
type="templateonly" - start position of text to be removed when a template topic is used. This is used to embed text that you do not want expanded when a new topic based on the template topic is created. See TWikiTemplates for more information.
%STARTSECTION{"name"}% ................ %ENDSECTION{"name"}%
%STARTSECTION{type="include"}% ........ %ENDSECTION{type="include"}%
%STARTSECTION{type="templateonly"}% ... %ENDSECTION{type="templateonly"}%
| Parameter: | Description: | Default |
|---|---|---|
"name" | Name of the section. Must be unique inside a topic. | Generated name |
type="..." | Type of the section; type "section", "include" or "templateonly" | "section" |
Note: If a section is not given a name, it will be assigned one. Unnamed sections are assigned names starting with _SECTION0 for the first unnamed section in the topic, _SECTION1 for the second, etc..
Note: You can define nested sections. It is not recommended to overlap sections, although it is valid in TWiki. Use named sections to make sure that the correct START and ENDs are matched. Section markers are not displayed when a topic is viewed.
%STATISTICSTOPIC%
WebStatistics, renders as WebStatistics
%STOPINCLUDE% variable itself.
%STOPINCLUDE%
%TOC%
"---++ text") and HTML ("<h2>text</h2>") are taken into account. Any heading text after "!!" is excluded from the TOC; for example, write "---+!! text" if you do not want to list a header in the TOC
%TOC{"SomeTopic" ...}%
| Parameter: | Description: | Default: |
|---|---|---|
"TopicName" | topic name | Current topic |
web="Name" | Name of web | Current web |
depth="2" | Limit depth of headings shown in TOC | 6 |
title="Some text" | Title to appear at top of TOC | none |
%TOC{depth="2"}%
%TOC{"TWikiDocumentation" web="TWiki" title="Contents:"}%
Hint: TOC will generate links to the headings, so when a reader clicks on a heading it will jump straight where that heading is anchored in the text. If you have two headings with exactly the same text, then their anchors will also be identical and they won't be able to jump to them. To make the anchors unique, you can add an invisible HTML comment to the text of the heading. This will be hidden in normal view, but will force the anchors to be different. For example, ---+ Heading <!--5-->.
%TOPIC%
TWikiVariables, renders as TWikiVariables
$name variable gets expanded to the topic name, $qname to double quoted name, $marker to marker parameter where topic matches selection, and $web to the name of the web.
%TOPICLIST{"format" ...}%
| Parameter: | Description: | Default: |
|---|---|---|
"format" | Format of one line, may include $web (name of web), $name (name of the topic), $qname (name of topic in double quotes), $marker (which expands to marker for the item matching selection only) | "$name" |
format="format" | (Alternative to above) | "$name" |
separator=", " | line separator | "$n" (new line) |
marker="selected" | Text for $marker if the item matches selection | "selected" |
selection="TopicA, TopicB" | Current value to be selected in list | (none) |
web="Name" | Name of web | Current web |
%TOPICLIST{" * $web.$name"}% creates a bullet list of all topics
%TOPICLIST{separator=", "}% creates a comma separated list of all topics
%TOPICLIST{" <option>$name</option>"}% creates an option list (for drop down menus)
<select>%TOPICLIST{" <option $marker value='$name'>$name</option>" separator=" " selection="%TOPIC%"}%</select> creates an option list of web topics with the current topic selected
%TWIKIWEB%
TWiki
%URLPARAM{"name"}%
| Parameter: | Description: | Default: |
|---|---|---|
"name" | The name of a URL parameter | required |
default="..." | Default value in case parameter is empty or missing | empty string |
newline="<br />" | Convert newlines in textarea to other delimiters | no conversion |
encode="entity" | Encode special characters into HTML entities. See ENCODE for more details. | no encoding |
encode="url" | Encode special characters for URL parameter use, like a double quote into %22 | no encoding |
multiple="on" multiple="[[$item]]" | If set, gets all selected elements of a <select multiple="multiple"> tag. A format can be specified, with $item indicating the element, e.g. multiple="Option: $item" | first element |
separator=", " | Separator between multiple selections. Only relevant if multiple is specified | "\n" (new line) |
%URLPARAM{"skin"}% returns print for a .../view/TWiki/TWikiVariables?skin=print URL
Note: URL parameters passed into HTML form fields must be entity ENCODEd
Note: When used in a template topic, this variable will be expanded when the template is used to create a new topic. See TWikiTemplates#TemplateTopicsVars for details.
Note: There is a risk that this variable could be misused for cross-site scripting.
%USERINFO%
format parameter to get different formatted results:
%USERINFO{format="$username is really $wikiname"}%
guest is really TWikiGuest
$emails, $username, $wikiname, $wikiusername, and $groups are available for use in the format string.
jsmith, WIKINAME like JohnSmith and WIKIUSERNAME like Main.JohnSmith. Un-authenticated users are all TWikiGuest.
%USERNAME%
guest
Note: When used in a template topic, this variable will be expanded when the template is used to create a new topic. See TWikiTemplates#TemplateTopicsVars for details.
%VAR{"NAME" web="Web"}%
%WEBBGCOLOR% of the Main web write %VAR{"WEBBGCOLOR" web="Main"}%, which expands to #FFEFA6
%WEB%
TWiki
NOSEARCHALL = on preference variable. The "format" defines the format of one web item. The $name variable gets expanded to the name of the web, $qname gets expanded to double quoted name, $marker to marker where web matches selection.
%WEBLIST{"format" ...}%
| Parameter: | Description: | Default: |
|---|---|---|
"format" | Format of one line, may include $name (the name of the web), $qname (the name of the web in double quotes), $indentedname (the name of the web with parent web names replaced by indents, for use in indented lists), and $marker (which expands to marker for the item matching selection only) | "$name" |
format="format" | (Alternative to above) | "$name" |
separator=", " | line separator | "$n" (new line) |
webs="public" | comma separated list of webs, public expands to all non-hidden | "public" |
marker="selected" | Text for $marker if the item matches selection | "selected" |
selection="%WEB%" | Current value to be selected in list | section="%WEB%" |
%WEBLIST{" * [[$name.WebHome]]"}% creates a bullet list of all webs.
%WEBLIST{"<option $marker value=$qname>$name</option>" webs="Trash, public" selection="TWiki" separator=" "}% creates a dropdown of all public webs + Trash web, with the current web highlighted.
%WEBPREFSTOPIC%
WebPreferences, renders as WebPreferences
Note: use %WIKILOGOURL% defined in WebPreferences instead.
%USERNAME% if not defined in the TWikiUsers topic
%WIKINAME%
TWikiGuest
Note: When used in a template topic, this variable will be expanded when the template is used to create new topic. See TWikiTemplates#TemplateTopicsVars for details.
%WIKIPREFSTOPIC%
TWikiPreferences, renders as TWikiPreferences
%WIKITOOLNAME%
wiki.fini
%WIKIUSERNAME%
Main.TWikiGuest, renders as TWikiGuest
Note: When used in a template topic, this variable will be expanded when the template is used to create a new topic. See TWikiTemplates#TemplateTopicsVars for details
%WIKIUSERSTOPIC%
TWikiUsers, with Main prefix renders as TWikiUsers
%WIKIVERSION%
Wed, 08 Feb 2006 build 8740
%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 |" }%.
header="..." parameter
Use the header parameter to specify the header of a search result. It should correspond to the format of the format parameter. This parameter is optional. header="| *Topic:* | *Summary:* |"
2. format="..." parameter
Use the format parameter to specify the format of one search hit.
format="| $topic | $summary |"
Variables that can be used in the format string:
| Name: | Expands To: |
|---|---|
$web | Name of the web |
$topic | Topic name |
$topic(20) | Topic name, "- " hyphenated each 20 characters |
$topic(30, -<br />) | Topic name, hyphenated each 30 characters with separator "-<br />" |
$topic(40, ...) | Topic name, shortended to 40 characters with "..." indication |
$parent | Name of parent topic; empty if not set |
$parent(20) | Name of parent topic, same hyphenation/shortening like $topic() |
$text | Formatted topic text. In case of a multiple="on" search, it is the line found for each search hit. |
$locked | LOCKED flag (if any) |
$date | Time stamp of last topic update, e.g. 08 Feb 2012 - 13:13 |
$isodate | Time stamp of last topic update, e.g. 2012-02-08T13:13Z |
$rev | Number of last topic revision, e.g. 4 |
$username | Login name of last topic update, e.g. jsmith |
$wikiname | Wiki user name of last topic update, e.g. JohnSmith |
$wikiusername | Wiki user name of last topic update, like Main.JohnSmith |
$createdate | Time stamp of topic revision 1 |
$createusername | Login name of topic revision 1, e.g. jsmith |
$createwikiname | Wiki user name of topic revision 1, e.g. JohnSmith |
$createwikiusername | Wiki user name of topic revision 1, e.g. Main.JohnSmith |
$summary | Topic summary, just the plain text, all formatting and line breaks removed; up to 162 characters |
$summary(50) | Topic summary, up to 50 characters shown |
$summary(showvarnames) | Topic summary, with %ALLTWIKI{...}% variables shown as ALLTWIKI{...} |
$summary(noheader) | Topic summary, with leading ---+ headers removedNote: The tokens can be combined, for example $summary(100, showvarnames, noheader) |
$changes | Summary of changes between latest rev and previous rev |
$changes(n) | Summary of changes between latest rev and rev n |
$formname | The name of the form attached to the topic; empty if none |
$formfield(name) | The field value of a form field; for example, $formfield(TopicClassification) would get expanded to PublicFAQ. This applies only to topics that have a TWikiForm |
$formfield(name, 10) | Form field value, "- " hyphenated each 10 characters |
$formfield(name, 20, -<br />) | Form field value, hyphenated each 20 characters with separator "-<br />" |
$formfield(name, 30, ...) | Form field value, shortended to 30 characters with "..." indication |
$pattern(reg-exp) | A regular expression pattern to extract some text from a topic (does not search meta data; use $formfield instead). In case of a multiple="on" search, the pattern is applied to the line found in each search hit.• Specify a RegularExpression that covers the whole text (topic or line), which typically starts with .*, and must end in .* • Put text you want to keep in parenthesis, like $pattern(.*?(from here.*?to here).*) • Example: $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the e-mail address from a bullet of format * Email: ... • This example has non-greedy .*? patterns to scan for the first occurance of the Email bullet; use greedy .* patterns to scan for the last occurance • Limitation: Do not use .*) inside the pattern, e.g. $pattern(.*foo(.*)bar.*) does not work, but $pattern(.*foo(.*?)bar.*) does • Note: Make sure that the integrity of a web page is not compromised; for example, if you include an HTML table make sure to include everything including the table end tag |
$count(reg-exp) | Count of number of times a regular expression pattern appears in the text of a topic (does not search meta data). Follows guidelines for use and limitations outlined above under $pattern(reg-exp). Example: $count(.*?(---[+][+][+][+]) .*) counts the number of <H4> headers in a page. |
$n or $n() | New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() | Is a "no operation". This variable gets removed; useful for nested search |
$quot | Double quote ("). Alternatively write \" to escape it |
$percnt | Percent sign (%) |
$dollar | Dollar sign ($) |
%SEARCH{ "FAQ" scope="topic" nosearch="on" nototal="on" header=" * *Topic: Summary:*" format=" * [[$topic]]: $summary" }%
To get this:
TopicClassification field, an OperatingSystem field and an OsVersion field we could write:
| *Topic:* | *OperatingSystem:* | *OsVersion:* | %SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" scope="text" regex="on" nosearch="on" nototal="on" format="| [[$topic]] | $formfield(OperatingSystem) | $formfield(OsVersion) |" }%
To get this:
| Topic: | OperatingSystem: | OsVersion: |
|---|---|---|
| IncorrectDllVersionW32PTH10DLL | OsWin | 95/98 |
| WinDoze95Crash | OsWin | 95 |
%SEARCH{ "__Back to\:__ TWikiFAQ" scope="text" regex="on" nosearch="on" nototal="on" header="TWiki FAQs:" format=" * $pattern(.*?FAQ\:[\n\r]*([^\n\r]+).*) [[$topic][Answer...]]" }%
To get this:
TWiki FAQs: %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" regex="on" nosearch="on" nototal="on" order="modified" reverse="on" format="| [[$topic]] | $wikiusername | $date |" limit="7" }%
To get this:
| BlackListPlugin | JohnLundin | 31 Mar 2011 - 08:04 |
| TWikiTip024 | CynthiaManuel | 05 Mar 2009 - 07:58 |
| robots? | TWikiGuest | 11 Jan 2009 - 20:01 |
| BuyerNeeds | CynthiaManuel | 26 Jul 2008 - 14:57 |
| CommentsTemplate | CynthiaManuel | 14 Jul 2008 - 12:31 |
| TWikiRegistration | CynthiaManuel | 30 May 2008 - 08:17 |
| NewUserTemplate | CynthiaManuel | 24 Mar 2008 - 07:18 |
%CALC{$SET(weekold, $TIMEADD($TIME(), -7, day))}% %SEARCH{ "." scope="topic" regex="on" nosearch="on" nototal="on" order="modified" reverse="on" format="$percntCALC{$IF($TIME($date) < $GET(weekold), <nop>, | [[$topic]] | $wikiusername | $date | $rev |)}$percnt" limit="100" }%
weekold variable to the serialized date of exactly one week ago
$percnt makes sure that the CALC gets executed once for each search hit
weekold date
<nop> is returned, which gets removed at the end of the TWiki rendering process
%URLPARAM{"..."}% variable. Example:
Write this:
<form action="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%">
Find Topics:
<input type="text" name="q" size="32" value="%URLPARAM{"q"}%" /> <input type="submit" class="twikiSubmit" value="Search" />
</form>
Result:
%SEARCH{ search="%URLPARAM{"q"}%" format=" * $web.$topic: %BR% $summary" nosearch="on" }%
To get this:
Result:
.
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. It's not recommended to upload files greater than a few hundred K through a browser. Large files can be extremely slow-loading, and often time out. Use an FTP site for large file uploads.
NOTE: There is no access control on individual attachments. If you need control over single files, create a separate topic per file and set topic-level access restrictions for each.
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: /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 /pub/TWiki/FileAttachment/Smile.gif, an image.
I Attachment Action Size Date Who Comment Sample.txt manage 0.1 K 22 Jul 2000 - 19:37 UploadingUser Just a sample Smile.gif manage 0.1 K 22 Jul 2000 - 19:38 UploadingUser Smiley face
Manage link takes you to a new page that looks a bit like this (depending on what skin is selected):
h means the attachment is hidden, it isn't listed when viewing a topic.
Hide file checkbox, then click Change properties.
| Input type | Type field | Size field | Value field |
|---|---|---|---|
| One or more checkboxes | checkbox | number of items per line | comma list of item labels |
| One or more checkboxes, plus Set and Clear buttons | checkbox+buttons | (same) | (same) |
| One or more radio buttons (radio buttons are mutually exclusive; only one can be selected) | radio | (same) | (same) |
| Read-only label text | label | ignored | text |
| Drop-down menu or scrollable box | select | 1 for drop down, 2 and up for scrollable box | comma-separated list of options |
| A one-line text field | text | text box width in number of characters | initial text, if a new topic is created with a form template |
| A text box | textarea | columns x rows, e.g. 80x6; default size is 40x5 | initial text, if a new topic is created with a form template |
YourForm, ExpenseReportForm, InfoCategoryForm, RecordReviewForm, whatever you need.
Name, Type, Size, Values, Tooltip message, and Attributes (see sample below).
Example: WebFormYou can also retrieve possible values for select, checkbox or radio types from other topics:
| *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...
Example: WebFormField values can also be obtained as the result of a FormattedSearch. 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...
Valuesfield blank.
- Then in the TopicClassification topic, define the possible values:
Name Type Tooltip message NoDisclosure option blah blah... Public Supported option blah blah... Public FAQ option blah blah...
%SEARCH{"Office$" scope="topic" web="%MAINWEB%" nototal="on" nosummary="on" nosearch="on" regex="on" format="$web.$topic" separator=", " }%
when used in the value field of the form definition, will take the set of field values to be all topic names in the Main web which end in "Office".
Notes: label, text, and textarea fields the value may also contain commas. checkbox fields cannot be initialized through the form template.
label field has no name (blank first column in the form definition) 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.
[[...]] notation.
Tooltip message column is used as a tooltip for the field name (only if field name is a WikiName) - you only see the tooltip in edit view.
Attributes column is used to define special behavior for that form field (multiple attributes can be entered, with or without separators): H indicates that this field should not be shown in view mode. However, the field is available for editing and storing information.
M indicates that this field is mandatory. The topic cannot be saved unless a value is provided for this field. If the field is found empty during topic save, an error is raised and the user is redirected to an oops page. Mandatory fields are indicated by an asterisks next to the field name.
WEBFORMS variable in WebPreferences is optional and defines a list of possible form templates.
Example:
- Set WEBFORMS = BugForm, FeatureForm, Books.BookLoanForm
WEBFORMS enabled, an extra button is added to the edit view. If the topic doesn't have a Form, an Add Form button appears at the end of the topic. If a Form is present, a Change button appears in the top row of the Form. The buttons open a screen that enables selection of a form specified in WEBFORMS, or the No form option.
WebTopicEditTemplate topic in a web, or a new topic that serves as an application specific template topic. Initial Form values can be set there.
formtemplate parameter in the (edit or save) URL. Initial values can then be provided in the URLs or as form values: name, ex: ?BugPriority=1
namevalue=1, ex: ?ColorRed=1.
<form name="newtopic" action="%SCRIPTURLPATH{"edit"}%/%WEB%/">
<input type="hidden" name="formtemplate" value="MyForm" />
New topic name <input type="text" name="topic" size="40" />
<input type="submit" value="Create" />
</form>
Tip: For TWiki applications you can automatically generate unique topicnames.
Note: Initial values will not be submitted to the form of a new topic if you only use the formtemplate parameter.
SubmitExpenseReport topic where you can create new expense reports, a SubmitVacationRequest topic, and so on. These can specify the required template topic with its associated form. Template topics has more.
FORMFIELD, SEARCH and METASEARCH variables in TWikiVariables, and TWiki Formatted Search.
Example
TWiki users often want to have an overview of topics they contributed to. With the$formfieldparameter it is easy to display the value of a classification field next to the topic link:| *Topic* | *Classification* | %SEARCH{"%MAINWEB%.UserName" scope="text" regex="off" nosearch="on" nototal="on" order="modified" reverse="on" format="|<b>[[$web.$topic][$topic]]</b> |<nop>$formfield(TopicClassification) |" web="Sandbox"}%
checkbox
+multi anywhere in the name
text fields when a topic is saved. If you need linefeeds in a field, make sure it is a textarea.
twikicatitems.tmpl. The replacement Form Template must be set as the first item in the WebPreferences variable WEBFORMS. If missing, pages will display, but attempting to edit results in an error message.
The new Form Template system should work with old Category Table data with no special conversion. Data is assigned to Meta variables the first time an imported topic is edited and saved in the new system.
If things aren't working correctly, there may be useful entries in data/warning.txt.
%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. Text between this and the %TMPL:END% directive is not used in-place, but is saved for later use with %TMPL:P. Leading and trailing whitespace is ignored.
%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.
Use of template directives is optional: templates work without them.
NOTE: Template directives work only for templates: they do not get processed in normal topic text.
%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 directory, or can also be read from user topics. As an example, twiki/templates/view.tmpl is the default template file for the twiki/bin/view script.
Templates that are included using %TMPL:INCLUDE% are also found using the same search algorithm, unless you explicitly put '.tmpl' at the end of the template name. In this case, the string is assumed to be the full name of a template in the templates directory, and the algorithm isn't used.
TWiki uses the following search order to determine which template file or topic to use for a particular script. The skin path is set as described in TWikiSkins.
For example, theLegend:
- templates/web/script.skin.tmpl for each skin on the skin path
- templates/script.skin.tmpl for each skin on the skin path
- templates/web/script.tmpl
- templates/script.tmpl
- The TWiki topic web.topic if the template name can be parsed into web.topic
- The TWiki topic web.SkinSkinScriptTemplate for each skin on the skin path
- The TWiki topic web.ScriptTemplate
- The TWiki topic TWiki.SkinSkinScriptTemplate for each skin on the skin path
- The TWiki topic TWiki.ScriptTemplate
- script refers to the script name, e.g
view,edit- Script refers to the same, but with the first character capitalized, e.g
View- skin refers to a skin name, e.g
dragon,pattern. All skins are checked at each stage, in the order they appear in the skin path.- Skin refers to the same, but with the first character capitalized, e.g
Dragon- web refers to the current web
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 user to override the templates used: VIEW_TEMPLATE sets the template to be used for viewing a topic
EDIT_TEMPLATE sets the template for editing a topic.
view and edit respectively. The template search order is as specified above.
%TMPL:DEF and %TMPL:END%) to define common sections that appear in two or more other templates. twiki.tmpl is the default master template.
Template variable: Defines: %TMPL:DEF{"sep"}% "|" separator %TMPL:DEF{"htmldoctype"}% Start of all HTML pages %TMPL:DEF{"standardheader"}% Standard header (ex: view, index, search) %TMPL:DEF{"simpleheader"}% Simple header with reduced links (ex: edit, attach, oops) %TMPL:DEF{"standardfooter"}% Footer, excluding revision and copyright parts %TMPL:DEF{"oops"}% Skeleton of oops dialog
When you create a new topic, TWiki locates a topic to use as a content template according to the following search order:
Topic Name: What it is: WebTopicViewTemplate Error page shown when you try to view a nonexistent topic WebTopicNonWikiTemplate Alert page shown when you try to view a nonexistent topic with a non-WikiName WebTopicEditTemplate Default text shown when you create a new topic.
templatetopic CGI parameter
Variable: Description: %DATE%Signature format date. See TWikiVariables#VarDATE %GMTIME%Date/time. See TWikiVariables#VarGMTIME %GMTIME{...}%Formatted date/time. See TWikiVariables#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 like %URLPARAM%NOP%{...}%%STARTSECTION{type="templateonly"}%
...
%ENDSECTION{type="templateonly"}%Text that gets removed when a new topic based on the template is created. See notes below. %SERVERTIME%Date/time. See TWikiVariables#VarSERVERTIME %SERVERTIME{...}%Formatted date/time. See TWikiVariables#VarSERVERTIME2 %USERNAME%Login name of user who is instantiating the new topic, e.g. guest %URLPARAM{"name"}%Value of a named URL parameter %WIKINAME%WikiName of user who is instantiating the new topic, e.g. TWikiGuest %WIKIUSERNAME%User name of user who is instantiating the new tpoic, e.g. Main.TWikiGuest
%STARTSECTION{type="templateonly"}%
...
%ENDSECTION{type="templateonly"}% markers are used to embed text that you do not want expanded when a new topic based on the template topic is created. For example, you might want to write in the template topic:
This template can only be changed by: * Set ALLOWTOPICCHANGE = %MAINWEB%.TWikiAdminGroupThis will restrict who can edit the template topic, but will get removed when a new topic based on that template topic is created.
%NOP% can be used to prevent expansion of TWiki variables that would otherwise be expanded during topic creation e.g.i escape %nop>SERVERTIME% with %SER%NOP%VERTIME%.
All other variables are unchanged, e.g. are carried over "as is" into the new topic.
templatetopic specifies ExampleTopicTemplate as the template topic to use. Here is the HTML source of the form:
<form name="new" action="%SCRIPTURLPATH{edit}%/%WEB%/">
* New example topic:
<input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="26" />
<input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
<input type="hidden" name="topicparent" value="%TOPIC%" />
<input type="hidden" name="onlywikiname" value="on" />
<input type="hidden" name="onlynewtopic" value="on" />
<input type="submit" class="twikiSubmit" value="Create" />
(date format is <nop>YYYYxMMxDD)
</form>
See TWikiScripts for details of the parameters that the edit script understands.
TIP: You can use the %WIKIUSERNAME% and %DATE% variables in your topic templates to include the signature of the person creating a new topic. The variables are expanded into fixed text when a new topic is created. The standard signature is: -- %WIKIUSERNAME% - %DATE%
[[%SCRIPTURLPATH{"edit"}%/%WEB%/BugIDXXXXXXXXXX?templatetopic=BugTemplate&topicparent=%TOPIC%&t=%SERVERTIME{"$day$hour$min$sec"}%][Create new item]]=
oopsbase.tmpl and an example oops dialog oopstest.tmpl based on the base template. NOTE: This isn't the release version, just a quick, simple demo.
%TMPL:P{"sep"}%
%TMPL:DEF{"sep"}% | %TMPL:END% <html> <head> <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title> <base href="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%"> <meta name="robots" content="noindex"> </head> <body bgcolor="#FFFFFF"> <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr> <td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%"> <a href="%WIKIHOMEURL%"> <img src="%PUBURLPATH%/wikiHome.gif" border="0"></a> </td> <td> <b>%WIKITOOLNAME% . %WEB% . </b><font size="+2"> <B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font> </td> </tr> <tr bgcolor="%WEBBGCOLOR%"> <td colspan="2"> %TMPL:P{"webaction"}% </td> </tr> </table> --- ++ %TMPL:P{"heading"}% %TMPL:P{"message"}% <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr bgcolor="%WEBBGCOLOR%"> <td valign="top"> Topic <b>%TOPIC%</b> . { %TMPL:P{"topicaction"}% } </td> </tr> </table> </body>
%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END% %TMPL:DEF{"webaction"}% test =webaction= %TMPL:END% %TMPL:DEF{"heading"}% Test heading %TMPL:END% %TMPL:DEF{"message"}% Test =message=. Blah blah blah blah blah blah blah blah blah blah blah... * Some more blah blah blah blah blah blah blah blah blah blah... * Param1: %PARAM1% * Param2: %PARAM2% * Param3: %PARAM3% * Param4: %PARAM4% %TMPL:END% %TMPL:DEF{"topicaction"}% Test =topicaction=: [[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}% [[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END% %TMPL:INCLUDE{"oopsbase"}%
.../bin/oops/Sandbox/TestTopic2?template=oopstest¶m1=WebHome¶m2=WebNotify
Related Topics: TWikiSkins, DeveloperDocumentationCategory, AdminDocumentationCategory
Tip: TWiki:TWiki.TWikiSkinsSupplement on TWiki.org has supplemental documentation on TWiki Skins.
twiki/templates directory and are named according to the skin: <scriptname>.<skin>.tmpl. For example, the template used for pages generated by the view script with the print skin selected is view.print.tmpl (this is how the Printable control is implemented). Skin files may also be defined in TWiki topics - see TWikiTemplates for details.
To start creating a new skin, copy the default TWikiTemplates (like view.tmpl), or copy an existing skin to use as a base for your own skin. You should only need to copy the files you intend to customise, as TWiki can be configured to fall back to another skin if a template is not defined in your skin. Name the files as described above (for example view.myskin.tmpl.
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
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
twiki.tmpl is a master template conventionally used by other templates, but not used directly by code.
Note: You are strongly recommended not to TMPL:INCLUDE the default templates, or templates from other skins, when you are defining your own skin. If you do, you run the risk that the included file might change and break your skin.
| Variable: | Expanded to: |
|---|---|
%WEBLOGONAME% | Filename of web logo |
%WEBLOGOIMG% | Image URL of web logo |
%WEBLOGOURL% | Link of web logo |
%WEBLOGOALT% | Alt text of web logo |
%WIKILOGOURL% | Link of page logo |
%WIKILOGOIMG% | Image URL of page logo |
%WIKILOGOALT% | Alt text of page logo |
%WEBBGCOLOR% | Web-specific background color, defined in the WebPreferences |
%WIKITOOLNAME% | The name of your TWiki site |
%SCRIPTURL% | The script URL of TWiki |
%SCRIPTURLPATH% | The script URL path |
%SCRIPTSUFFIX% | The script suffix, ex: .pl, .cgi |
%WEB% | The name of the current web. |
%TOPIC% | The name of the current topic. |
%WEBTOPICLIST% | Common links of current web, defined in the WebPreferences. It includes a Go box |
%TEXT% | The topic text, e.g. the content that can be edited |
%META{"form"}% | TWikiForm, if any |
%META{"attachments"}% | FileAttachment table |
%META{"parent"}% | The topic parent |
%EDITTOPIC% | Edit link |
%REVTITLE% | The revision title, if any, ex: (r1.6) |
%REVINFO% | Revision info, ex: r1.6 - 24 Dec 2002 - 08:12 GMT - TWikiGuest |
%WEBCOPYRIGHT% | Copyright notice, defined in the WebPreferences |
%BROADCASTMESSAGE% | Broadcast message at the beginning of your view template, can be used to alert users of scheduled downtimes; can be set in TWikiPreferences |
%WEBTOPICLIST% includes a "Go" box, also called "Jump" box, to jump to a topic. The box also understands URLs, e.g. you can type http://www.google.com/ to jump to an external web site. The feature is handy if you build a skin that has a select box of frequently used links, like Intranet home, employee database, sales database and such. A little JavaScript gets into action on the onSelect method of the select tag to fill the selected URL into the "Go" box field, then submits the form.
Here is an example form that has a select box and the "Go" box for illustration purposes. You need to have JavaScript enabled for this to work:
css.pattern.tmpl.
Write in your main template:
<style type='text/css' media='all'>@import url('%PUBURLPATH%/%TWIKIWEB%/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% | 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 |
%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. Example activation of PrintSkin that generates a printable page:
Setting SKIN (or the ?skin parameter in the URL) replaces the existing skin path setting. 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 full skin path is built up as follows: SKIN setting (or ?skin if it is set), then COVER setting is added, then ?cover.
text skin is reserved for TWiki internal use.
Skin names starting with rss also have a special meaning; if one or more of the skins in the skin path starts with 'rss' then 8-bit characters will be encoded as XML entities in the output, and the content-type header will be forced to text/xml.
Related Topics: TWikiSkinBrowser, AdminDocumentationCategory, DeveloperDocumentationCategory, TWiki:TWiki.TWikiSkinsSupplement
-- Contributors: TWiki:Main.PeterThoeny, TWiki:Main.MikeMannix, TWiki:Main.CrawfordCurrie
META variable name/value pairs
META variables to store topic data that's separate from the main free-form content. This includes program-generated info like FileAttachment and topic movement data, and user-defined TWikiForms info. Use META variables to format and display Meta Data.
%META:<type>{key1="value1" key2="value2" ...}%
name, this appears first for easier searching (note the order of the variables themselves is defined).
\n (new line) is represented in values by %_N_ and " (double-quotes) by %_Q_%.
Example of Format
%META:TOPICINFO{version="1.6" date="976762663" author="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, WebHome if done from Go, othewise topic where ? or form used. Normally just topic, but is full web.topic format if parent is in a different Web. Renaming a Web will then only break a few of these references or they can be scanned and fixed. |
| 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 " > ". |
Meta.pm code that supports the format needs only minor alteration.
Related Topics: DeveloperDocumentationCategory, UserDocumentationCategory
Tip: TWiki:TWiki.TWikiPluginsSupplement on TWiki.org has supplemental documentation on TWiki Plugins.
%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 http://www.fini.net/v/TWiki/AbcPlugin
If you need to install an "expensive" Plugin, and you need its functionality only in one web, you can place the Plugin topic into that web. TWiki will initialize the Plugin only if the Plugin topic is found (which won't be the case for other webs.)
{PluginsOrder} in the Plugins section of configure.
Set SHORTDESCRIPTION = Create dynamic foo bar reports
data/debug.txt. Set to 0=off or 1=on: Set DEBUG = 0
%<pluginname>_<var>%. For example, %DEFAULTPLUGIN_SHORTDESCRIPTION% shows the description of the DefaultPlugin.
%ACTIVATEDPLUGINS% %PLUGINDESCRIPTIONS% "$SUM( $ABOVE() )" to tables located in wiki.fini topics.ExternalSite:Page text to external sites based on aliases defined in a rules topic=[[URL or TopicName][Link Text][Options]]== or :cool: for :cool:%FAILEDPLUGINS% | Plugin | Errors |
|---|---|
| SpreadSheetPlugin | none |
| ActionTrackerPlugin | none |
| BatchUploadPlugin | none |
| BlackListPlugin | none |
| CalendarPlugin | none |
| CommentPlugin | none |
| EditTablePlugin | none |
| FilterPlugin | none |
| GluePlugin | none |
| IfDefinedPlugin | none |
| ImageGalleryPlugin | none |
| ImagePlugin | none |
| InterwikiPlugin | none |
| LinkOptionsPlugin | none |
| NatSkinPlugin | none |
| PreferencesPlugin | none |
| RedDotPlugin | none |
| RenderListPlugin | none |
| SlideShowPlugin | none |
| SmiliesPlugin | none |
| TablePlugin | none |
| ToolTipPlugin | none |
| TreePlugin | none |
| WysiwygPlugin | none |
| Handler | Plugins |
|---|---|
| afterEditHandler | ActionTrackerPlugin |
| beforeAttachmentSaveHandler | BatchUploadPlugin BlackListPlugin |
| beforeCommonTagsHandler | PreferencesPlugin WysiwygPlugin |
| beforeEditHandler | ActionTrackerPlugin WysiwygPlugin |
| beforeSaveHandler | ActionTrackerPlugin BlackListPlugin CommentPlugin WysiwygPlugin |
| commonTagsHandler | SpreadSheetPlugin ActionTrackerPlugin BlackListPlugin CalendarPlugin CommentPlugin EditTablePlugin FilterPlugin GluePlugin IfDefinedPlugin ImageGalleryPlugin ImagePlugin LinkOptionsPlugin NatSkinPlugin RedDotPlugin SlideShowPlugin SmiliesPlugin TreePlugin |
| initPlugin | SpreadSheetPlugin ActionTrackerPlugin BatchUploadPlugin BlackListPlugin CalendarPlugin CommentPlugin EditTablePlugin FilterPlugin GluePlugin IfDefinedPlugin ImageGalleryPlugin ImagePlugin InterwikiPlugin LinkOptionsPlugin NatSkinPlugin PreferencesPlugin RedDotPlugin RenderListPlugin SlideShowPlugin SmiliesPlugin TablePlugin ToolTipPlugin TreePlugin WysiwygPlugin |
| modifyHeaderHandler | WysiwygPlugin |
| postRenderingHandler | BlackListPlugin EditTablePlugin NatSkinPlugin PreferencesPlugin RedDotPlugin ToolTipPlugin WysiwygPlugin |
| preRenderingHandler | InterwikiPlugin RenderListPlugin SmiliesPlugin TablePlugin |
| redirectCgiQueryHandler | RedDotPlugin |
lib/TWiki/Func.pm) describes all the interfaces available to Plugins. Plugins should only use the interfaces described in this module.
Note: If you use other core functions not described in Func.pm, you run the risk of creating security holes. Also, your Plugin will likely break and require updating when you upgrade to a new version of TWiki.
lib/TWiki/Plugins/EmptyPlugin.pm module.
DISABLE_ from the function name.
eval block like this:eval { require IPC::Run } return "<font color=\"red\">SamplePlugin: Can't load required modules ($@)</font>" if $@;
$VERSION='0.000' variable, beginning at 1.000.
initPlugin handler should check all dependencies and return TRUE if the initialization is OK or FALSE if something went wrong. initPlugin handler).
$TWiki::Plugins::VERSION in the TWiki::Plugins module contains the TWiki Plugin API version, currently 1.1. %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 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.
lib/TWiki/Plugins/EmptyPlugin.pm to <name>Plugin.pm. The EmptyPlugin.pm module contains mostly empty functions, so it does nothing, but it's ready to be used. Customize it. Refer to the Plugin API specs for more information.
If your Plugin uses its own modules and objects, you must include the name of the Plugin in the package name. For example, write Package MyFirstPlugin::Attrs; instead of just Package Attrs;. Then call it using:
use TWiki::Plugins::MyFirstPlugin::Attrs; $var = MyFirstPlugin::Attrs->new();
MyFirstPlugin, press enter and create the new topic
OUTLINE: Doc Topic Contents
Check the Plugins web on TWiki.org for the latest Plugin doc topic template. Here's a quick overview of what's covered: Syntax Rules: <Describe any special text formatting that will be rendered.>" Example: <Include an example of the Plugin in action. Possibly include a static HTML version of the example to compare if the installation was a success!>" Plugin Settings: <Description and settings for custom Plugin %VARIABLES%, and those required by TWiki.>"Plugin Installation Instructions: <Step-by-step set-up guide, user help, whatever it takes to install and run, goes here.>" Plugin Info: <Version, credits, history, requirements - entered in a form, displayed as a table. Both are automatically generated when you create or edit a page in the TWiki:Plugins web.>"
- Plugins Preferences <If user settings are needed, explain... Entering values works exactly like TWikiPreferences and WebPreferences: six (6) spaces and then:>"
- Set <EXAMPLE = value added>
Plugin, ex: MyFirstPlugin.pm, and a documentation page with the same name(MyFirstPlugin.txt).
lib/TWiki/Plugins/MyFirstPlugin.pm
data/TWiki/MyFirstPlugin.txt
pub/TWiki/MyFirstPlugin/uparrow.gif [a required graphic]
MyFirstPlugin.zip) and add the entire directory structure from Step 1. The archive should look like this: lib/TWiki/Plugins/MyFirstPlugin.pm
data/TWiki/MyFirstPlugin.txt
pub/TWiki/MyFirstPlugin/uparrow.gif
MyFirstPlugin
MyFirstPlugin.zip
Dev, ex: MyFirstPluginDev. This is the discussion page for future development. (User support for Plugins is handled in TWiki:Support.)
Once you have done the above steps once, you can use the BuildContrib to upload updates to your Plugin.
Thank you very much for sharing your Plugin with the TWiki community
TWiki::Func::getWorkArea() function, which gives you a persistant 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: _FooBarPlugin_img123.gif
TWiki::Func::saveAttachment() function to store the data.
Recommendation for file names in Plugin attachment area: _Main_roundedge-ul.gif
Dev, such as MyFirstPluginDev. The Plugin development topic is a great resource to discuss feature enhancements and to get feedback from the TWiki community.
Tip: Plugins can be written to be compatible with older and newer TWiki releases. This can be done also for Plugins using unofficial TWiki internal functions of an earlier release that no longer work on the latest TWiki codebase. TWiki:TWiki.TWikiPluginsSupplement#MaintainPlugins has more.
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.
%PLUGINVERSION% variable. The 'Since' field in the function
documentation refers to the VERSION number and the date that the function
was addded.
Note: Beware! These methods should only ever be called
from the context of a TWiki Plugin. They require a Plugins SESSION context to be
established before they are called, and will not work if simply called from
another TWiki module. For example,
use TWiki; print TWiki::Func::getSkin(),"\n";will fail with
Can't call method "getSkin" on an undefined value at TWiki/Func.pm line 83.
If you want to call the methods outside the context of a plugin, you can create a Plugins SESSION object. For example,
the script:
use TWiki: $TWiki::Plugins::SESSION = new TWiki(); print TWiki::Func::getSkin(),"\n";will work happily.
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'
$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)
$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"
This might be used like this:
my $url = TWiki::Func::getOopsUrl($web, $topic, 'oopsmistake', 'I made a boo-boo'); TWiki::Func::redirectCgiQuery( undef, $url ); return 0;Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002) Since TWiki::Plugins::VERSION 1.1, the recommended approach is to throw an oops exception.
use Error qw( :try ); throw TWiki::OopsException($web, $topic, undef, 0, [ 'I made a boo-boo' ]);and let TWiki handle the cleanup.
$path URL path of pub directory, e.g. "/pub"
Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
$query CGI query object; or 0 if script is called as a shell script
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$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
$key - Session key
sub initPlugin {
TWiki::Func::getContext()->{'MyID'} = 1;
...
This can be used in SecondPlugin.pm like this:
sub initPlugin {
if( TWiki::Func::getContext()->{'MyID'} ) {
...
}
...
or in a template, like this:
%TMPL:DEF{"ON"}% Not off %TMPL:END%
%TMPL:DEF{"OFF"}% Not on %TMPL:END%
%TMPL:P{context="MyID" then="ON" else="OFF"}%
or in a topic:
%IF{"context MyID" then="MyID is ON" else="MyID is OFF"}%
Note: all plugins have an automatically generated context identifier
if they are installed and initialised. For example, if the FirstPlugin is
working, the context ID 'FirstPlugin' will be set.
Since: TWiki::Plugins::VERSION 1.1
$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' );
$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)
$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" );
$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)
$name Name of tool, e.g. 'TWiki'
Synonymous with TWiki::Func::getPreferencesValue('WIKITOOLNAME');
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
$name Name, e.g. 'Main'
Synonymous with TWiki::Func::getPreferencesValue('MAINWEB');
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
$name Name, e.g. 'TWiki'
Synonymous with TWiki::Func::getPreferencesValue('TWIKIWEB');
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)
$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)
$wikiName - Wiki name, e.g. 'Main.JohnDoe' or 'JohnDoe'
$loginName Login name of user, e.g. 'jdoe'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$loginName - Login name, e.g. 'jdoe'
$dontAddWeb - Do not add web prefix if "1"
$wikiName Wiki name of user, e.g. 'Main.JohnDoe' or 'JohnDoe'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web - Web name, required, e.g. 'Sandbox'
$type - Access type, e.g. 'VIEW', 'CHANGE', 'CREATE'
$wikiName - WikiName of remote user, i.e. "Main.PeterThoeny"
$text - Topic text, optional. If empty, topic $web.$topic is consulted
$topic - Topic name, required, e.g. 'PrivateStuff'
$web - Web name, required, e.g. 'Sandbox'
$filter - spec of web types to recover
$filter may also contain the word 'public' which will further filter
out webs that have NOSEARCHALL set on them.
'allowed' filters out webs the current user can't read.
For example, the deprecated getPublicWebList function can be duplicated
as follows:
my @webs = TWiki::Func::getListOfWebs( "user,public" );Since: TWiki::Plugins::VERSION 1.1
$web - Web name, required, e.g. 'Sandbox'
$newWeb is the name of the new web.
$baseWeb is the name of an existing web (a template web). If the base web is a system web, all topics in it will be copied into the new web. If it is a normal web, only topics starting with 'Web' will be copied. If no base web is specified, an empty web (with no topics) will be created. If it is specified but does not exist, an error will be thrown.
$opts is a ref to a hash that contains settings to be modified in
use Error qw( :try );
use TWiki::AccessControlException;
try {
TWiki::Func::createWeb( "Newweb" );
} catch Error::Simple with {
my $e = shift;
# see documentation on Error::Simple
} catch TWiki::AccessControlException with {
my $e = shift;
# see documentation on TWiki::AccessControlException
} otherwise {
...
};
Since: TWiki::Plugins::VERSION 1.1
use Error qw( :try );
use TWiki::AccessControlException;
try {
TWiki::Func::moveWeb( "Oldweb", "Newweb" );
} catch Error::Simple with {
my $e = shift;
# see documentation on Error::Simple
} catch TWiki::AccessControlException with {
my $e = shift;
# see documentation on TWiki::AccessControlException
} otherwise {
...
};
To delete a web, move it to a subweb of Trash
TWiki::Func::moveWeb( "Deadweb", "Trash.Deadweb" );Since: TWiki::Plugins::VERSION 1.1
$web - Web name, required, e.g. 'Sandbox'
@topics Topi