TWiki Webmaster Reference (ver. 01 Sep 2001)

This page contains all documentation topics as one long and complete reference sheet. Use the extended menu below to jump directly to sections. Doubleclick anywhere on-screen to return to the top of the page.

(You can also browse the TWiki reference as individual pages from the full topics menu.)

Note: Read the most up to date version of this document at http://TWiki.org/cgi-bin/view/TWiki/TWikiDocumentation

Related Topics: TWikiSite, TWikiHistory, TWikiPlannedFeatures, TWikiEnhancementRequests

Warning: Can't find topic TWikiImplementationNotes

Warning: Can't find topic TWikiInstallationNotes

Warning: Can't find topic TWikiUpgradeNotes

Warning: Can't find topic TWikiAuthentication

TWiki Access Control

Restricting read and write access to topics and webs, by Users and groups

TWikiAccessControl allows you restrict access to single topics and entire webs, by individual user and by user Groups. Access control, combined with TWikiUserAuthentication, lets you easily create and manage an extremely flexible, fine-grained privilege system.

Permissions settings of the webs on this TWiki site

Web Sitemap VIEW CHANGE RENAME
Listed DENY ALLOW DENY ALLOW DENY ALLOW
Main ...              
TWiki ...         TWikiAdminGroup   TWikiAdminGroup

See TWikiAccessControl for details

Please Note:

  • A blank in the the above table may mean either the corresponding control is absent or commented out or that it has been set to a null value. The two conditions have dramatically different and possibly opposed semantics.
  • TWikiGuest is the guest account - used by unauthenticated users.
  • The TWiki web must not be denied view to TWikiGuest - otherwise people will not be able to register.

Related Topics: SiteMap, UserDocumentationCategory, AdminDocumentationCategory, AdminToolsCategory

This table comes from SitePermissions

An Important Control Consideration

