Note: Read the most up to date version of this document at http://TWiki.org/cgi-bin/view/TWiki/TWikiDocumentation
Related Topics: TWikiWeb?, TWikiHistory, TWikiPlannedFeatures, TWikiEnhancementRequests.
This section applies only if your TWiki is installed on a server that is both authenticated and on an intranet.
TWiki internally manages two usernames: Login username and TWiki username.
pthoeny
. This name is normally passed to TWiki by the REMOTE_USER
environment variable. TWiki uses this name internally to log topic changes. Login usernames are maintained by your system administrator.
PeterThoeny
, recorded when you register in TWikiRegistration; doing so also generates your personal home page in the Main web of your TWiki site.
TWiki can map the intranet username to the Wiki username automatically, provided that the Login username and Wiki username pair has been entered in the TWikiUsers topic. This happens automatically when you register.
NOTE: To correctly enter a WikiName - your own or someone else's - be sure to specify the Main web in front of the Wiki username: writeMain.WikiUsername
or%MAINWEB%.WikiUsername
. This assures that the name will be linked automatically to the Main web, where user home pages are stored, even if the text is entered in a different web.
-- TWiki:Main.PeterThoeny - 30 Jan 2003
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, in three areas: view; edit & attach; and rename/move/delete. Access control, combined with TWikiUserAuthentication, lets you easily create and manage an extremely flexible, fine-grained privilege system.
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 care - the more restrictions, the less Wiki in the mix. Experience shows that unrestricted write access works very well because:
As a collaboration guideline:
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.
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.
A user can create an account in TWikiRegistration. The following actions are performed:
.htpasswd
if authentication is enabled.
Users can be authenticated using Basic Authentication (htaccess) or SSL (secure server). In either case, TWikiUserAuthentication is required in order to track user identities, and use User and Group access control.
The default visitor name is TWikiGuest. This is the non-authenticated user.
Groups are defined by group topics created in the Main
web, like the TWikiAdminGroup. To create a new group:
Edit
TWikiGroups by entering a new topic with a name that ends in Group
. Example:
SomeGroup
Set GROUP = < list of Users and/or Groups >
Set ALLOWTOPICCHANGE = < list of Users and/or Groups >
Set GROUP = Main.SomeUser, Main.OtherUser, Main.SomeGroup
Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup
You can define who is allowed to make changes to a web or a topic.
Denying editing of a topic also restricts file attachment; both privileges are assigned together.
Set DENYTOPICCHANGE = < list of Users and Groups >
Set ALLOWTOPICCHANGE = < list of Users and Groups >
Set DENYTOPICCHANGE = Main.SomeBadBoy, Main.SomeBadGirl, Main.SomeHackerGroup
Set ALLOWTOPICCHANGE = Main.SomeGoodGuy, Main.SomeGoodGirl, Main.TWikiAdminGroup
Restricting web-level editing blocks creating new topics, changing topics or attaching files.
Set DENYWEBCHANGE = < list of Users and Groups >
Set ALLOWWEBCHANGE = < list of Users and Groups >
The same rules apply as for restricting topics, with these additions:
You can define who is allowed to rename, move or delete a topic, or rename a web.
To allow a user to rename, move or delete a topic, they also need write (editing) permission. They also need write access to change references in referring topics.
Set DENYTOPICRENAME = < list of Users and Groups >
Set ALLOWTOPICRENAME = < list of Users and Groups >
Set DENYTOPICRENAME = Main.SomeBadBoy, Main.SomeBadGirl, Main.SomeHackerGroup
Set ALLOWTOPICRENAME = Main.SomeGoodGuy, Main.SomeGoodGirl, Main.TWikiAdminGroup
You can define restrictions of who is allowed to rename a TWiki web.
Set DENYWEBRENAME = < list of Users and Groups >
Set ALLOWWEBRENAME = < list of Users and Groups >
The same rules apply as for topics, with these additions:
You can define who is allowed to see a web.
Technically it is possible to restrict read access to an individual topic based on
DENYTOPICVIEW
/ ALLOWTOPICVIEW
preferences variables, provided that the view script is authenticated. However this setup is not recommended since all content is searchable within a web - a search will turn up view restricted topics.
You can define restrictions of who is allowed to view a TWiki web. You can restrict access to certain webs to selected Users and Groups, by:
The idea is to keep a web hidden by not publishing its 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.
Obfuscating webs is insecure, as anyone who knows the URL can access the web.
Use the following setup to authenticate users for topic viewing in all webs and to restrict access to selected webs:
Set DENYWEBVIEW = < list of Users and Groups >
Set ALLOWWEBVIEW = < list of Users and Groups >
DENYWEBVIEW
is evaluated before ALLOWWEBVIEW
. Access is denied if the authenticated person is in the DENYWEBVIEW
list, or not in the ALLOWWEBVIEW
list. Access is granted in case DENYWEBVIEW
and ALLOWWEBVIEW
is not defined.
NOSEARCHALL
variable in its WebPreferences topic:
Set NOSEARCHALL = on
view
to the list of authenticated scripts in the .htaccess
file.
This method only works if the
view
script is authenticated, which means that all Users have to login, even for read-only access. (An open guest account, like TWikiGuest, can get around this, allowing anyone to login to a common account with, for example, view-only access for public webs.) TWikiInstallationGuide has more on Basic Authentication, using the .htaccess
file.
Use the following setup to provide unrestricted viewing access to open webs, with authentication only on selected webs:
Set DENYWEBVIEW = < list of Users and Groups >
Set ALLOWWEBVIEW = < list of Users and Groups >
DENYWEBVIEW
is evaluated before ALLOWWEBVIEW
. Access is denied if the authenticated person is in the DENYWEBVIEW
list, or not in the ALLOWWEBVIEW
list. Access is granted in case DENYWEBVIEW
and ALLOWWEBVIEW
is not defined.
NOSEARCHALL
variable in its WebPreferences topic:
Set NOSEARCHALL = on
$doRememberRemoteUser
flag in lib/TWiki.cfg
as described in TWikiUserAuthentication. TWiki will now remember the IP address of an authenticated user.
view
script to viewauth
(or better, create a symbolic link)
viewauth
to the list of authenticated scripts in the .htaccess
file. The view
script should not be listed in the .htaccess
file.
When a user accesses a web where you enabled view restriction, TWiki will redirect from the view
script to the viewauth
script once (this happens only if the user has never edited a topic). Doing so will ask for authentication. The viewauth
script shows the requested topic if the user could log on and if the user is authorized to see that web.
Authenticating webs is not very secure, as there is a way to circumvent the read access restriction. It can be useful in certain situations - for example, to simplify site organization and clutter, by hiding low traffic webs - but is not recommended for securing sensitive content.
To hide access control settings from normal browser viewing, place them in comment markers.
By mistyping a user or group name in the ALLOWTOPICCHANGE setting, it's possible to lock a topic so that no-one can edit it from a browser. To avoid this, you can create Web-based superusers:
$superAdminGroup
variable in lib/TWiki.cfg
to the name of a group of Users who are always allowed to edit/view topics.
$superAdminGroup = "TWikiAdminGroup";
-- TWiki:Main.PeterThoeny - 04 May 2002
-- TWiki:Main.MikeMannix - 12 May 2002
Definition of the templates used to render all HTML pages displayed in TWiki
The new modular template system offers flexible, easy control over the layout of all TWiki pages. The master template approach groups parts that are shared by several templates - like headers and footers - in a common file. Special variables allow individual layouts to include parts from a master template - variables are mixed with regular HTML markup for template-specific content. Templates are used to define page layout, and also to supply default content for new pages.
Where the old templates were each complete HTML documents, the new templates are defined using variables to include template parts from a master file. You can now change one instance of a common element to update all occurrences; previously, every affected template had to be updated. This simplifies the conversion of templates into XHTML format, and provides a more versatile solution for templates and for TWikiSkins. The new system:
&TWiki::Store::readTemplate()
so that the caller simply gets an expanded template file (the same as before).
%TMPL:<key>%
and %TMPL:<key>{"attr"}%
.
%TMPL:INCLUDE{"file"}%
: Includes a template file. The template directory of the current web is searched first, then the templates root (twiki/templates
).
%TMPL:DEF{"var"}%
: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
%TMPL:END%
: Ends variable definition.
%TMPL:P{"var"}%
: Prints a previously defined variable.
twiki.tmpl
master template, like twiki.print.tmpl
, that redefines the header and footer.
There are three types of template:
Common parts, appearing in two or more templates, can be defined in a master template and then shared by others: 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
TWiki uses HTML template files for 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.
Templates are stored either in the twiki/templates
directory or in user topics. As an example, twiki/templates/view.tmpl
is the template file for the twiki/bin/view
script.
Templates can be overloaded by individual webs.
TWikiSkins can overload the standard templates.
TWiki uses the following search order to determine which template to use:
If a skin is specified If no skin is specified templates/%WEB%/script.skin.tmpl
templates/%WEB%/script.tmpl
templates/script.skin.tmpl
templates/script.tmpl
data/%WEB%/SkinSkinScriptTemplate.txt
data/%WEB%/ScriptTemplate.txt
data/TWiki/SkinSkinScriptTemplate.txt
data/TWiki/ScriptTemplate.txt
Legend:
• script refers to the script name, e.gview
,edit
• Script refers to the same, but with the first character capitalized, e.gView
• skin refers to the skin name, e.gdragon
,pattern
• Skin refers to the same, but with the first character capitalized, e.gDragon
•%WEB%
refers to the current web
Additionally (and primarily for use in %TMPL:INCLUDE{}%
) the template name may be a wiki topic name, specified as Web.Topic
, in which case the search is:
If Web is not specified in the INCLUDE, it defaults to TWiki, and the search to the first type.
If a skin is specified If no skin is specified templates/web/Web.Topic.skin.tmpl
templates/web/Web.Topic.tmpl
templates/Web.Topic.skin.tmpl
templates/Web.Topic.tmpl
data/Web/Topic.txt
Special variables are used in templates, especially in view
, to display meta data.
Template topics define the default text for new topics. There are three types of template topic:
All template topics are located in the TWiki web. The WebTopicEditTemplate can be overloaded. When you create a new topic, TWiki locates a topic to use as a content template according to the following search order:
Topic Name: What it is: WebTopicViewTemplate Error page shown when you try to view a nonexistent topic WebTopicNonWikiTemplate Alert page shown when you try to view a nonexistent topic with a non-WikiName WebTopicEditTemplate Default text shown when you create a new topic.
templatetopic
CGI parameter.
The following variables get expanded when a user creates a new topic based on a template topic:
Variable: Description: %DATE%
Current date, e.g. 02 May 2025
%USERNAME%
Login name, e.g. jsmith
%WIKINAME%
WikiName of user, e.g. JohnSmith
%WIKIUSERNAME%
User name, e.g. Main.JohnSmith
%URLPARAM{"name"}%
Value of a named URL parameter %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{ ... }%
A no-operation text that gets removed. Useful to write-protect an edit template topic, but not the topics based this template topic. See notes below. Example:
%NOP{
* Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup
}%
Notes:
%NOP{ ... }%
can span multiple lines.
}%
pattern is "non-greedy", that is, it stops at the first occurance. That means, you need to escape variables with parameters located inside %NOP{ ... }%
: Insert a %NOP%
between }
and %
. Silly example: %NOP{ %GMTIME{"$year"}%NOP%% }%
.
All other variables are unchanged, e.g. are carried over "as is" into the new topic.
Here is an example for creating new topics based on a specific template topic:
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="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%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" value="Create" /> (date format is <nop>YYYYxMMxDD) </form>
The edit
scipt understands the following parameters, typically supplied by HTML input fields:
Parameter: Description: topic
Name of topic to create. Can be set in a text field, or is set programmatically (e.g. with a sequential number) onlywikiname
If set, TWiki will complain if the topic name is not a WikiWord onlynewtopic
If set, TWiki will complain if a topic of the same name already exists templatetopic
The name of the template topic, e.g. topic used to copy the initial content topicparent
Sets the parent topic TopicClassification
Assuming the template topic has a form with a field called "TopicClassification", it will set the value of the field contenttype
Optional parameter that defines the application type to write into the CGI header. Defaults to text/html
. May be used to invoke alternative client applicationsanyname
Any parameter can passed to the new topic; if the template topic contains %URLPARAM{"anyname"}%
, it will be replaced by its value
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%
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.
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%SCRIPTSUFFIX%/%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>
Each oops template basically just defines some variables and includes the base template that does the layout work.
%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"}%
With URL: .../bin/oops/Sandbox/TestTopic2?template=oopstest¶m1=WebHome¶m2=WebNotify
.tmpl
filename extension - it contained unresolved %VARIABLES%
, but could still be previewed directly in a browser.
-- TWiki:Main.CrawfordCurrie - 30 Jun 2004
-- TWiki:Main.PeterThoeny - 15 Aug 2004
-- TWiki:Main.MikeMannix - 14 Sep 2001
-- TWiki:Main.DavidLeBlanc - 11 Mar 2002
Skins overlay regular templates with alternate header/footer layouts; topic text is not affected
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.
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
.
Use the existing TWikiTemplates (like view.tmpl
) or skin files as a base for your own skin, name it for example view.myskin.tmpl
.
You can use template variables, TWikiVariables, and other predefined variables to compose your skins. Some commonly used variables in skins:
Variable: | Expanded to: |
---|---|
%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 #GoBox |
%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 %WEBTOPICLIST%
includes a "Go" box to jump to a topic. The box also understand 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:
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>
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 |
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 e.g. "1.1" |
%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 it included after twiki.tmpl, your macro definitions will override the defaults defined there.
See TWiki:Plugins/SkinPackagingHowTo and TWiki:Plugins/SkinDeveloperFAQ
You can try all installed skins in TWikiSkinBrowser.
A skin can be activated in two ways:
SKIN
Preference variable in TWikiPreferences, one of the WebPreferences, or in a user - TWikiGuest - topic.
Set SKIN = print
?skin=name
to the URL, for this example:
The ?skin=name
URL parameter overrides the SKIN Preference value.
-- TWiki:Main.PeterThoeny - 25 Jul 2004
-- TWiki:Main.CrawfordCurrie - 30 Jun 2004
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. VARIABLES
are replaced by data, either user-entered or automatically generated by TWiki (like the date, or the current username). There are predefined variables, and Preference variables that you can configure. You can also define custom variables, with new names and values.
Notes:
!%TOPIC%
to get %TOPIC%.
Most predefined variables return values that were either set in the lib/twiki.cfg
file, when TWiki was installed, or taken from server info (like current username, or date and time). Many of the variables let you format the appearance of the display results.
%INCLUDINGTOPIC%
, %INCLUDE%
, and the mighty %SEARCH%
.
This version of TWiki - 01 Sep 2004 $Rev: 1742 $ - expands the following variables (enclosed in %
percent signs):
%ATTACHURL%
http://pyqplayer.sourceforge.net/pub/TWiki/TWikiVariablesAtoM
%ATTACHURL%/image.gif
%ATTACHURLPATH%
/pub/TWiki/TWikiVariablesAtoM
%TOPIC%
if there is no INCLUDE
%BASETOPIC%
%WEB%
in case there is no include.
%BASEWEB%
%DISPLAYTIME%
02 May 2025 - 19:56
%GMTIME%
%DISPLAYTIME{"format"}%
%DISPLAYTIME{"$hou:$min"}%
expands to 19:56
%ENCODE{"string"}%
Parameter: | Description: | Default: |
---|---|---|
"string" | String to encode | required (can be empty) |
type="entity" | Encode special characters into HTML entities, like a double quote into " | URL encoding |
type="url" | Encode special characters for URL parameter use, like a double quote into %22 | (this is the default) |
%ENCODE{"spaced name"}%
expands to spaced%20name
%FORMFIELD{"fieldname"}%
Parameter: | Description: | Default: |
---|---|---|
"fieldname" | The name of a TWiki form field | required |
topic="..." | Topic where form data is located. May be of the form Web.TopicName | Current topic |
format="..." | Format string. $value expands to the field value | "$value" |
default="..." | Text shown when no value is defined for the field | "" |
alttext="..." | Text shown when field is not found in the form | "" |
%FORMFIELD{"ProjectName" topic="Projects.SushiProject" default="(not set)" alttext="ProjectName field found"}%
%GMTIME%
02 May 2025 - 19:56
%GMTIME{"format"}%
Variable: | Unit: | Example |
---|---|---|
$seconds | seconds | 59 |
$minutes | minutes | 59 |
$hours | hours | 23 |
$day | day of month | 31 |
$wday | day of the Week (Sun, Mon, Tue, Wed, Thu, Fri, Sat) | Thu |
$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 | 2025-05-02T19:56Z |
$rcs | RCS format timestamp | 2025/05/02 19:56:31 |
$http | E-mail & http format timestamp | Fri, 02 May 2025 19:56:31 GMT |
%GMTIME{"$day $month, $year - $hour:$min:$sec"}%
expands to 02 May, 2025 - 19:56:31
%HOMETOPIC%
WebHome
, renders as WebHome
%HTTP_HOST%
pyqplayer.sourceforge.net
%ICON{"type"}%
bmp
, doc
, gif
, hlp
, html
, mp3
, pdf
, ppt
, txt
, xls
, xml
, zip
%ICON{"pdf"}%
expands to %INCLUDE{"page" ...}%
Parameter: | Description: | Default: |
---|---|---|
"SomeTopic" | The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}% | |
"Web.Topic" | A topic in another web, i.e. %INCLUDE{"TWiki.SiteMap"}% | |
"http://..." | A full qualified URL, i.e. %INCLUDE{"http://twiki.org/"}% Note 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="1.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) | %INCLUDE- WARNING% preferences setting |
%TOPIC%
in case there is no include
%INCLUDINGTOPIC%
%WEB%
if there is no INCLUDE.
%INCLUDINGWEB%
%MAINWEB%
Main
%METASEARCH{...}%
Parameter: | Description: | Default: |
---|---|---|
type="topicmoved" | What sort of search is required? "topicmoved" if search for a topic that may have been moved "parent" if searching for topics that have a specific parent i.e. its children | 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 | current topic |
title="Title" | Text that is prefixed to any search results | empty |
default="none" | Default text shown if no search hit | empty |
%METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%
%METASEARCH{type="parent" web="%WEB%" topic="%TOPIC%" title="Children: "}%
%NOTIFYTOPIC%
WebNotify
, renders as WebNotify
$TWiki::Plugins::VERSION
number, also indicating the version of the TWikiFuncModule
%PLUGINVERSION{}%
1.025
%PLUGINVERSION{"name"}%
%PLUGINVERSION{"DefaultPlugin"}%
expands to 1.021
%PUBURL%
http://pyqplayer.sourceforge.net/pub
%PUBURL%/%WEB%/OtherTopic/image.gif
%PUBURLPATH%
/pub
%REMOTE_ADDR%
127.0.0.1
%REMOTE_PORT%
49358
%REMOTE_USER%
%REVINFO%
r1.1 - 14 Aug 2004 - 08:01 - TWikiGuest
%REVINFO{"format"}%
Parameter: | Description: | Default: |
---|---|---|
"format" | Format of revision information, see supported variables below | "r1.$rev - $date - $wikiusername" |
web="..." | Name of web | Current web |
topic="..." | Topic name | Current topic |
rev="1.5" | Specific revison number | Latest revision |
Variable: | Unit: | Example |
---|---|---|
$web | Name of web | Current web |
$topic | Topic name | Current topic |
$rev | Revison number. Prefix r1. to get the usual r1.5 format | 5 |
$date | Revision date | 11 Jul 2004 |
$username | Login username of revision | jsmith |
$wikiname | WikiName of revision | JohnSmith |
$wikiusername | WikiName with Main web prefix | Main.JohnSmith |
%REVINFO{"$date - $wikiusername" rev="1.1"}%
returns revision info of first revision
%SCRIPTURL%
http://pyqplayer.sourceforge.net/cgi-bin/bin
%SCRIPTURL%/viewauth%SCRIPTSUFFIX%/%WEB%/%TOPIC%
which expands to http://pyqplayer.sourceforge.net/cgi-bin/bin/viewauth/TWiki/TWikiVariablesNtoZ
%SCRIPTURLPATH%
/cgi-bin/bin
.pl
or .cgi
%SCRIPTSUFFIX%
%SEARCH{"text" ...}%
Parameter: | Description: | Default: |
---|---|---|
"text" | Search term. Is a keyword search, literal search or regular expression search, depending on the type parameter. SearchHelp has more | required |
search="text" | (Alternative to above) | N/A |
web="Name" web="Main, Know" web="all" | Wiki web to search: A web, a list of webs separated by comma, or all webs. [2] | Current web |
topic="WebPreferences" topic="*Bug" | Limit search to topics: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. | All topics in a web |
excludetopic="Web*" excludetopic="WebHome, WebChanges" | Exclude topics from search: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. | None |
type="keyword" type="literal" type="regex" | Do a keyword search like soap "web service" -shampoo ; a literal search like web service ; or RegularExpression search like soap;web service;!shampoo | %SEARCHVAR- DEFAULTTYPE% preferences setting (literal) |
scope="topic" scope="text" scope="all" | Search topic name (title); the text (body) of topic; or all (both) | "text" |
order="topic" order="created" order="modified" order="editby" order= | Sort the results of search by the topic names, topic creation time, last modified time, last editor, or named field of TWikiForms. The sorting is done web by web; in case you want to sort across webs, create a formatted table and sort it with TablePlugin's initsort | Sort by topic name |
limit="all" limit="16" | Limit the number of results returned. This is done after sorting if order is specified | All results |
reverse="on" | Reverse the direction of the search | Ascending search |
casesensitive="on" | Case sensitive search | Ignore case |
nosummary="on" | Show topic title only | Show topic summary |
bookview="on" | BookView search, e.g. show complete topic text | Show topic summary |
nosearch="on" | Suppress search string | Show search string |
noheader="on" | Suppress search header Topics: Changed: By: | Show search header |
nototal="on" | Do not show number of topics found | Show number |
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 |
separator=", " | Line separator between hits | Newline "$n" |
%SEARCH{"wiki" web="Main" scope="topic"}%
%SEARCH{"FAQ" scope="topic" nosearch="on" nototal="on" header="| *Topic: * | *Summary: * |" format="| $topic | $summary |"%
(displays results in a table with header - details)
%TABLE{}%
variable just before the %SEARCH{}%
to alter the output of a search. Example: %TABLE{ tablewidth="90%" }%
web="all"
search if you define a NOSEARCHALL=on
variable in its WebPreferences
%SERVERTIME%
02 May 2025 - 19:56
%GMTIME%
%SERVERTIME{"format"}%
%SERVERTIME{"$hou:$min"}%
expands to 19:56
%SPACEDTOPIC%
TWiki%20*Variables%20*Nto%20*Z
%STOPINCLUDE%
variable. A normal view of the topic shows everyting exept the %STARTINCLUDE%
variable itself.
%STARTINCLUDE%
%STATISTICSTOPIC%
WebStatistics
, renders as WebStatistics
%STOPINCLUDE%
variable itself.
%STOPINCLUDE%
%TOC%
%TOC{"SomeTopic" ...}%
"---++ 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
Parameter: | Description: | Default: |
---|---|---|
"TopicName" | topic name | Current topic |
web="Name" | Name of web | Current web |
depth="2" | Limit depth of headings shown in TOC | 6 |
title="Some text" | Title to appear at top of TOC | none |
%TOC{depth="2"}%
%TOC{"TWikiDocumentation" web="TWiki" title="Contents:"}%
%TOPIC%
TWikiVariablesNtoZ
, renders as TWikiVariablesNtoZ
$name
variable gets expanded to the topic name; the $web
variable gets expanded to the name of the web.
%TOPICLIST{"format" ...}%
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 |
%TOPICLIST{" * $web.$name"}%
creates a bullet list of all topics
%TOPICLIST{separator=", "}%
creates a comma separated list of all topics
%TOPICLIST{" <option>$name</option>"}%
creates an option list (for drop down menus)
%TWIKIWEB%
TWiki
%URLPARAM{"name"}%
Parameter: | Description: | Default: |
---|---|---|
"name" | The name of a URL parameter | required |
default="..." | Default value in case parameter is empty or missing | empty string |
newline="<br />" | Convert newlines in textarea to other delimiters | no conversion |
encode="entity" | Encode special characters into HTML entities, like a double quote into " . 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) |
%URLPARAM{"skin"}%
returns print
for a .../view/TWiki/TWikiVariablesNtoZ?skin=print
URL. Test this:
jsmith
, WIKINAME like JohnSmith
and WIKIUSERNAME like Main.JohnSmith
. A user is a TWikiGuest in case the topic is not authenticated
%USERNAME%
guest
%VAR{"NAME" web="Web"}%
%WEBBGCOLOR%
of the Main web write %VAR{"WEBBGCOLOR" web="Main"}%
, which expands to #FFEFA6
%WEB%
TWiki
NOSEARCHALL=on
preference variable. The "format"
defines the format of one web item. The $name
variable gets expanded to the name of the web, $qname
gets expanded to double quoted name, $marker
to marker
where web matches selection
.
%WEBLIST{"format" ...}%
Parameter: | Description: | Default: |
---|---|---|
"format" | Format of one line, may include $name variable | "$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%" |
%WEBLIST{" * [[$name.WebHome]]"}%
creates a bullet list of all webs.
%WEBLIST{"<option $marker value=$qname>$name</option>" webs="Trash,public" selection="TWiki" separator=" "}%
Dropdown of all public Webs + Trash Web, current Web highlighted.
%WEBPREFSTOPIC%
WebPreferences
, renders as WebPreferences
%WIKIHOMEURL%
http://your.domain.com/twiki
%WIKINAME%
TWikiGuest
%WIKIPREFSTOPIC%
TWikiPreferences
, renders as TWikiPreferences
%WIKITOOLNAME%
TWiki
%WIKIUSERNAME%
Main.TWikiGuest
, renders as TWikiGuest
%WIKIUSERSTOPIC%
TWikiUsers
, with Main prefix renders as TWikiUsers
%WIKIVERSION%
01 Sep 2004 $Rev: 1742 $
Note: Above text is included from TWikiVariablesAtoM and TWikiVariablesNtoZ
Additional variables are defined in the preferences topics:
Variable: | Level: | What: | Expands to: | ||
---|---|---|---|---|---|
%ALLOWTOPICCHANGE% |
(any topic) | List of users and groups who are allowed to change the current topic. (More in TWikiAccessControl) | |||
%ALLOWTOPICRENAME% |
(any topic) | List of users and groups who are allowed to rename the current topic. (More in TWikiAccessControl) | TWikiAdminGroup | ||
%ALLOWWEBCHANGE% |
WL | List of users and groups who are allowed to change topics in the TWiki web. (More in TWikiAccessControl) | |||
%ALLOWWEBRENAME% |
WL | List of users and groups who are allowed to rename topics in the TWiki web. (More in TWikiAccessControl) | |||
%ATTACHLINKBOX% |
SL , UL | Default state of the link check box in the attach file page. Check box is initially checked if value is set to CHECKED , unchecked if empty. If checked, a link is created to the attached file at the end of the topic. Value is: |
|||
%DENYTOPICCHANGE% |
(any topic) | List of users and groups who are not allowed to change the current topic. (More in TWikiAccessControl) | %DENYTOPICCHANGE% | ||
%DENYTOPICRENAME% |
(any topic) | List of users and groups who are not allowed to rename the current topic. (More in TWikiAccessControl) | %DENYTOPICRENAME% | ||
%DENYWEBCHANGE% |
WL | List of users and groups who are not allowed to change topics in the TWiki web. (More in TWikiAccessControl) | |||
%DENYWEBRENAME% |
WL | List of users and groups who are not allowed to rename topics in the TWiki web. (More in TWikiAccessControl) | |||
%DONTNOTIFYCHECKBOX% |
SL , UL | Default state of the "Minor Changes, Don't Notify" (DontNotify) check box in preview. Check box is initially checked if Set DONTNOTIFYCHECKBOX = checked="checked" , or unchecked if empty. Value is: |
|||
%EDITBOXHEIGHT% |
SL , UL | Vertical size of edit box, is 17 |
17 | ||
%EDITBOXWIDTH% |
SL , UL | Horizontal size of edit box, is 70 |
70 | ||
%EDITBOXSTYLE% |
SL , UL | Style of text edit box. Set to width: 99% for full window width (default; overwrites the EDITBOXWIDTH setting), or width: auto to disable. Value is: width: 99% |
width: 99% | ||
%FINALPREFERENCES% |
SL , WL | List of preferences that are not allowed to be overridden by next level preferences | ATTACHFILESIZELIMIT, PREVIEWBGIMAGE, WIKITOOLNAME, WIKIWEBMASTER, SMTPMAILHOST, SMTPSENDERHOST, ALLOWWEBMANAGE, READTOPICPREFS, TOPICOVERRIDESUSER, NOSEARCHALL, ATTACHFILESIZELIMIT, WIKIWEBMASTER, WEBCOPYRIGHT, WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, DENYWEBRENAME, ALLOWWEBRENAME | ||
%HTTP_EQUIV_ON_EDIT% |
SL , UL | http-equiv meta tags for edit script. | |||
%HTTP_EQUIV_ON_PREVIEW% |
SL , UL | http-equiv meta tags for preview script. | |||
%HTTP_EQUIV_ON_VIEW% |
SL | http-equiv meta tags for view, rdiff, attach, search* scripts. | |||
%NEWTOPICBGCOLOR% |
SL , UL | Background color of non existing topic. ( UL needs authentication for topic views ) | #FFFFCE | ||
%NEWTOPICFONTCOLOR% |
SL , UL | Font color of non existing topic. ( UL needs authentication for topic views ) | #0000FF | ||
%NOSEARCHALL% |
WL | Exclude web from a web="all" search (set variable to on for hidden webs) |
|||
%RELEASEEDITLOCKCHECKBOX% |
SL , UL | Default state of the "Release edit lock" (UnlockTopic) check box in preview. Checkbox is initially checked if Set RELEASEEDITLOCKCHECKBOX = checked="checked" , or unchecked if empty. If checked, make sure to click on Edit to do more changes; do not go back in your browser to the edit page, or you risk that someone else will edit the topic at the same time! Value is: |
|||
%WEBBGCOLOR% |
WL | Background color of web | #FFD8AA | ||
%WEBCOPYRIGHT% |
SL , WL | Copyright notice (bottom right corner of topics) | Copyright © 1999-2025 by the contributing authors.
All material on this collaboration platform is the property of the contributing authors. Ideas, requests, problems regarding TWiki? Send feedback
|
||
%WEBTOPICLIST% |
WL | Common links of web (second line of topics) | Welcome | Register | Changes | Topics | Index | Search | Go | ||
%WIKIWEBLIST% |
SL | List of TWiki webs (in upper right corner of topics) | Main | TWiki | Sandbox | ||
%WIKIWEBMASTER% |
SL | Webmaster email address (sender of email notifications) , is dkessler@operamail.com | dkessler@operamail.com |
Note: There are some more useful variables defined in the TWikiPreferences like %BR%
for line break, colors like %RED%
for colored text and small icons like %H%
for a Help icon.
Set VARIABLENAME = value
Set VARIABLENAME = value
Example: Create a custom logo variable the TWiki web
- 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
:
Set MYLOGO = %PUBURL%/TWiki/LogoTopic/mylogo.gif
-- TWiki:Main.PeterThoeny - 14 Aug 2004
-- TWiki:Main.MikeMannix - 12 May 2002
Plug-in enhanced feature add-ons, with a Plugin API for developers
You can add Plugins to extend TWiki's functionality, without altering the core program code. A plug-in approach lets you:
Everything to do with TWiki Plugins - demos, new releases, downloads, development, general discussion - is available at TWiki.org, in the TWiki:Plugins web.
TWiki comes with a set of Plugins as part of the standard installation.
TWiki:Plugins
expands to TWiki:Plugins on TWiki.org. You can edit the predefined set of of Wiki-related sites, and add your own
:-)
for :cool:
for "$SUM( $ABOVE() )"
to tables located in TWiki topics.
Each TWikiPlugin comes with full documentation: step-by-step installation instructions, a detailed description of any special requirements, version details, and a working example for testing.
Most Plugins can be installed in three easy steps, with no programming skills required:
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. In these cases, detailed instructions are in the Plugin documentation.
Each Plugin has a standard release page, located in the TWiki:Plugins web at TWiki.org. In addition to the documentation topic (SomePlugin
), there's a separate development page.
Dev
(SomePluginDev
).
To test new Plugins on your installation before making them public, you may want to use one of these two approaches:
twiki/bin
and twiki/lib
directories for the Test version, and adjust the paths in the new lib/TWiki.cfg
. The following directories are shared: twiki/data
, twiki/templates
and twiki/pub
.
DISABLEDPLUGINS
variable in TWikiPreferences. Redefine the DISABLEDPLUGINS
variable in the Sandbox
web and do the testing there.
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 performance of the system depends on the number of Plugins installed and on the Plugin implementation. Some Plugins impose no measurable performance decrease, some do. For example, outsidePREHandler
is an expensive callback function, or a Plugin might use many Perl libraries that need to be initialized with each page view (unless you run mod_perl). It is recommended to measure the performance with and without a new Plugin. Example for Unix:
time wget -qO /dev/null http://pyqplayer.sourceforge.net/cgi-bin/bin/view/TWiki/AbcPlugin
In case 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.)
When you finish installing a Plugin, you should be able to read the user instructions and go. In fact, 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.
Installed Plugins can be toggled on or off, site-wide or by web, through TWikiPreferences and individual WebPreferences:
lib/TWiki/Plugins
directory are activated automatically unless disabled by the DISABLEDPLUGINS
Preferences variable in TWikiPreferences. You can optionally list the installed Plugins in the INSTALLEDPLUGINS
Preferences variable. This is useful to define the sequence of Plugin execution, or to specify other webs than the TWiki web for the Plugin topics. Settings in TWikiPreferences are:
Set INSTALLEDPLUGINS = DefaultPlugin, ...
Set DISABLEDPLUGINS = EmptyPlugin, ...
Plugin execution order in TWiki is determined by searching Plugin topics in a specific sequence: First, full web.topicname
name, if specified in INSTALLEDPLUGINS
; next, the TWiki web is searched; and finally, the current web.
Plugin-specific settings are done in individual Plugin topics. Two settings are standard for each Plugin:
Set SHORTDESCRIPTION = Blah blah woof woof.
data/debug.txt
. Set to 0=off or 1=on:
Set DEBUG = 0
%<pluginname>_<var>%
, ex: %DEFAULTPLUGIN_SHORTDESCRIPTION%
shows the description of the DefaultPlugin.
Plugin status variables let you list all active Plugins wherever needed. There are two list formats:
%ACTIVATEDPLUGINS%
variable lists activated Plugins by name. (This variable is displayed in TWikiPreferences for debugging use.)
%PLUGINDESCRIPTIONS%
variable displays a bullet list with a one-line description of each active Plugins. This variable is based on the %<plugin>_SHORTDESCRIPTION%
Preferences variables of individual topics and is shown in TextFormattingRules.
DEMO: Automatically List Active Plugins Using VariablesUsing
%ACTIVATEDPLUGINS%
:
On this TWiki site, the active Plugins are: DefaultPlugin, SpreadSheetPlugin, CommentPlugin, EditTablePlugin, InterwikiPlugin, RenderListPlugin, SlideShowPlugin, SmiliesPlugin, TablePlugin.Using
%
:PLUGINDESCRIPTIONS%
You can use any of these active TWiki Plugins:
- DefaultPlugin: This plugin can be used to specify some simple custom rendering rules. It also renders depreciated
*_text_*
as bold italic text.- SpreadSheetPlugin: Add spreadsheet calculation like
"$SUM( $ABOVE() )"
to tables located in TWiki topics.- CommentPlugin: Allows users to quickly post comments to a page without an edit/preview/save cycle.
- EditTablePlugin: Edit TWiki tables using edit fields, date pickers and drop down boxes
- InterwikiPlugin: Link
ExternalSite:Page
text to external sites based on aliases defined in the InterWikis topic- RenderListPlugin: Render bullet lists in a variety of formats
- SlideShowPlugin: Create web based presentations based on topics with headings.
- SmiliesPlugin: Render smilies as icons, like
:-)
foror
:cool:
for![]()
- TablePlugin: Control attributes of tables and sorting of table columns
The Application Programming Interface (API) for TWikiPlugins provides the specifications for hooking into the core TWiki code from your external Perl Plugin module. The Plugin API is new to the Production version of TWiki with the 01-Sep-2001 release.
The TWikiFuncModule (lib/TWiki/Func.pm
) implements ALL official Plugin functions. Plugins should ONLY use functions published in this module.
If you use functions not 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.
In addition to TWiki core functions, Plugins can use predefined hooks, or call backs, listed in the lib/TWiki/Plugins/EmptyPlugin.pm
module.
DISABLE_
from the function name.
outsidePREHandler
and insidePREHandler
are particularly expensive.
Most Plugins use either the commonTagsHandler
or startRenderingHandler
for rendering tasks:
commonTagsHandler:
Use it to expand %XYZPLUGIN%
and %XYZPLUGIN{...}%
variables
startRenderingHandler:
Use it for your own rendering rules or to overload TWiki's internal rendering like [[links]]
TWiki:Codev/StepByStepRenderingOrder helps you decide which rendering handler to use.
eval
block like:eval { require IPC::Run }
return "<font color=\"red\">SamplePlugin: Can't load required modules ($@)</font>" if $@;
To eliminate the incompatibility problems bound to arise from active open Plugin development, a Plugin versioning system is provided for automatic compatibility checking.
$VERSION='0.000'
variable, beginning at 1.000
.
initPlugin
handler should check all dependencies and return TRUE if the initialization is OK or FALSE if something went wrong.
initPlugin
handler).
$TWiki::Plugins::VERSION
in the TWiki::Plugins
module contains the TWiki Plugin API version, currently 1.025.
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.
A basic TWiki Plugin consists of two elements:
MyFirstPlugin.pm
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.
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();
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:
MyFirstPlugin
, press enter and create the new topic
OUTLINE: Doc Topic Contents
Check the Plugins web on TWiki.org for the latest Plugin doc topic template. Here's a quick overview of what's covered:Syntax Rules: <Describe any special text formatting that will be rendered.>"
Example: <Include an example of the Plugin in action. Possibly include a static HTML version of the example to compare if the installation was a success!>"
Plugin Settings: <Description and settings for custom Plugin %VARIABLES%, and those required by TWiki.>"
- 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.>"
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
).
lib/TWiki/Plugins/MyFirstPlugin.pm
data/TWiki/MyFirstPlugin.txt
pub/TWiki/MyFirstPlugin/uparrow.gif
[a required graphic]
MyFirstPlugin.zip
) and add the entire directory structure from Step 1. The archive should look like this:
lib/TWiki/Plugins/MyFirstPlugin.pm
data/TWiki/MyFirstPlugin.txt
pub/TWiki/MyFirstPlugin/uparrow.gif
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 in these steps:
MyFirstPlugin
MyFirstPlugin.zip
Dev
, ex: MyFirstPluginDev
. This is the discussion page for future development. (User support for Plugins is handled in TWiki:Support.)
Thank you very much for sharing your Plugin with the TWiki community
Plugins sometimes need to store data. This can be Plugin internal data like cache data, or generated data for the browser like images. The following is a recommendation where to store the data.
In case the Plugin generates data just for internal use, or data which is not specific to a topic, store it in the Plugin's attachment directory.
pubdir/Installweb/FooBarPlugin
Installweb
refers to the name of the web where the Plugin is installed
%PUBURL%/Installweb/FooBarPlugin
_any_name.ext
getPubDir()
to get the attachment root directory
getUrlHost()
and getPubUrlPath()
to build the URL in case you create content for the browser
$installWeb
to get the name of the web where the Plugin is installed
In case the Plugin generates data which is specific to a topic, store it in the topic's attachment directory.
pubdir/Webname/TopicName
%PUBURL%/Webname/TopicName
_FooBarPlugin_any_name.ext
getPubDir()
to get the attachment root directory
getUrlHost()
and getPubUrlPath()
to build the URL in case you create content for the browser
Example code to build the file name:
sub _make_filename { my ( $web, $topic, $name ) = @_; # Create web directory "pub/$web" if needed my $dir = TWiki::Func::getPubDir() . "/$web"; unless( -e "$dir" ) { umask( 002 ); mkdir( $dir, 0775 ); } # Create topic directory "pub/$web/$topic" if needed $dir .= "/$topic"; unless( -e "$dir" ) { umask( 002 ); mkdir( $dir, 0775 ); } return "$dir/_FooBarPlugin_$name"; }
-- TWiki:Main/PeterThoeny - 14 Aug 2004
-- TWiki:Main/AndreaSterbini - 29 May 2001
-- TWiki:Main/MikeMannix - 03 Dec 2001
Project hosting provided by: | Donations welcome:![]() |