Open, freeform editing is the essence of WikiCulture - what makes TWiki different and often more effective than other collaboration tools. For that reason, it is strongly recommended that decisions to restrict read or write access to a web or a topic are made with great care - the more restrictions, the less Wiki in the mix. Experience shows that unrestricted write access works very well because:

  • Peer influence is enough to ensure that only relevant content is posted.
  • Peer editing - the ability for anyone to rearrange all content on a page - keeps topics focussed.
  • In TWiki, content is transparently preserved under revision control:
    • Edits can be undone by the TWikiAdminGroup (the default administrators group; see #ManagingGroups).
    • Users are encouraged to edit and refactor (condense a long topic), since there's a safety net.
As a collaboration guideline:
  • Create broad-based Groups (for more and varied input), and...
  • Avoid creating view-only Users (if you can read it, you should be able to contribute to it).

Authentication vs. Access Control

Authentication: Identifies who a user is based on a login procedure. See TWikiUserAuthentication.

Access control: Restrict access to content based on users and groups once a user is identified.

Users and Groups

Access control is based on the familiar concept of Users and Groups. Users are defined by their WikiNames. They can then be organized in unlimited combinations by inclusion in one or more user Groups. For convenience, Groups can also be included in other Groups.

Managing Users

A user can create an account in TWikiRegistration. The following actions are performed:

  • WikiName and encrypted password are recorded using the password manager if authentication is enabled.
  • A confirmation e-mail is sent to the user.
  • A user home page with the WikiName of the user is created in the Main web.
  • The user is added to the TWikiUsers topic.

The default visitor name is TWikiGuest. This is the non-authenticated user.

Managing Groups

Groups are defined by group topics created in the Main web, like the TWikiAdminGroup. To create a new group:

  1. Edit TWikiGroups by entering a new topic with a name that ends in Group. Example:
    • SomeGroup
  2. Define two TWikiVariables in the new group topic:
    • Set GROUP = < list of Users and/or Groups >
    • Set ALLOWTOPICCHANGE = < list of Users and/or Groups >
    • The GROUP variable is a comma-separated list of Users and/or other Groups. Example:
      • Set GROUP = Main.SomeUser, Main.OtherUser, Main.SomeGroup
    • ALLOWTOPICCHANGE defines who is allowed to change the group topic; it is a comma delimited list of Users and Groups. You typically want to restrict that to the members of the group itself, so it should contain the name of the topic. This prevents Users not in the Group from editing the topic to give themselves or others access. For example, for the TWikiAdminGroup topic write:
    • Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup
  3. These are summarised on SitePermissions

ALERT! 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.

The SuperAdminGroup

By mistyping a user or group name in the settings, it's possible to lock a topic so that no-one can edit it from a browser. To avoid this, you can create superusers:

  • Edit the SuperAdminGroup as described above and add the wikinames of a group of Users who are always allowed to edit/view topics e.g.
    • Set GROUP= ElizabethWindsor?,Main.TonyBlair

Restricting Access

You can define who is allowed to read or write to a web or a topic. Note that some plugins may not respect access permissions.

  • Restricting VIEW blocks viewing and searching of content.
  • Restricting CHANGE blocks creating new topics, changing topics or attaching files.
  • Restricting RENAME controls who is allowed to rename, move or delete a topic.
    • To rename, move or delete a topic, the user also also needs VIEW and CHANGE permission. They also need CHANGE access to change references in any referring topics (though the rename can proceed without this access), and CHANGE access to the target topic.
  • Restricting MANAGE controls access to certain management functions, such as 'create web'. It must be set in the TWiki web.

Controlling access to a Web

You can define restrictions of who is allowed to view a FS web. You can restrict access to certain webs to selected Users and Groups, by:

  • authenticating all webs and restricting selected webs: Topic access in all webs is authenticated, and selected webs have restricted access.
  • authenticating and restricting selected webs only: Provide unrestricted viewing access to open webs, with authentication and restriction only on selected webs.

  • You can define these settings in the WebPreferences topic, preferable towards the end of the topic:
    • 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 >

Be careful with empty values for any of these. In older versions of TWiki,

  • Set ALLOWWEBVIEW =
meant the same as not setting it at all. However since TWiki Dakar release, it means allow no-one access i.e. prevent anyone from viewing the web. Similarly
  • Set DENYWEBVIEW =
now means do not deny anyone the right to view this web. See "How TWiki evaluates ALLOW/DENY settings" below for more on this.

Controlling access to a Topic

  • You can define these settings in the WebPreferences topic, preferable towards the end of the topic:
    • 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 >

Remember when opening up access to specific topics within a restricted web that other topics in the web - for example, the WebLeftBar - may also be accessed when viewing the topics. The message you get when you are denied access should tell you what topic you were not permitted to access.

Be careful with empty values for any of these. In older versions of TWiki,

  • Set ALLOWTOPICVIEW =
meant the same as not setting it at all. However since TWiki Dakar release, it means allow no-one access i.e. prevent anyone from viewing the topic. Similarly
  • Set DENYTOPICVIEW =
now means do not deny anyone the right to view this topic. See "How TWiki evaluates ALLOW/DENY settings" below for more on this.

Controlling access to Attachments

Attachments are referred to directly, and are not normally indirected via TWiki scripts. This means that the above instructions for access control will not apply to attachments. It is possible that someone may inadvertently publicise a URL that they expected to be access-controlled.

The easiest way to apply the same access control rules for attachments as apply to topics is to use the Apache 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.

How TWiki evaluates ALLOW/DENY settings

When deciding whether to grant access, TWiki evaluates the following rules in order (read from the top of the list; if the logic arrives at PERMITTED or DENIED that applies immediately and no more rules are applied). You need to read the rules bearing in mind that VIEW, CHANGE and RENAME access may be granted/denied separately.

  1. If the user is a super-user
    • access is PERMITTED.
  2. If DENYTOPIC is set to a list of wikinames
    • people in the list will be DENIED.
  3. If DENYTOPIC is set to empty ( i.e. Set DENYTOPIC = )
    • access is PERMITTED i.e no-one is denied access to this topic
  4. If ALLOWTOPIC is set
    1. people in the list are PERMITTED
    2. everyone else is DENIED
      • Note that this means that setting ALLOWTOPIC to empty denies access to everyone except admins (unless DENYTOPIC is also set to empty, as described above)
  5. If DENYWEB is set to a list of wikiname
    • people in the list are DENIED access
  6. If ALLOWWEB is set to a list of wikinames
    • people in the list will be PERMITTED
    • everyone else will be DENIED
      • Note that setting ALLOWWEB to empty denies access to everyone except admins
  7. If you got this far, access is PERMITTED

Access Control quick recipes

Obfusticating Webs

Another way of hiding webs is to keep them hidden by not publishing the URL and by preventing the all webs search option from accessing obfuscated webs. Do so by enabling the NOSEARCHALL variable in WebPreferences:

  • Set NOSEARCHALL = on

This setup can be useful to hide a new web until content its ready for deployment, or to hide view access restricted webs.

ALERT! Note: Obfuscating a web without view access control is very insecure, as anyone who knows the URL can access the web.

Authenticate all Webs and Restrict Selected Webs

Use the following setup to authenticate users for topic viewing in all webs and to restrict access to selected webs. Requires TWikiUserAuthentication to be enabled.

  1. Restrict view access to selected Users and Groups. Set one or both of these variables in its WebPreferences topic:
    • Set DENYWEBVIEW = < list of Users and Groups >
    • Set ALLOWWEBVIEW = < list of Users and Groups >
    • Note: DENYWEBVIEW is evaluated before ALLOWWEBVIEW. Access is denied if the authenticated person is in the DENYWEBVIEW list, or not in the ALLOWWEBVIEW list. Access is granted in case DENYWEBVIEW and ALLOWWEBVIEW is not defined.
  2. Hide the web from an "all webs" search. Enable this restriction with the NOSEARCHALL variable in its WebPreferences topic:
    • Set NOSEARCHALL = on

Authenticate and Restrict Selected Webs Only

Use the following setup to provide unrestricted viewing access to open webs, with authentication only on selected webs. Requires TWikiUserAuthentication to be enabled.

  1. Restrict view access to selected Users and Groups. Set one or both of these variables in its WebPreferences topic:
    • Set DENYWEBVIEW = < list of Users and Groups >
    • Set ALLOWWEBVIEW = < list of Users and Groups >
    • Note: DENYWEBVIEW is evaluated before ALLOWWEBVIEW. Access is denied if the authenticated person is in the DENYWEBVIEW list, or not in the ALLOWWEBVIEW list. Access is granted in case DENYWEBVIEW and ALLOWWEBVIEW is not defined.
  2. Hide the web from an "all webs" search. Enable this restriction with the NOSEARCHALL variable in its WebPreferences topic:
    • Set NOSEARCHALL = on

Hide Control Settings

TIP Tip: To hide access control settings from normal browser viewing, place them in HTML comment markers.

<!--
   * Set DENYTOPICCHANGE = Main.SomeGroup
-->

TWiki Templates

Definition of the templates used to render all HTML pages displayed in TWiki

Overview

There are three types of template:

  • Master Templates: Define blocks of text for use in other templates
  • HTML Page Templates: Define the layout of FS pages
  • Template Topics: Define default text when you create a new topic

All three types of template use the TWiki template system.

The TWiki Template System

Templates are plain text with embedded template directives that tell TWiki how to compose blocks of text together to create something new.

How Template Directives Work

  • Template directives are embedded in templates.
  • Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
  • Directives:
    • %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.
  • Two-pass processing lets you use a variable before or after declaring it.
  • Templates and TWikiSkins work transparently and interchangeably. For example, you can create a skin that overloads only the twiki.tmpl master template, like twiki.print.tmpl, that redefines the header and footer.
  • HELP Use of template directives is optional: templates work without them.
  • ALERT! NOTE: Template directives work only for templates: they do not get processed in normal topic text.

TMPL:P also supports simple parameters. For example, given the definition %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.

Finding Templates

Templates are stored either in the 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.

  1. templates/web/script.skin.tmpl for each skin on the skin path
    • ALERT! this usage is supported for compatibility only and is deprecated. Store web-specific templates in TWiki topics instead.
  2. templates/script.skin.tmpl for each skin on the skin path
  3. templates/web/script.tmpl
    • ALERT! this usage is supported for compatibility only and is deprecated. Store web-specific templates in TWiki topics instead.
  4. templates/script.tmpl
  5. The TWiki topic web.topic if the template name can be parsed into web.topic
  6. The TWiki topic web.SkinSkinScriptTemplate for each skin on the skin path
  7. The TWiki topic web.ScriptTemplate
  8. The TWiki topic TWiki.SkinSkinScriptTemplate for each skin on the skin path
  9. The TWiki topic TWiki.ScriptTemplate
Legend:
  • 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
For example, the example template file will be searched for in the following places, when the current web is Thisweb and the skin path is print,pattern:
  1. templates/Thisweb/example.print.tmpl deprecated; don't rely on it
  2. templates/Thisweb/example.pattern.tmpl deprecated; don't rely on it
  3. templates/example.print.tmpl
  4. templates/example.pattern.tmpl
  5. templates/Thisweb/example.tmpl deprecated; don't rely on it
  6. templates/example.tmpl
  7. Thisweb.PrintSkinExampleTemplate
  8. Thisweb.PatternSkinExampleTemplate
  9. Thisweb.ExampleTemplate
  10. TWiki.PrintSkinExampleTemplate
  11. TWiki.PatternSkinExampleTemplate
  12. TWiki.ExampleTemplate

Template names are usually derived from the name of the currently executing script; however it is also possible to override these settings in the 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.
If these preferences are set locally (using Local instead of Set) for a topic, or as WebPreferences or TWikiPreferences (using Set), the indicated templates will be chosen for view and edit respectively. The template search order is as specified above.

Master Templates

Master templates use the block definition directives (%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

HTML Page Templates

HTML page templates are files of HTML mixed with template directives that tell TWiki how to build up an HTML page. As described above, the template system supports the use of 'include' directives that let you re-use the same sections of HTML - such as headers and footers - in several different places.

TWiki uses HTML page templates when composing the output from all actions, like topic view, edit, and preview. This allows you to change the look and feel of all pages by editing just a few template files.

HTML page templates are also used in the definition of TWikiSkins.

Template Topics

Template topics define the default text for new topics. There are three types of template topic:

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.
When you create a new topic, TWiki locates a topic to use as a content template according to the following search order:

  1. A topic name specified by the templatetopic CGI parameter
    • if no web is specified, the current web is searched first and then the TWiki web
  2. WebTopicEditTemplate in the current web
  3. WebTopicEditTemplate in the TWiki web

Edit Template Topics and Variable Expansion

The following variables get expanded when a user creates a new topic based on a template topic:

Variable: Description:
%DATE% 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%{...}%
%NOP{ ... }% 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

The NOP tag is used to embed text that you do not want expanded when a new topic based on the template is created. For example, you might want to write in the template: 


This template can only be changed by:
   * Set ALLOWTOPICCHANGE = WikiMastersGroup
This will restrict who can edit the template, but will get removed when a topic based on the template is created.

%NOP% (or %NOP{}% can be used to prevent expansion of TWiki variables that would otherwise be expanded during topic creation e.g. %SERVERTIME%.

Notes:

  • %NOP{ ... }% can span multiple lines.
  • The scan for the closing }% pattern is "non-greedy", that is, it stops at the first occurence. That means you have to protect variables with parameters located inside %NOP{ ... }%. To do this, insert a %NOP% between } and %. Example: %NOP{ %GMTIME{"$year"}%NOP%% }%.

All other variables are unchanged, e.g. are carried over "as is" into the new topic.

Template Topics in Action

Here is an example for creating new topics based on a specific template topic:

  • New example topic:   (date format is YYYYxMMxDD)

The above form asks for a topic name. A hidden input tag named templatetopic specifies ExampleTopicTemplate as the template topic to use. Here is the HTML source of the form: 

<form name="new" action="%SCRIPTURL{"edit"}%/%INTURLENCODE{"%WEB%"}%/">
   * New example topic: 
     <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
     <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
     <input type="hidden" name="topicparent" value="%TOPIC%" />
     <input type="hidden" name="onlywikiname" value="on" />
     <input type="hidden" name="onlynewtopic" value="on" />
     <input type="submit" class="twikiSubmit" value="Create" />
     (date format is <nop>YYYYxMMxDD)
</form>

See TWikiScripts for details of the parameters that the edit script understands.

TIP 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%

Automatically Generated Topicname

If you want to make a TWiki application where you need automatically generated unique topicnames, you can use 10 X's in the edit / save URL, and they will be replaced on topic save with a count value. For example, BugIDXXXXXXXXXX will result in topics named BugID0, BugID1, BugID2 etc.

Example link to create a new topic:
[[%SCRIPTURL{"edit"}%/%WEB%/BugIDXXXXXXXXXX?templatetopic=BugTemplate&amp;topicparent=%TOPIC%&amp;t=%SERVERTIME{"$day$hour$min$sec"}%][Create new item]]

Master Templates by Example

Attached is an example of an oops based template oopsbase.tmpl and an example oops dialog oopstest.tmpl based on the base template. %A% NOTE: This isn't the release version, just a quick, simple demo.

Base template oopsbase.tmpl

The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}% 

%TMPL:DEF{"sep"}% | %TMPL:END%
<html>
<head>
  <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title>
  <base href="%SCRIPTURL{"view"}%/%WEB%/%TOPIC%">
  <meta name="robots" content="noindex">
</head>
<body bgcolor="#FFFFFF">
<table width="100%" border="0" cellpadding="3" cellspacing="0">
  <tr>
    <td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%">
      <a href="%WIKIHOMEURL%">
      <img src="%PUBURLPATH%/wikiHome.gif" border="0"></a>
    </td>
    <td>
      <b>%WIKITOOLNAME% . %WEB% . </b><font size="+2">
      <B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font>
    </td>
  </tr>
  <tr bgcolor="%WEBBGCOLOR%">
    <td colspan="2">
      %TMPL:P{"webaction"}%
    </td>
  </tr>
</table>
--- ++ %TMPL:P{"heading"}%
%TMPL:P{"message"}%
<table width="100%" border="0" cellpadding="3" cellspacing="0">
  <tr bgcolor="%WEBBGCOLOR%">
    <td valign="top">
      Topic <b>%TOPIC%</b> . {
        %TMPL:P{"topicaction"}%
      }
    </td>
  </tr>
</table>
</body>

Test template oopstest.tmpl

Each oops template basically just defines some variables and includes the base template that does the layout work.

</table >

Sample screen shot of oopstest.tmpl

With URL: .../bin/oops/Sandbox/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify 

%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"}%
testscreen.gif

Related Topics: TWikiSkins, DeveloperDocumentationCategory, AdminDocumentationCategory

Warning: Can't find topic TWikiTemplatingSystem

TWiki Skins

Skins overlay regular templates with alternate header/footer layouts; topic text is not affected

Overview

Skins are customized TWikiTemplates files. You can use skins to change the look of a TWiki topic, for example, the layout of the header and footer. Rendered text between header and footer does not change. You can also use skins to define an alternate view, like a view optimized for printing.

Defining Skins

Skin files are located in the twiki/templates directory and are named with the syntax: <scriptname>.<skin>.tmpl. For example, the Printable skin for the view template is view.print.tmpl. Skin files may also be defined in TWiki topics - see TWikiTemplates for details.

Use the existing TWikiTemplates (like view.tmpl) or skin files as a base for your own skin, name it for example view.myskin.tmpl.

ALERT! Note: Two skin names have reserved meanings; text skin, and skin names starting with rss have hard-coded meanings.

The following template files are referenced in the TWiki core code, and must be defined in the templates directory for a skin to work. Remember that if a skin doesn't define a template, then TWiki will fall back to the default version of the file.

Certain template files are expected to provide certain TMPL:DEFs - these are listed in sub-bullets.

  • addform
  • attachagain
  • attachnew
  • attachtables
    • ATTACH:files:footer, ATTACH:files:header, ATTACH:files:row, ATTACH:versions:footer, ATTACH:versions:header, ATTACH:versions:row
  • changeform
  • changes
  • edit
  • form
  • formtables
    • FORM:display:footer, FORM:display:header, FORM:display:row
  • login
    • LOG_IN, LOG_IN_BANNER, LOG_OUT, LOGGED_IN_BANNER, NEW_USER_NOTE, UNRECOGNISED_USER
  • mirrorlink
  • mirrornote
  • moveattachment
  • oopsaccessdenied
    • no_such_topic, no_such_web, only_group, topic_access
  • oopsattention
    • already_exists, bad_email, bad_ver_code, bad_wikiname, base_web_missing, confirm, created_web, delete_err, illegally_named_upload, 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, web_creation_error, web_exists, web_missing, wrong_password, zero_size_upload
  • oopsleaseconflict
    • active, old
  • oopsmirror
  • oopssaveerr
  • preview
  • rdiff
  • registernotify
  • registernotifyadmin
  • rename
  • renameconfirm
  • renamedelete
  • renameweb
  • renamewebconfirm
  • renamewebdelete
  • searchbookview
  • searchformat
  • search
  • settings
  • view
twiki.tmpl is a master template conventionally used by other templates, but not used directly by code.

Variables in Skins

You can use template variables, TWikiVariables, and other predefined variables to compose your skins. Some commonly used variables in skins:

Variable: Expanded to:
%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
%SCRIPTSUFFIX% The script suffix, ex: .pl, .cgi
%WEB% The name of the current web. Note: It is recommended to URL-encode the variable in form actions with %INTURLENCODE{"%WEB%"}% for proper handling in an internationalized environment
%TOPIC% The name of the current topic. Note: It is recommended to URL-encode the variable in form actions with %INTURLENCODE{"%TOPIC%"}% for proper handling in an internationalized environment
%WEBTOPICLIST% Common links of current web, defined in the WebPreferences. It includes a 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; is set in TWikiPreferences

The "Go" Box and Navigation Box

The %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:

Bare bones header for demo only
Welcome  |  Register  |  Changes  |  Topics  |  Index  |  Search  |  Go

Using Cascading Style Sheets

Although work is underway at TWiki:Codev.CssClassNames, the regular templates files currently do not use style sheets. Many skin developers, however, choose to use them; it helps in separating style from content.

Example: To use a style sheet for the broadcast message, add this to view.myskin.tmpl: 

<style type="text/css">
.broadcastmessage {
    background: yellow; display:block;
    border-style:solid;border-width: 2px;border-color:red;
}
.broadcastmessage strong {color: red}
</style>

Then add a div tag to the %BROADCASTMESSAGE% variable located after the #PageTop anchor or after the opening form tag: 

<div class="broadcastmessage"> %BROADCASTMESSAGE% </div>

Attachment Tables

Controlling the look and feel of attachment tables is a little bit more complex than for the rest of a skin. By default the attachment table is a standard TWiki table, and the look is controlled in the same way as other tables. In a very few cases you may want to change the content of the table as well.

The format of standard attachment tables is defined through the use of special TWiki template macros which by default are defined in the templates/twiki.tmpl template using the %TMPL:DEF macro syntax described in TWikiTemplates. These macros are:

Macro Description
ATTACH:files:header Standard title bar
ATTACH:files:row Standard row
ATTACH:files:footer Footer for all screens
ATTACH:files:header:A Title bar for upload screens, with attributes column
ATTACH:files:row:A Row for upload screen
ATTACH:files:footer:A Footer for all screens
The format of tables of file versions in the Upload screen are also formattable, using the macros:
Macro Description
ATTACH:versions:header Header for versions table on upload screen
ATTACH:versions:row Row format for versions table on upload screen
ATTACH:versions:footer Footer for versions table on upload screen

The ATTACH:row macros are expanded for each file in the attachment table, using the following special tags:

Tag Description
%A_URL% URL that will recover the file
%A_REV% Revision of this file
%A_ICON% A file icon suitable for representing the attachment content
%A_FILE% The name of the file
%A_SIZE% The size of the file
%A_DATE% The date the file was uploaded
%A_USER% The user who uploaded it
%A_COMMENT% The comment they put in when uploading it
%A_ATTRS% The attributes of the file as seen on the upload screen e.g "h" for a hidden file

Note: it is easy to change the look and feel for an entire site by editing the twiki.tmpl template file. However, to simplify upgrading, you should avoid doing this. Instead, write a skin-specific template file e.g. attach.myskin.tmpl and use %TMPL:INCLUDE{attach.myskin.tmpl}% to include it in each of your skin files. As long as it is included after twiki.tmpl, your macro definitions will override the defaults defined there.

Packaging and Publishing Skins

See TWiki:Plugins/SkinPackagingHowTo and TWiki:Plugins/SkinDeveloperFAQ

Browsing Installed Skins

You can try all installed skins in TWikiSkinBrowser.

Activating Skins

TWiki uses a skin search path, which lets you combine skins additively. The skin path is defined using a combination of TWikiVariables and URL parameters.

TWiki works by asking for a template for a particular function - for example, 'view'. The detail of how templates are searched for is described in TWikiTemplates, but in summary, the templates directory is searched for a file called 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 setting the %SKIN% TWiki Variable:

  • Set SKIN = catskin, bearskin

You can also add a parameter to the URL, such as ?skin=catskin, bearskin. Example activation of PlainSkin that removes all page decoration:

  • /bin/view/TWiki/TWikiSkins?skin=plain

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

This pushes a different skin to the front of the skin search path (so for our example above, that final skin path will be ruskin, catskin, bearskin). There is also an equivalent cover URL parameter.

The full skin path is built up as follows: %SKIN% (or ?skin if it is set), then %COVER% is added, then ?cover.

Hard Coded Skins

The 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: AdminDocumentationCategory, DeveloperDocumentationCategory

TWiki Variables

Special text strings expand on the fly to display user data or system info

TWikiVariables are text strings - %VARIABLE% - that expand into content whenever a page is rendered for viewing. Some variables can even take parameters - %VARIABLE{parameter="value"}%.

  • To leave a variable unexpanded, precede it with an exclamation point, e.g. type !%TOPIC% to get %TOPIC%.
  • Variables are expanded relative to the topic they are used in, not the topic they are defined in.
  • Optional plugins may extend the set of predefined variables

Setting Variables

You can set variables in all the following places:
  1. local site level in TWikiPreferences
  2. user level in individual user topics in Main web
  3. web level in WebPreferences of each web
  4. topic level in topics in webs
  5. plugin topics (see TWikiPlugins)
  6. session variables (if sessions are enabled)

Settings at higher-numbered levels override settings of the same variable at lower numbered levels, unless the variable was included in the setting of FINALPREFERENCES at a lower-numbered level, in which case it is locked at the value it has at that level.

There are many predefined variables defined by default, and many more may already have been defined for your site. You can put %ALL_VARIABLES% into a topic anywhere in your TWiki to get a full listing of the variables defined there.

The syntax for setting Variables is the same anywhere in TWiki (on its own TWiki bullet line, including nested bullets):
[multiple of 3 spaces] * [space] Set [space] VARIABLENAME [space] = [value]

Examples:
  • Set VARIABLENAME = value
    • Set VARIABLENAME = value
Spaces between the = sign and the value will be ignored. You can split a value over several lines by starting following lines with [multiple of 3 spaces] - as long as you don't try to use * as the first character on the following line.
Example: 
   * Set VARIABLENAME = value starts here
   and continues 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 variable
  • To place a logo anywhere in a web by typing %MYLOGO%, define the Variable on the web's WebPreferences page, and upload a logo file, ex: mylogo.gif. You can upload by attaching the file to WebPreferences, or, to avoid clutter, to any other topic in the same web, ex: LogoTopic - Sample variable setting in WebPreferences:
    • Set MYLOGO = %PUBURLPATH%/TWiki/LogoTopic/mylogo.gif

You can also set preference variables on a topic by clicking the link Edit topic preference settings under More topic actions. Preferences set in this manner are not visible in the topic text, but take effect nevertheless.

Access Control Variables

You should review TWikiAccessControl for details about security settings, which are managed using TWikiVariables.

Local values for variables

Certain topics (a users home topic, web site and default preferences topics) have a problem; variables defined in those topics can have two meanings. For example, consider a user topic. A user may want to use a double-height edit box when they are editing their home topic - but only when editing their home topic. The rest of the time, they want to have a normal edit box. This separation is achieved using 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 = 20
Then 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! %ALL_VARIABLES% 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.

Predefined Variables

Most predefined variables return values that were either set in the configuration when TWiki was installed, or taken from server info (like current username, or date and time). Some, like =%SEARCH%, are powerful and general tools.

  • ALERT! Predefined variables can be overridden by Preferences variables
  • ALERT! Plugins may extend the set of predefined variables see individual Plugins topics for details
  • TIP Take the time to thoroughly read through ALL preference variables. If you actively configure your site, review variables periodically. They cover a wide range of functions, and it can be easy to miss the one perfect variable for something you have in mind. For example, see %INCLUDINGTOPIC%, %INCLUDE%, and the mighty %SEARCH%.
This version of TWiki - Wed, 14 Dec 2005 build 7851 - predefines the following variables

ACTIVATEDPLUGINS -- list of currently activated plugins

ATTACHURL -- full URL for attachments in the current topic

ATTACHURLPATH -- path of the attachment URL of the current topic

AUTHREALM -- authentication realm

BASETOPIC -- base topic where an INCLUDE started

  • The name of the topic where a single or nested INCLUDE started - same as %TOPIC% if there is no INCLUDE
  • Syntax: %BASETOPIC%
  • Related: BASEWEB, INCLUDINGTOPIC, INCLUDE, TOPIC

BASEWEB -- base web where an INCLUDE started

  • The web name where the includes started, e.g. the web of the first topic of nested includes. Same as %WEB% in case there is no include.
  • Syntax: %BASEWEB%
  • Related: BASETOPIC, INCLUDINGWEB, INCLUDE, WEB

DATE -- signature format date

DISPLAYTIME -- display time

DISPLAYTIME{"format"} -- formatted display time

  • Formatted time - either GMT or Local server time, depending on setting in configure. Same format qualifiers as %GMTIME%
  • Syntax: %DISPLAYTIME{"format"}%
  • Example: %DISPLAYTIME{"$hou:$min"}% expands to 02:48
  • Related: DISPLAYTIME, GMTIME, SERVERTIME

ENCODE{"string"} -- encodes a string

  • Syntax: %ENCODE{"string"}%
  • Supported parameters:
    Parameter: Description: Default:
    "string" String to encode required (can be empty)
    type="entity" Encode special characters into HTML entities, like a double quote into &#034; URL encoding
    type="url" Encode special characters for URL parameter use, like a double quote into %22 (this is the default)
  • Example: %ENCODE{"spaced name"}% expands to spaced%20name
  • Related: URLPARAM

ENDSECTION{"name"} -- marks the end of a named section

FAILEDPLUGINS -- debugging for plugins that failed to load, and handler list

FORMFIELD{"format"} -- renders a field in the form attached to some topic

  • Syntax: %FORMFIELD{"fieldname"}%
  • Supported parameters:
    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 ""
  • Example: %FORMFIELD{"ProjectName" topic="Projects.SushiProject" default="(not set)" alttext="ProjectName field found"}%
  • Related: SEARCH

GMTIME -- GM time

GMTIME{"format"} -- formatted GM time

  • Syntax: %GMTIME{"format"}%
  • Supported variables:
    Variable: Unit: Example
    $seconds seconds 59
    $minutes minutes 59
    $hours hours 23
    $day day of month 31
    $wday day of the Week (Sun, Mon, Tue, Wed, Thu, Fri, Sat) Thu
    $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 2026-06-18T02:48Z
    $rcs RCS format timestamp 2026/06/18 02:48:03
    $http E-mail & http format timestamp Thu, 18 Jun 2026 02:48:03 GMT
    $epoch Number of seconds since 00:00 on 1st January, 1970 1781750883
  • Variables can be shortened to 3 characters
  • Example: %GMTIME{"$day $month, $year - $hour:$min:$sec"}% expands to 18 Jun, 2026 - 02:48:03
  • ALERT! 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.
  • Related: DISPLAYTIME, GMTIME, SERVERTIME

HOMETOPIC -- home topic in each web

HTTP -- get HTTP headers

HTTPS -- get HTTPS headers

  • The same as %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.
  • Syntax: %HTTPS%
  • Syntax: %HTTPS{'Header-name'}%
  • Related: HTTP, REMOTE_ADDR, REMOTE_PORT, REMOTE_USER

HTTP_HOST -- environment variable

ICON{"name"} -- small documentation graphic or icon of common attachment types

  • Small graphic (commonly 16x16 pixels) used to enhance topics. Specify the name of the graphic.
  • A set of 16x16 pixel icons of common attachment types is provided. Specify file type only, file name, or full path name.
  • Syntax: %ICON{"name"}% or %ICON{"type"}%
  • Graphic samples: arrowbright arrowbright, bubble bubble, choice-yes choice-yes, hand hand
  • Filetype samples: bmp bmp, doc doc, gif gif, hlp hlp, html html, mp3 mp3, pdf pdf, ppt ppt, txt txt, xls xls, xml xml, zip zip
  • Example: %ICON{"info"}% expands to info
  • Related: TWikiPreferences, FileAttachments, TWikiDocGraphics

ICONPATH{"name"} -- url path of small documentation graphic or icon of common attachment types

IF{"condition" ...} -- simple conditionals

  • Syntax: %IF{"CONDITION" then="THEN" else="ELSE"}%
  • In the example above, if CONDITION evaluates to TRUE, then THEN will be shown; otherwise ELSE will be shown.
  • Related: IfStatements has more information on how to write %IF{}% statements
  • Related: $IF() of SpreadSheetPlugin

INCLUDE{"page"} -- include other topic or web page

  • Syntax: %INCLUDE{"page" ...}%
  • Supported parameters:
    Parameter: Description: Default:
    "SomeTopic" The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}%  
    "Web.Topic" A topic in another web, i.e. %INCLUDE{"TWiki.SiteMap"}%  
    "http://..." A full qualified URL, i.e. %INCLUDE{"http://twiki.org:80/index.html"}%. Supported content types are text/html and text/plain.
    IDEA! 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) on preferences setting
    section="name" Includes only the specified section, as defined in the included topic by the SECTION and ENDSECTION variables  
    PARONE="val 1"
    PARTWO="val 2"         		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.  
  • Examples: See IncludeTopicsAndWebPages
  • Related: BASETOPIC, BASEWEB, INCLUDINGTOPIC, INCLUDINGWEB, STARTINCLUDE, STOPINCLUDE, SECTION, ENDSECTION

INCLUDINGTOPIC -- name of topic that includes current topic

  • The name of the topic that includes the current topic - same as %TOPIC% in case there is no include
  • Syntax: %INCLUDINGTOPIC%
  • Related: BASETOPIC, INCLUDINGWEB, INCLUDE, TOPIC

INCLUDINGWEB -- web that includes current topic

  • The web name of the topic that includes the current topic - same as %WEB% if there is no INCLUDE.
  • Syntax: %INCLUDINGWEB%
  • Related: BASEWEB, INCLUDINGTOPIC, INCLUDE, WEB

LANGUAGES -- list available TWiki languages

  • List the languages available (as PO files) to TWiki. Those are the languages in which TWiki's user interface is available.
  • Syntax: %LANGUAGES{...}%
  • Supported parameters:
    Parameter: Description: Default:
    format format for each item. See below for variables available in the format string. "   * $langname"
    sep separator between items. "\n" (newline)
  • format variables:
    Variable Meaning
    $langname language's name, as informed by the translators
    $langtag language's tag. Ex: en, pt-br, etc.

LOCALSITEPREFS -- web.topicname of site preferences topic

  • The full name of the local site preferences topic. This topic is read for preferences before TWiki.%TWIKIPREFSTOPIC% is read.
  • Syntax: %LOCALSITEPREFS%
  • Expands to: Main.TWikiPreferences

LOGIN -- present a full login link

LOGOUT -- present a full logout link

MAKETEXT -- creates text using TWiki's I18N infrastructure

  • Syntax = %MAKETEXT{"string" args="..."}
  • Supported parameters:
    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
  • Examples:
    • %MAKETEXT{string="Notes:"}%
      expands to
      Notes:
    • %MAKETEXT{"Contact [_1] if you have any questions." args="%WIKIWEBMASTER%"}%
      expands to
      Contact jpw@rainysky.org if you have any questions.
    • %MAKETEXT{"Did you want to [[[_1]][reset [_2]'s password]]?" args="TWiki.ResetPassword,%WIKIUSERNAME%"}%
      expands to
      Did you want to reset Main.TWikiGuest's password?
  • Notes:
    • that TWiki will translate the string to the current user's language only if it has such string in its translation table for that language.
    • Amperstands (&) 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.
    • translatable string starting with underscores (_) are reserved. You should not use translatable phrases starting with an underscore.

MAINWEB -- name of Main web

META -- displays meta-data

  • Provided mainly for use in templates, this variable generates the parts of the topic view that relate to meta-data (attachments, forms etc.) The formfield item is the most likely to be useful to casual users.
  • Syntax: %META{ "item" ...}%
  • Parameters:
    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
  • Related: METASEARCH

METASEARCH -- special search of meta data

  • Syntax: %METASEARCH{...}%
  • Supported parameters:
    Parameter: Description: Default:
    type="topicmoved" What sort of search is required?
    "topicmoved" if search for a topic that may have been moved
    "parent" if searching for topics that have a specific parent i.e. its children
    "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
  • Example: %METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%
  • Example: You may want to use this in WebTopicViewTemplate and WebTopicNonWikiTemplate:
    %METASEARCH{type="parent" web="%WEB%" topic="%TOPIC%" title="Children: "}%
  • Example: %METASEARCH{type="field" name="Country" value="China"}%
  • Related: SEARCH, META

NOP -- template text not to be expanded in instantiated topics

  • Syntax: %NOP%
  • Syntax: %NOP{...}%
  • Available in template topics only. See TWikiTemplates#HtmlTemplates for details. In normal topic text, simply expands to whatever is in the curly braces (if anything).

NOTIFYTOPIC -- name of the notify topic

PLUGINDESCRIPTIONS -- list of plugin descriptions

  • Syntax: %PLUGINDESCRIPTIONS%
  • Expands to:
    • CommentPlugin (Dakar, 6827): Allows users to quickly post comments to a page without an edit/preview/save cycle.
    • EditTablePlugin (Dakar, 6827): Edit TWiki tables using edit fields, date pickers and drop down boxes
    • ExifMetaDataPlugin (1.010): Displays EXIF data for jpeg images attached to a topic.
    • GuidPlugin: (disabled)
    • HeadlinesPlugin (1.95, 7779): Build news portals that show headline news based on RSS news feeds from news sites.
    • InterwikiPlugin (Dakar, $Rev: 7873$): Link ExternalSite:Page text to external sites based on aliases defined in the %RULESTOPIC% topic
    • PreferencesPlugin (Dakar, 6827): Allows editing of preferences using fields predefined in a form
    • RedirectPlugin (1.000): This plugin allows one to produce TWiki topics that automatically redirect to other TWiki topics or URLs.
    • SlideShowPlugin (Dakar, $Rev: 7873$): Create web based presentations based on topics with headings.
    • SmiliesPlugin (Dakar, 6827): Render smilies as icons, like  :-) for smile or  :cool: for :cool:
    • SpreadSheetPlugin (Dakar, 6827): Add spreadsheet calculation like "$SUM( $ABOVE() )" to tables located in FS topics.
    • TablePlugin (Dakar, 6850): Control attributes of tables and sorting of table columns
  • Related: ACTIVATEDPLUGINS, FAILEDPLUGINS, PLUGINVERSION

PLUGINVERSION -- the version of the TWiki Plugin API

  • This is the $TWiki::Plugins::VERSION number, also indicating the version of the Func module
  • Syntax: %PLUGINVERSION%
  • Expands to: 1.1
  • Related: PLUGINVERSION{"name"}, WIKIVERSION

PLUGINVERSION{"name"} -- the version of an installed Plugin

PUBURL -- the base URL of attachments

  • Syntax: %PUBURL%
  • Expands to: https://fs.rainysky.org/pub
  • Example: You can refer to a file attached to another topic with %PUBURL%/%WEB%/OtherTopic/image.gif
  • Related: ATTACHURL, PUBURLPATH, SCRIPTURL, FileAttachments

PUBURLPATH -- the base URL path of attachments

QUERYSTRING -- full, unprocessed string of parameters to this URL

  • Syntax: %QUERYSTRING%
  • Expands to: rev=26;skin=print.pattern%2Cpattern
  • String of all the URL parameters that were on the URL used to get to the current page. For example, if you add ?name=Samantha;age=24;eyes=blue to this URL you can see this in action. This string can be appended to a URL to pass parameter values on to another page.
  • ALERT! 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{}%.
  • Related: URLPARAM

REMOTE_ADDR -- environment variable

REMOTE_PORT -- environment variable

REMOTE_USER -- environment variable

REVINFO -- revision information of current topic

REVINFO{"format"} -- formatted revision information of topic

  • Syntax: %REVINFO{"format"}%
  • Supported parameters:
    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
  • Supported variables in format:
    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
  • Example: %REVINFO{"$date - $wikiusername" rev="1.1"}% returns revision info of first revision
  • Related: REVINFO

SCRIPTNAME -- name of current script

  • The name of the current script is shown, including script suffix, if any (for example viewauth.cgi)
  • Syntax: %SCRIPTNAME%
  • Expands to: view
  • Related: SCRIPTSUFFIX, SCRIPTURL

SCRIPTSUFFIX -- script suffix

  • Some FS installations require a file extension for CGI scripts, such as .pl or .cgi
  • Syntax: %SCRIPTSUFFIX%
  • Expands to:
  • Related: SCRIPTNAME, SCRIPTURL, SCRIPTURLPATH

SCRIPTURL -- script URL

  • Syntax: %SCRIPTURL%
  • Expands to: https://fs.rainysky.org/bin
  • Example: To get the authenticated version of current topic write "}%L%/viewauth%SCRIPTSUFFIX%/%WEB%/%TOPIC% which expands to /bin/viewauth/TWiki/TWikiVariablesNtoZ
  • Syntax: %SCRIPTURL{"script"}%
  • Expands to: /bin/script
  • Example: To get the authenticated version of current topic write %SCRIPTURL{"viewauth"}%/TWiki/TWikiVariablesNtoZ which expands to /bin/viewauth/TWiki/TWikiVariablesNtoZ
  • This second form of SCRIPTURL handles URL rewriting (see TWiki:TWiki.ShorterURLCookbook).
  • Related: PUBURL, SCRIPTNAME, SCRIPTSUFFIX, SCRIPTURLPATH

SCRIPTURLPATH -- script URL path

SEARCH{"text"} -- search content

  • Inline search, shows a search result embedded in a topic
  • Syntax: %SEARCH{"text" ...}%
  • Supported parameters:    
    Parameter: Description: Default:
    "text" Search term. Is a keyword search, literal search or regular expression search, depending on the type parameter. SearchHelp has more required
    search="text" (Alternative to above) N/A
    web="Name"
    web="Main, Know"
    web="all"     		Comma-separated list of webs to search. 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
     "formfield(name)"=     		Sort the results of search by the topic names, topic creation time, last modified time, last editor, or named field of TWikiForms. The sorting is done web by web; 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"
  • Example: %SEARCH{"wiki" web="Main" scope="topic"}%
  • Example with format: %SEARCH{"FAQ" scope="topic" nosearch="on" nototal="on" header="| *Topic: * | *Summary: * |" format="| $topic | $summary |"% (displays results in a table with header - details)
  • HELP 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%" }%
  • Related: METASEARCH, TOPICLIST, WEBLIST, FormattedSearch

SECTION{"name"} -- marks the start of a named section

SERVERTIME -- server time

SERVERTIME{"format"} -- formatted server time

  • Same format qualifiers as %GMTIME%
  • Syntax: %SERVERTIME{"format"}%
  • Example: %SERVERTIME{"$hou:$min"}% expands to 20:48
  • ALERT! 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.
  • Related: DISPLAYTIME, GMTIME, SERVERTIME

SESSION_VARIABLE -- get, set or clear a session variable

SESSIONID -- unique ID for this session

SESSIONVAR -- name of CGI and session variable that stores the session ID

SPACEDTOPIC -- topic name, spaced and URL-encoded

  • The current topic name with added spaces, for regular expression search of backlinks
  • Syntax: %SPACEDTOPIC%
  • Expands to: TWiki%20*Variables%20*Nto%20*Z
  • TIP Hint: This variable is provided almost exclusively for generating URLs for searching for backlinks to topics
  • Related: TOPIC

STARTINCLUDE -- start position of topic text if included

  • If present in included topic, start to include text from this location up to the end, or up to the location of the %STOPINCLUDE% variable. A normal view of the topic shows everything exept the %STARTINCLUDE% variable itself. An optional parameter can be used to control whether the content is expanded.
  • Syntax: %STARTINCLUDE%
  • Syntax: %STARTINCLUDE{param}%
    • If param does not expand to a non-zero integer, then nothing will be included.
  • Related: ENDSECTION, INCLUDE, SECTION, STOPINCLUDE

STATISTICSTOPIC -- name of statistics topic

STOPINCLUDE -- end position of topic text if included

  • If present in included topic, stop to include text at this location and ignore the remaining text. A normal view of the topic shows everyting exept the %STOPINCLUDE% variable itself.
  • Syntax: %STOPINCLUDE%
  • Related: ENDSECTION, INCLUDE, SECTION, STARTINCLUDE

TOC -- table of contents of current topic

TOC{"Topic"} -- table of contents

  • Syntax: %TOC{"SomeTopic" ...}%
  • Table of Contents. Shows a TOC that is generated automatically based on headings of a topic. Headings in WikiSyntax ("---++ text") and HTML ("<h2>text</h2>") are taken into account. Any heading text after "!!" is excluded from the TOC; for example, write "---+!! text" if you do not want to list a header in the TOC
  • Supported parameters:
    Parameter: Description: Default:
    "TopicName" topic name Current topic
    web="Name" Name of web Current web
    depth="2" Limit depth of headings shown in TOC 6
    title="Some text" Title to appear at top of TOC none
  • Example: %TOC{depth="2"}%
  • Example: %TOC{"TWikiDocumentation" web="TWiki" title="Contents:"}%
  • Example: see TWiki:Sandbox.TestTopicInclude
  • TIP 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-->.
  • Related: TOC

TOPIC -- name of current topic

TOPICLIST{"format"} -- topic index of a web

  • The "format" defines the format of one topic item. It may include variables: The $name variable gets expanded to the topic name; the $web variable gets expanded to the name of the web.
  • Syntax: %TOPICLIST{"format" ...}%
  • Supported parameters:
    Parameter: Description: Default:
    "format" Format of one line, may include $name and $web variables "$name"
    format="format" (Alternative to above) "$name"
    separator=", " line separator "\n" (new line)
    web="Name" Name of web Current web
  • Example: %TOPICLIST{"   * $web.$name"}% creates a bullet list of all topics
  • Example: %TOPICLIST{separator=", "}% creates a comma separated list of all topics
  • Example: %TOPICLIST{" <option>$name</option>"}% creates an option list (for drop down menus)
  • Related: SEARCH, WEBLIST

TWIKIWEB -- name of TWiki documentation web

  • The web containing all documentation and site-wide preference settings for FS
  • Syntax: %TWIKIWEB%
  • Expands to: TWiki
  • Related: MAINWEB

URLPARAM{"name"} -- get value of a URL parameter

  • Returns the value of a URL parameter.
  • Syntax: %URLPARAM{"name"}%
  • Supported parameters:
    Parameter: Description: Default:
    "name" The name of a URL parameter required
    default="..." Default value in case parameter is empty or missing empty string
    newline="<br />" Convert newlines in textarea to other delimiters no conversion
    encode="entity" Encode special characters into HTML entities, like a double quote into &#034;. This is needed if text is put into an HTML form field no encoding
    encode="url" Encode special characters for URL parameter use, like a double quote into %22 no encoding
    multiple="on"
    multiple="[[$item]]"     		If set, gets all selected elements of a <select multiple="multiple"> tag. A format can be specified, with $item indicating the element, e.g. multiple="Option: $item" first element
    separator=", " Separator between multiple selections. Only relevant if multiple is specified "\n" (new line)
  • Example: %URLPARAM{"skin"}% returns print for a .../view/TWiki/TWikiVariablesNtoZ?skin=print URL.
  • ALERT! 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.
  • ALERT! Note: There is a risk that this variable could be misused for cross-site scripting.
  • Related: SEARCH, FormattedSearch, QUERYSTRING

USERNAME -- your login username

USERLANGUAGE -- current user's language

  • Returns the language code for the language used as the current user. This is the language actually used by TWiki Internationalization (e.g. in user interface).
  • The language is detected from the user's browser, unless some site/web/user/session-defined setting overrides it:
    • Is the LANGUAGE preference is set, it's used as user's language instead of any language detected from the browser.
    • Avoid to define it LANGUAGE at a non per-user way, so each user can choose his/her preferred language.
  • Related: LANGUAGES

VAR{"NAME" web="Web"} -- get a preference value from another web

  • Syntax: %VAR{"NAME" web="Web"}%
  • Example: To get %WEBBGCOLOR% of the Main web write %VAR{"WEBBGCOLOR" web="Main"}%, which expands to #FFEFA6
  • Related: WEBPREFSTOPIC

WEB -- name of current web

WEBLIST{"format"} -- index of all webs

  • List of all webs. Hidden webs are excluded, e.g. webs with a NOSEARCHALL=on preference variable. The "format" defines the format of one web item. The $name variable gets expanded to the name of the web, $qname gets expanded to double quoted name, $marker to marker where web matches selection.
  • Syntax: %WEBLIST{"format" ...}%
  • Supported parameters:
    Parameter: Description: Default:
    "format" Format of one line, may include $name variable. (to support HierarchicalWebs?, there are 2 added variables $webindent and $indentedname) "$name"
    format="format" (Alternative to above) "$name"
    separator=", " line separator "\n" (new line)
    webs="public" comma sep list of Web, public expands to all non-hidden "public"
    marker="selected" Text for $marker where item matches selection, otherwise equals "" "selected"
    selection="%WEB%" Current value to be selected in list section="%WEB%"
  • Example: %WEBLIST{"   * [[$name.WebHome]]"}% creates a bullet list of all webs.
  • Example: %WEBLIST{"<option $marker value=$qname>$name</option>" webs="Trash,public" selection="TWiki" separator=" "}% Dropdown of all public Webs + Trash Web, current Web highlighted.
  • Related: TOPICLIST, SEARCH

WEBPREFSTOPIC -- name of web preferences topic

WIKIHOMEURL -- site home URL

  • ALERT! Note: DEPRECATED, use %WIKILOGOURL% defined in WebPreferences instead. This variables value is defined in lib/TWiki.cfg::$wikiHomeUrl which is marked deprecated. Will be removed in future versions.

WIKINAME -- your Wiki username

WIKIPREFSTOPIC -- name of site-wide preferences topic

WIKITOOLNAME -- name of your TWiki site

WIKIUSERNAME -- your Wiki username with web prefix

  • Your %WIKINAME% with Main web prefix, useful to point to your FS home page
  • Syntax: %WIKIUSERNAME%
  • Expands to: Main.TWikiGuest, renders as TWikiGuest
  • ALERT! 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
  • Related: REMOTE_USER, USERNAME, WIKINAME

WIKIUSERSTOPIC -- name of topic listing all registers users

  • Syntax: %WIKIUSERSTOPIC%
  • Expands to: TWikiUsers, with Main prefix renders as TWikiUsers
  • Related: WIKIUSERNAME

WIKIVERSION -- the version of the installed TWiki engine

Warning: Can't find topic MetaDataDefinition

Warning: Can't find topic TWikiFormTemplate

TWiki Plugins

Plug-in enhanced feature add-ons, with a Plugin API for developers

Overview

You can add Plugins to extend TWiki functionality, without altering the core code. A plug-in approach lets you:

  • add virtually unlimited features while keeping the main TWiki code compact and efficient;
  • heavily customize an installation and still do clean updates to new versions of TWiki;
  • rapidly develop new TWiki functions in Perl using the Plugin API.

Everything to do with TWiki Plugins - demos, new releases, downloads, development, general discussion - is available at TWiki.org, in the TWiki:Plugins web.

TWiki plugins are developed and contributed by interested members of the community. Plugins are provided on an 'as is' basis; they are not a part of TWiki, but are independently developed and maintained.

Installing Plugins

Each TWiki Plugin comes with its own documentation: Step-by-step installation instructions, a detailed description of any special requirements, version details, and a working example for testing. Many plugins have an install script that automates these steps for you.

Special Requests: Some Plugins need certain Perl modules to be preinstalled on the host system. Plugins may also use other resources, like graphics, other modules, applications, templates. You should be able to find detailed instructions are in the Plugin documentation.

Each Plugin has a standard release topic, located in the TWiki:Plugins web at TWiki.org. There's usually a number of other related topics, such as a developers page, and an appraisal page.

On-Site Pretesting

The recommended approach to testing new Plugins before making them public is to create a second local TWiki installation, and test the plugin there. You can allow selected users access to the test area. Once you are satisifed that it won't compromise your main installation, you can install it there as well.

InstalledPlugins shows which Plugins are: 1) installed, 2) loading properly and 3) what TWiki:Codev.PluginHandlers they invoke. Any failures are shown in the Errors section. The %FAILEDPLUGINS% variable can be used to debug failures. You may also want to check your webserver error log and the various TWiki log files.

Some Notes on Plugin Performance

The performance of the system depends to some extent on the number of Plugins installed and on the Plugin implementation. Some Plugins impose no measurable performance decrease, some do. For example, a Plugin might use many Perl libraries that need to be initialized with each page view (unless you run mod_perl). You can only really tell the performance impact by installing the Plugin and by measuring the performance with and without the new Plugin. Use the TWiki:Plugins.PluginBenchmarkAddOn, or test manually with the Apache ab utility. Example on Unix:
time wget -qO /dev/null /bin/view/TWiki/AbcPlugin

TIP 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.)

Managing Installed Plugins

Some Plugins require additional settings or offer extra options that you have to select. Also, you may want to make a Plugin available only in certain webs, or temporarily disable it. And may want to list all available Plugins in certain topics. You can handle all of these management tasks with simple procedures.

Enabling Plugins

Plugins can be enabled and disabled with the configure script. An installed Plugin needs to be enabled before it can be used.

Plugin Evaluation Order

By default, TWiki executes Plugins in alphabetical oder on Plugin name. It is possible to change the order, for example to evaluate a database variables before the speadsheet CALCs. This can be done with the configure script.

Plugin Specific Settings

Plugin-specific settings are done in individual Plugin topics. Two settings are standard for each Plugin:

  1. One line description, used to form the bullets describing the Plugins in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Create dynamic foo bar reports
  2. Debug Plugin, output can be seen in data/debug.txt. Set to 0=off or 1=on:
    • Set DEBUG = 0
  • The settings can be retrieved as Preferences variables like %<pluginname>_<var>%. For example, %DEFAULTPLUGIN_SHORTDESCRIPTION% shows the description of the DefaultPlugin.

Listing Active Plugins

Plugin status variables let you list all active Plugins wherever needed.

%ACTIVATEDPLUGINS%

On this TWiki site, the enabled Plugins are: CommentPlugin, EditTablePlugin, ExifMetaDataPlugin, HeadlinesPlugin, InterwikiPlugin, PreferencesPlugin, RedirectPlugin, SlideShowPlugin, SmiliesPlugin, SpreadSheetPlugin, TablePlugin.

%PLUGINDESCRIPTIONS%

  • CommentPlugin (Dakar, 6827): Allows users to quickly post comments to a page without an edit/preview/save cycle.
  • EditTablePlugin (Dakar, 6827): Edit TWiki tables using edit fields, date pickers and drop down boxes
  • ExifMetaDataPlugin (1.010): Displays EXIF data for jpeg images attached to a topic.
  • GuidPlugin: (disabled)
  • HeadlinesPlugin (1.95, 7779): Build news portals that show headline news based on RSS news feeds from news sites.
  • InterwikiPlugin (Dakar, $Rev: 7873$): Link ExternalSite:Page text to external sites based on aliases defined in the %RULESTOPIC% topic
  • PreferencesPlugin (Dakar, 6827): Allows editing of preferences using fields predefined in a form
  • RedirectPlugin (1.000): This plugin allows one to produce TWiki topics that automatically redirect to other TWiki topics or URLs.
  • SlideShowPlugin (Dakar, $Rev: 7873$): Create web based presentations based on topics with headings.
  • SmiliesPlugin (Dakar, 6827): Render smilies as icons, like  :-) for smile or  :cool: for :cool:
  • SpreadSheetPlugin (Dakar, 6827): Add spreadsheet calculation like "$SUM( $ABOVE() )" to tables located in FS topics.
  • TablePlugin (Dakar, 6850): Control attributes of tables and sorting of table columns

%FAILEDPLUGINS%

PluginErrors
CommentPlugin none
EditTablePlugin none
ExifMetaDataPlugin none
GuidPlugin 
TWiki::Plugins::GuidPlugin could not be loaded.  Errors were: 
Can't locate loadable object for module Data::UUID in @INC (@INC contains: /home/rainysky/public_html/fs/lib/CPAN/lib//arch/ /home/rainysky/public_html/fs/lib/CPAN/lib//5.16.3/x86_64-linux-thread-multi/ /home/rainysky/public_html/fs/lib/CPAN/lib//5.16.3/ /home/rainysky/public_html/fs/lib/CPAN/lib// /home/rainysky/public_html/fs/lib . /usr/local/lib64/perl5 /usr/local/share/perl5 /usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl /usr/lib64/perl5 /usr/share/perl5) at /home/rainysky/public_html/fs/lib/TWiki/Plugins/GuidPlugin.pm line 60.
Compilation failed in require at /home/rainysky/public_html/fs/lib/TWiki/Plugins/GuidPlugin.pm line 60.
BEGIN failed--compilation aborted at /home/rainysky/public_html/fs/lib/TWiki/Plugins/GuidPlugin.pm line 60.
Compilation failed in require at (eval 37) line 1.
BEGIN failed--compilation aborted at (eval 37) line 1.

----
HeadlinesPlugin none
InterwikiPlugin none
PreferencesPlugin none
RedirectPlugin none
SlideShowPlugin none
SmiliesPlugin none
SpreadSheetPlugin none
TablePlugin none
HandlerPlugins
afterAttachmentSaveHandler
afterCommonTagsHandler
afterEditHandler
afterSaveHandler
beforeAttachmentSaveHandler
beforeCommonTagsHandler
beforeEditHandler
beforeSaveHandlerCommentPlugin
commonTagsHandlerCommentPlugin
EditTablePlugin
ExifMetaDataPlugin
HeadlinesPlugin
RedirectPlugin
SlideShowPlugin
SmiliesPlugin
SpreadSheetPlugin
earlyInitPlugin
endRenderingHandler
initPluginCommentPlugin
EditTablePlugin
ExifMetaDataPlugin
HeadlinesPlugin
InterwikiPlugin
PreferencesPlugin
RedirectPlugin
SlideShowPlugin
SmiliesPlugin
SpreadSheetPlugin
TablePlugin
initializeUserHandler
insidePREHandler
modifyHeaderHandler
mergeHandler
outsidePREHandler
postRenderingHandlerEditTablePlugin
PreferencesPlugin
preRenderingHandlerInterwikiPlugin
PreferencesPlugin
SmiliesPlugin
TablePlugin
redirectCgiQueryHandler
registrationHandler
renderFormFieldForEditHandler
renderWikiWordHandler
startRenderingHandler
writeHeaderHandler
12 plugins

The TWiki Plugin API

The Application Programming Interface (API) for TWiki Plugins provides the specifications for hooking into the core TWiki code from your external Perl Plugin module.

Available Core Functions

The TWikiFuncDotPm module (lib/TWiki/Func.pm) describes all the interfaces available to Plugins. Plugins should only use the interfaces described in this module.

ALERT! 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.

Predefined Hooks

In addition to TWiki core functions, Plugins can use predefined hooks, or call backs, as described in the lib/TWiki/Plugins/EmptyPlugin.pm module.

  • All but the initPlugin are disabled. To enable a call back, remove DISABLE_ from the function name.

TWiki:Codev/StepByStepRenderingOrder helps you decide which rendering handler to use.

Hints on Writing Fast Plugins

  • Delay initialization as late as possible. For example, if your plugin is a simple syntax processor, you might delay loading extra Perl modules until you actually see the syntax in the text.
  • For example, use an eval block like this:
    eval { require IPC::Run }
    return "<font color=\"red\">SamplePlugin: Can't load required modules ($@)</font>" if $@;
  • You can use a flag to avoid running the initialization twice
  • The TWiki:Plugins.PluginBenchmarkAddOn comes in handy to measure and fine-tune the performance of your Plugin

Plugin Version Detection

To eliminate the incompatibility problems bound to arise from active open Plugin development, a Plugin versioning system is provided for automatic compatibility checking.

  • All modules require a $VERSION='0.000' variable, beginning at 1.000.

  • The initPlugin handler should check all dependencies and return TRUE if the initialization is OK or FALSE if something went wrong.
    • The Plugin initialization code does not register a Plugin that returns FALSE (or that has no initPlugin handler).

  • $TWiki::Plugins::VERSION in the TWiki::Plugins module contains the TWiki Plugin API version, currently 1.1.
    • You can also use the %PLUGINVERSION{}% variable to query the Plugin API version or the version of installed Plugins.

Security

  • Badly written plugins can open huge security holes in TWiki. This is especially true if care isn't taken to prevent execution of arbitrary commands on the server.
  • Don't allow sensitive configuration data to be edited by users. it is better to add sensitive configuration options to the TWiki::cfg hash than adding it as preferences in the plugin topic
  • Always use the TWiki::Sandbox to execute commands.
  • Always audit the plugins you install, and make sure you are happy with the level of security provided. While every effort is made to monitor plugin authors activities, at the end of the day they are uncontrolled user contributions.

Creating Plugins

With a reasonable knowledge of the Perl scripting language, you can create new Plugins or modify and extend existing ones. Basic plug-in architecture uses an Application Programming Interface (API), a set of software instructions that allow external code to interact with the main program. The TWiki Plugin API Plugins by providing a programming interface for TWiki.

Anatomy of a Plugin

A basic TWiki Plugin consists of two elements:

  • a Perl module, ex: MyFirstPlugin.pm
  • a documentation topic, ex: MyFirstPlugin.txt

The Perl module can be a block of code that connects with TWiki alone, or it can include other elements, like other Perl modules (including other Plugins), graphics, TWiki templates, external applications (ex: a Java applet), or just about anything else it can call. In particular, files that should be web-accessible (graphics, Java applets ...) are best placed as attachments of the MyFirstPlugin topic. Other needed Perl code is best placed in a lib/TWiki/Plugins/MyFirstPlugin/ directory.

The Plugin API handles the details of connecting your Perl module with main TWiki code. When you're familiar with the Plugin API, you're ready to develop Plugins.

Creating the Perl Module

Copy file lib/TWiki/Plugins/EmptyPlugin.pm to <name>Plugin.pm. The EmptyPlugin.pm module contains mostly empty functions, so it does nothing, but it's ready to be used. Customize it. Refer to the Plugin API specs for more information.

If your Plugin uses its own modules and objects, you must include the name of the Plugin in the package name. For example, write Package MyFirstPlugin::Attrs; instead of just Package Attrs;. Then call it using: 

use TWiki::Plugins::MyFirstPlugin::Attrs;
$var = MyFirstPlugin::Attrs->new();

Measuring and Improving the Plugin Performance

A high quality Plugin performs well. You can use the TWiki:Plugins.PluginBenchmarkAddOn to measure your TWiki:Plugins.PluginBenchmarks. The data is needed as part of the Documentation Topic.

See also Hints on Writing Fast Plugins.

Writing the Documentation Topic

The Plugin documentation topic contains usage instructions and version details. It serves the Plugin files as FileAttachments for downloading. (The doc topic is also included in the distribution package.) To create a documentation topic:

  1. Copy the Plugin topic template from TWiki.org. To copy the text, go to TWiki:Plugins/PluginPackage and:
    • enter the Plugin name in the "How to Create a Plugin" section
    • click Create
    • select all in the Edit box & copy
    • Cancel the edit
    • go back to your site to the TWiki web
    • In the GoBox enter your Plugin name, for example MyFirstPlugin, press enter and create the new topic
    • paste & save new Plugin topic on your site
  2. Customize your Plugin topic.
    • Important: In case you plan to publish your Plugin on TWiki.org, use Interwiki names for author names and links to TWiki.org topics, such as TWiki:Main/TWikiGuest. This is important because links should work properly in a Plugin topic installed on any TWiki, not just on TWiki.org.
  3. Document the performance data you gathered while measuring the performance
  4. Save your topic, for use in packaging and publishing your Plugin.

OUTLINE: Doc Topic Contents
Check the Plugins web on TWiki.org for the latest Plugin doc topic template. Here's a quick overview of what's covered:

Syntax Rules: <Describe any special text formatting that will be rendered.>"

Example: <Include an example of the Plugin in action. Possibly include a static HTML version of the example to compare if the installation was a success!>"

Plugin Settings: <Description and settings for custom Plugin %VARIABLES%, and those required by TWiki.>"

  • Plugins Preferences <If user settings are needed, explain... Entering values works exactly like TWikiPreferences and WebPreferences: six (6) spaces and then:>"
    • Set <EXAMPLE = value added>

Plugin Installation Instructions: <Step-by-step set-up guide, user help, whatever it takes to install and run, goes here.>"

Plugin Info: <Version, credits, history, requirements - entered in a form, displayed as a table. Both are automatically generated when you create or edit a page in the TWiki:Plugins web.>"

Packaging for Distribution

The TWiki:Plugins.BuildContrib is a powerful build environment that is used by the TWiki project to build TWiki itself, as well as many of the plugins. You don't have to use it, but it is highly recommended!

If you don't want (or can't) use the BuildContrib, then a minimum Plugin release consists of a Perl module with a WikiName that ends in Plugin, ex: MyFirstPlugin.pm, and a documentation page with the same name(MyFirstPlugin.txt).

  1. Distribute the Plugin files in a directory structure that mirrors TWiki. If your Plugin uses additional files, include them all:
    • lib/TWiki/Plugins/MyFirstPlugin.pm
    • data/TWiki/MyFirstPlugin.txt
    • pub/TWiki/MyFirstPlugin/uparrow.gif [a required graphic]
  2. Create a zip archive with the Plugin name (MyFirstPlugin.zip) and add the entire directory structure from Step 1. The archive should look like this:
    • lib/TWiki/Plugins/MyFirstPlugin.pm
    • data/TWiki/MyFirstPlugin.txt
    • pub/TWiki/MyFirstPlugin/uparrow.gif

Publishing for Public Use

You can release your tested, packaged Plugin to the TWiki community through the TWiki:Plugins web. All Plugins submitted to TWiki.org are available for download and further development in TWiki:Plugins/PluginPackage.

Publish your plugin by following these steps:

  1. Post the Plugin documentation topic in the TWiki:Plugins/PluginPackage:
    • enter the Plugin name in the "How to Create a Plugin" section, for example MyFirstPlugin
    • paste in the topic text from Writing the Documentation Topic and save
  2. Attach the distribution zip file to the topic, ex: MyFirstPlugin.zip
  3. Link from the doc page to a new, blank page named after the Plugin, and ending in Dev, ex: MyFirstPluginDev. This is the discussion page for future development. (User support for Plugins is handled in TWiki:Support.)
  4. Put the Plugin into the SVN repository, see TWiki:Plugins/ReadmeFirst (optional)

NEW 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 smile

Recommended Storage of Plugin Specific Data

Plugins sometimes need to store data. This can be Plugin internal data such as cache data, or data generated for browser consumption such as images. Plugins should store data using TWikiFuncDotPm functions that support saving and loading of topics and attachments.

Plugin Internal Data

You can create a Plugin "work area" using the 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.

Web Accessible Data

Topic specific data such as generated images can be stored in the topics attachment area, which is web accessible. Use the TWiki::Func::saveAttachment() function to store the data.

Recommendation for file name:

  • Prefix the filename with an underscore (the leading underscore avoids a nameclash with files attached to the same topic)
  • Identify where the attachment originated from, typically by including the Plugin name in the file name
  • Use only alphanumeric characters, underscores, dashes and periods to avoid platform dependency issues and URL issues
  • Example: _FooBarPlugin_img123.gif

Web specific data can be stored in the Plugin's attachment area, which is web accessible. Use the TWiki::Func::saveAttachment() function to store the data.

Recommendation for file names in Plugin attachment area:

  • Prefix the filename with an underscore
  • Include the name of the web in the filename
  • Use only alphanumeric characters, underscores, dashes and periods to avoid platform dependency issues and URL issues
  • Example: _Main_roundedge-ul.gif

Handling deprecated functions

From time-to-time, the TWiki developers will add new functions to the interface (either to TWikiFuncDotPm, or new handlers). Sometimes these improvements mean that old functions have to be deprecated to keep the code manageable.

FIXME: The following is not KISS

When this happens, the deprecated functions will be supported in the interface for at least one more TWiki release (i.e. one more after the one they are first deprecated in). When a plugin uses (or defines) the deprecated function, a warning will be generated in the TWiki warnings log. Admins who see these warnings in their logs should check TWiki.org and if necessary, contact the plugin author, for an updated version of the plugin.

Updated plugins may still need to define deprecated handlers for compatibility with old TWiki versions. In this case, the plugin package that defines old handlers can set a flag to prevent the warnings from being issued. This is done by defining a global hash that maps from the handler name to the 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.

There is no way to prevent warnings from being issued when deprecated functions in the TWikiFuncDotPm interface are called. In this case, plugins authors should be encouraged recode their plugins as described in the TWikiFuncDotPm documentation of the deprecated function.

Related Topics: DeveloperDocumentationCategory, AdminDocumentationCategory

Warning: Can't find topic TWikiNotificationOfChanges

Warning: Can't find topic RenameTopic

Warning: Can't find topic TWikiAdministration

This topic: TWiki > TWikiDocumentation
History: r26 - 30 Aug 2001 - 20:01 - MikeMannix?
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding FS? Send feedback