Authentication vs. Access ControlAuthentication: 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 GroupsAccess 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 UsersA user can create an account in TWikiRegistration. The following actions are performed:
Managing GroupsThe following describes the standard TWiki support for groups. Your local TWiki may have an alternate group mapping manager installed. Check with your TWiki administrator if you are in doubt. Groups are defined by group topics located in theMain web. To create a new group, visit TWikiGroups and enter the name of the new group ending in Group into the "new group" form field. This will create a new group topic with two important settings:
![]() The Super Admin GroupA number of TWiki functions (for example, renaming webs) are only available to administrators. Administrators are simply users who belong to the SuperAdminGroup. This is a standard user group, the name of which is defined by {SuperAdminGroup} setting in configure. The default name of this group is theTWikiAdminGroup . The system administrator may have chosen a different name for this group if your local TWiki uses an alternate group mapping manager but for simplicity we will use the default name TWikiAdminGroup in the rest of this topic.
You can create new administrators simply by adding them to the TWikiAdminGroup topic. For example,
Restricting AccessYou can define who is allowed to read or write to a web or a topic. Note that some plugins may not respect access permissions.
Controlling access to a WebYou can define restrictions on who is allowed to view a TWiki web. You can restrict access to certain webs to selected Users and Groups, by:
ALLOWWEBVIEW set, this will also apply to the subweb.
Creation and renaming of sub-webs is controlled by the WEBCHANGE setting on the parent web (or ROOTCHANGE for root webs). Renaming is additionally restricted by the setting of WEBRENAME in the web itself.
Note: For Web level access rights Setting any of these settings to an empty value has the same effect as not setting them at all. Please note that the documentation of TWiki 4.0 and earlier versions of TWiki 4.1 did not reflect the actual implementation, e.g. an empty ALLOWWEBVIEW does not prevent anyone from viewing the web, and an an empty DENYWEBVIEW does not allow all to view the web.
Controlling access to a Topic
![]() Controlling access to AttachmentsAttachments 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 Apachemod_rewrite module, and configure your webserver to redirect accesses to attachments to the TWiki viewfile script. For example,
ScriptAlias /twiki/bin/ /filesystem/path/to/twiki/bin/ Alias /twiki/pub/ /filesystem/path/to/twiki/pub/ RewriteEngine on RewriteCond %{REQUEST_URI} !^/+twiki/+pub/+TWiki/+.+ RewriteRule ^/+twiki/+pub/+([^/]+)/+((([^/]+)/+)+)(.+) /twiki/bin/viewfile/$1/$4?filename=$5 [L,PT]That way all the controls that apply to the topic also apply to attachments to the topic. Other types of webserver have similar support. Note: Images embedded in topics will load much slower since each image will be delivered by the viewfile script.
Controlling who can manage top-level websTop level webs are a special case, because they don't have a parent web with a WebPreferences. So there has to be a special control just for the root level.
ROOTCHANGE access to rename an existing top-level web. You just need WEBCHANGE in the web itself.
How TWiki evaluates ALLOW/DENY settingsWhen 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.
Access Control quick recipesObfuscating WebsAnother way of hiding webs is to keep them hidden by not publishing the URL and by preventing theall webs search option from accessing obfuscated webs. Do so by enabling the NOSEARCHALL variable in WebPreferences:
![]() Authenticate all Webs and Restrict Selected WebsUse the following setup to authenticate users for topic viewing in all webs and to restrict access to selected webs. Requires TWikiUserAuthentication to be enabled.
Authenticate and Restrict Selected Webs OnlyUse the following setup to provide unrestricted viewing access to open webs, with authentication only on selected webs. Requires TWikiUserAuthentication to be enabled.
Hide Control Settings![]()
TWiki Text FormattingWorking in TWiki is as easy as typing in text. You don't need to know HTML, though you can use it if you prefer. Links to topics are created automatically when you enter WikiWords. And TWiki shorthand gives you all the power of HTML with a simple coding system that takes no time to learn. It's all laid out below.TWiki Editing Shorthand
Using HTMLYou can use just about any HTML tag without a problem. You can add HTML if there is no TWiki equivalent, for example, write<strike>deleted text</strike> to get ![]()
![]() Script tagsYou can use HTML<script> tags for your TWiki applications. However note that your TWiki administrator can disable <script> in topics, and may have chosen to do so for security considerations. TWiki markup and TWikiVariables are not expanded inside script tags.
HyperlinksBeing able to create links without any special formatting is a core TWiki feature, made possible with WikiWords and inline URLs.Internal Links
External Links
TWiki VariablesTWiki Variables are names that are enclosed in percent signs% that are expanded on the fly. Some variables take arguments, such as %INCLUDE% . For those variables, the arguments are included in curly braces ({ and }).
%ICON{"help"}% , %ICON{"tip"}% , and %ICON{"warning"}% to get: ![]() ![]() ![]() ![]() !%SOMEVARIABLE% to get: %SOMEVARIABLE%.
TWikiPlugin Formatting ExtensionsPlugins can extend the functionality of TWiki into many other areas. There are a huge number of TWiki plugins available from the Plugins web on TWiki.org. Currently enabled plugins on this TWiki installation, as listed by%PLUGINDESCRIPTIONS% :
Common Editing ErrorsTWiki formatting rules are fairly simple to use and quick to type. However, there are some things to watch out for, taken from the TextFormattingFAQ:
TWiki VariablesSpecial text strings expand on the fly to display user data or system info TWikiVariables are text strings -%VARIABLE% or %VARIABLE{ parameter="value" }% - that expand into content whenever a topic is rendered for viewing. There are two types of variables:
Using VariablesTo use a variable type its name. For example,
Variable NamesVariable names must start with a letter. The following characters can be letters, numbers and the underscore '_'. You can use both upper-case and lower-case letters and you can mix the characteres. E.g.%MYVAR% , %MyVar% , %My2ndVar% , and %My_Var% are all valid variable names. Variables are case sensitive. %MyVAR% and %MYVAR% are not the same variable.
By convention all settings, predefined variables and variables used by plugins are always UPPER-CASE.
Preferences VariablesUnlike predefined variables, preferences variables can be defined by the user in various places.Setting Preferences VariablesYou can set variables in all the following places:
[multiple of 3 spaces] * [space] Set [space] VARIABLENAME [space] = [space] value
Examples:Spaces between the = sign and the value will be ignored. You can split a value over several lines by indenting following lines with spaces - as long as you don't try to use * as the first character on the following line. Example:Whatever you include in your Variable will be expanded on display, exactly as if it had been entered directly.* Set VARIABLENAME = value starts here and continues here Example: Create a custom logo variableYou can also set preferences variables on a topic by clicking the link 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 VariablesThese are special types of preferences variables to control access to content. TWikiAccessControl explains these security settings in detail.Local values for variablesCertain 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 usingLocal in place of Set in the variable definition. For example, if the user sets the following in their home topic:
* Set EDITBOXHEIGHT = 10 * Local EDITBOXHEIGHT = 20Then when they are editing any other topic, they will get a 10 high edit box. However when they are editing their home topic, they will get a 20 high edit box. Local can be used wherever a preference needs to take a different value depending on where the current operation is being performed.
Use this powerful feature with great care! %ALLVARIABLES% can be used to get a listing of the values of all variables in their evaluation order, so you can see variable scope if you get confused.
Frequently Used Preferences VariablesThe following preferences variables are frequently used. They are defined in TWikiPreferences#Miscellaneous_Settings:
Predefined VariablesMost predefined variables return values that were either set in the configuration when TWiki was installed, or taken from server info (such as current username, or date and time). Some, like%SEARCH% , are powerful and general tools.
ACTIVATEDPLUGINS -- list of currently activated plugins
ALLVARIABLES -- list of currently defined TWikiVariables
AQUA -- start aqua colored text
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
BASEWEB -- base web where an INCLUDE started
BB -- bullet with line break
BB2 -- level 2 bullet with line break
BB3 -- level 3 bullet with line break
BB4 -- level 4 bullet with line break
BLACK -- start black colored text
BLUE -- start blue colored text
BR -- line break
BROWN -- start brown colored text
BULLET -- bullet character
DATE -- signature format date
DISPLAYTIME -- display time
DISPLAYTIME{"format"} -- formatted display time
ENCODE{"string"} -- encodes a string to HTML entities
ENDCOLOR -- end colored text
ENDSECTION{"name"} -- marks the end of a named section within a topic
FAILEDPLUGINS -- debugging for plugins that failed to load, and handler list
FORMFIELD{"fieldname"} -- renders a field in the form attached to some topic
GMTIME -- GM time
GMTIME{"format"} -- formatted GM time
GRAY -- start gray colored text
GREEN -- start green colored text
GROUPS -- a formatted list of groups
H -- help icon
HOMETOPIC -- home topic in each web
HTTP -- get HTTP headers
HTTP_HOST -- environment variable
HTTPS -- get HTTPS headers
I -- idea icon
ICON{"name"} -- small documentation graphic or icon of common attachment types
ICONURL{"name"} -- URL of small documentation graphic or icon
ICONURLPATH{"name"} -- URL path of small documentation graphic or icon
IF{"condition" ...} -- simple conditionals
INCLUDE{"page"} -- include other topic or web page
INCLUDINGTOPIC -- name of topic that includes current topic
INCLUDINGWEB -- web that includes current topic
LANGUAGE -- current user's language
LANGUAGES -- list available TWiki languages
LIME -- start lime colored text
LOCALSITEPREFS -- web.topicname of site preferences topic
LOGIN -- present a full login link
LOGOUT -- present a full logout link
M -- moved to... icon
MAINWEB -- name of Main web
MAKETEXT -- creates text using TWiki's I18N infrastructure
MAROON -- start maroon colored text
META -- displays meta-data
METASEARCH -- special search of meta data
N -- "new" icon
NAVY -- start navy blue colored text
NOP -- template text not to be expanded in instantiated topics
NOTIFYTOPIC -- name of the notify topic
OLIVE -- start olive green colored text
ORANGE -- start orange colored text
P -- pencil icon
PINK -- start pink colored text
PLUGINDESCRIPTIONS -- list of plugin descriptions
PLUGINVERSION -- the version of a TWiki Plugin, or the TWiki Plugins API
PUBURL -- the base URL of attachments
PUBURLPATH -- the base URL path of attachments
PURPLE -- start purple colored text
Q -- question icon
QUERYPARAMS -- show paramaters to the query
QUERYSTRING -- full, unprocessed string of parameters to this URL
RED -- start red colored text
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
S -- red star icon
SCRIPTNAME -- name of current script
SCRIPTSUFFIX -- script suffix
SCRIPTURL -- base URL of TWiki scripts
SCRIPTURL{"script"} -- URL of TWiki script
SCRIPTURLPATH -- base URL path of TWiki scripts
SCRIPTURLPATH{"script"} -- URL path of TWiki script
SEARCH{"text"} -- search content
SERVERTIME -- server time
SERVERTIME{"format"} -- formatted server time
SESSIONID -- unique ID for this session
SESSIONVAR -- name of CGI and session variable that stores the session ID
SESSION_VARIABLE -- get, set or clear a session variable
SILVER -- start silver colored text
SPACEDTOPIC -- topic name, spaced and URL-encoded deprecated
SPACEOUT{"string"} -- renders string with spaces inserted in sensible places
STARTINCLUDE -- start position of topic text if included
STARTSECTION -- marks the start of a section within a topic
STATISTICSTOPIC -- name of statistics topic
STOPINCLUDE -- end position of topic text if included
T -- tip icon
TEAL -- start teal colored text
TOC -- table of contents of current topic
TOC{"Topic"} -- table of contents
TOPIC -- name of current topic
TOPICLIST{"format"} -- topic index of a web
TOPICURL -- shortcut to viewing the current topic
TWIKIWEB -- name of TWiki documentation web
U -- "updated" icon
URLPARAM{"name"} -- get value of a URL parameter
USERINFO{"WikiName"} -- retrieve details about a user
USERNAME -- your login username
VAR{"NAME" web="Web"} -- get a preference value from another web
VBAR -- vertical bar
VOTE{ attributes } -- define a poll in a TWiki topic.
WEB -- name of current web
WEBLIST{"format"} -- index of all webs
WEBPREFSTOPIC -- name of web preferences topic
WHITE -- start white colored text
WIKIHOMEURL -- site home URL
WIKINAME -- your Wiki username
WIKIPREFSTOPIC -- name of site-wide preferences topic
WIKITOOLNAME -- name of your TWiki site
WIKIUSERNAME -- your Wiki username with web prefix
WIKIUSERSTOPIC -- name of topic listing all registers users
WIKIVERSION -- the version of the installed TWiki engine
X -- warning icon
Y -- "yes" icon
YELLOW -- start yellow colored text
TWiki Formatted SearchInline search feature allows flexible formatting of search result The default output format of a%SEARCH{...}% is a table consisting of topic names and topic summaries. Use the format="..." parameter to customize the search result. The format parameter typically defines a bullet or a table row containing variables, such as %SEARCH{ "food" format="| $topic | $summary |" }% . See %SEARCH{...}% for other search parameters, such as separator="" .
SyntaxTwo parameters can be used to specify a customized search result: 1.
Use the header parameter to specify the header of a search result. It should correspond to the format of the format parameter. This parameter is optional. |
Name: | Expands To: |
---|---|
$web | Name of the web |
$n or $n() | New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() | Is a "no operation". This variable gets removed; useful for nested search |
$quot | Double quote (" ). Alternatively write \" to escape it |
$percnt | Percent sign (% ) |
$dollar | Dollar sign ($ ) |
format="..."
parameter format="| $topic | $summary |"
Variables that can be used in the format string:
Name: | Expands To: |
---|---|
$web | Name of the web |
$topic | Topic name |
$topic(20) | Topic name, "- " hyphenated each 20 characters |
$topic(30, -<br />) | Topic name, hyphenated each 30 characters with separator "-<br />" |
$topic(40, ...) | Topic name, shortended to 40 characters with "..." indication |
$parent | Name of parent topic; empty if not set |
$parent(20) | Name of parent topic, same hyphenation/shortening like $topic() |
$text | Formatted topic text. In case of a multiple="on" search, it is the line found for each search hit. |
$locked | LOCKED flag (if any) |
$date | Time stamp of last topic update, e.g. 06 Dec 2019 - 13:03 |
$isodate | Time stamp of last topic update, e.g. 2019-12-06T13:03Z |
$rev | Number of last topic revision, e.g. 4 |
$username | Login name of last topic update, e.g. jsmith |
$wikiname | Wiki user name of last topic update, e.g. JohnSmith |
$wikiusername | Wiki user name of last topic update, like Main.JohnSmith |
$createdate | Time stamp of topic revision 1 |
$createusername | Login name of topic revision 1, e.g. jsmith |
$createwikiname | Wiki user name of topic revision 1, e.g. JohnSmith |
$createwikiusername | Wiki user name of topic revision 1, e.g. Main.JohnSmith |
$summary | Topic summary, just the plain text, all formatting and line breaks removed; up to 162 characters |
$summary(50) | Topic summary, up to 50 characters shown |
$summary(showvarnames) | Topic summary, with %ALLTWIKI{...}% variables shown as ALLTWIKI{...} |
$summary(noheader) | Topic summary, with leading ---+ headers removedNote: The tokens can be combined, for example $summary(100, showvarnames, noheader) |
$changes | Summary of changes between latest rev and previous rev |
$changes(n) | Summary of changes between latest rev and rev n |
$formname | The name of the form attached to the topic; empty if none |
$formfield(name) | The field value of a form field; for example, $formfield(TopicClassification) would get expanded to PublicFAQ . This applies only to topics that have a TWikiForm |
$formfield(name, 10) | Form field value, "- " hyphenated each 10 characters |
$formfield(name, 20, -<br />) | Form field value, hyphenated each 20 characters with separator "-<br />" |
$formfield(name, 30, ...) | Form field value, shortended to 30 characters with "..." indication |
$pattern(reg-exp) | A regular expression pattern to extract some text from a topic (does not search meta data; use $formfield instead). In case of a multiple="on" search, the pattern is applied to the line found in each search hit.• Specify a RegularExpression that covers the whole text (topic or line), which typically starts with .* , and must end in .* • Put text you want to keep in parenthesis, like $pattern(.*?(from here.*?to here).*) • Example: $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the e-mail address from a bullet of format * Email: ... • This example has non-greedy .*? patterns to scan for the first occurance of the Email bullet; use greedy .* patterns to scan for the last occurance • Limitation: Do not use .*) inside the pattern, e.g. $pattern(.*foo(.*)bar.*) does not work, but $pattern(.*foo(.*?)bar.*) does • Note: Make sure that the integrity of a web page is not compromised; for example, if you include an HTML table make sure to include everything including the table end tag |
$count(reg-exp) | Count of number of times a regular expression pattern appears in the text of a topic (does not search meta data). Follows guidelines for use and limitations outlined above under $pattern(reg-exp) . Example: $count(.*?(---[+][+][+][+]) .*) counts the number of <H4> headers in a page. |
$n or $n() | New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() | Is a "no operation". This variable gets removed; useful for nested search |
$quot | Double quote (" ). Alternatively write \" to escape it |
$percnt | Percent sign (% ) |
$dollar | Dollar sign ($ ) |
%SEARCH{ "FAQ" scope="topic" nosearch="on" nototal="on" header=" * *Topic: Summary:*" format=" * [[$topic]]: $summary" }%
To get this:
TopicClassification
field, an OperatingSystem
field and an OsVersion
field we could write:
| *Topic:* | *OperatingSystem:* | *OsVersion:* |
%SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" scope="text" type="regex" nosearch="on" nototal="on" format="| [[$topic]] | $formfield(OperatingSystem) | $formfield(OsVersion) |" }%
To get this:
Topic: | OperatingSystem: | OsVersion: |
---|---|---|
IncorrectDllVersionW32PTH10DLL | OsWin | 95/98 |
WinDoze95Crash | OsWin | 95 |
%SEARCH{ "__Back to\:__ TWikiFAQ" scope="text" type="regex" nosearch="on" nototal="on" header="TWiki FAQs:" format=" * $pattern(.*?FAQ\:[\n\r]*([^\n\r]+).*) [[$topic][Answer...]]" }%
To get this:
TWiki FAQs: %SEARCH{ "culture" format=" * $topic is referenced by: (list all references)" nosearch="on" nototal="on" }%
%SEARCH{ "(topic found in first search)" format="$topic" nosearch="on" nototal="on" separator=", " }%
$percnt
to escape the leading percent of the second search
\"
to escape the double quotes
$dollar
to escape the $
of $topic
$nop
to escape the }%
sequence
%SEARCH{ "culture" format=" * $topic is referenced by:$n * $percntSEARCH{ \"$topic\" format=\"$dollartopic\" nosearch=\"on\" nototal=\"on\" separator=\", \" }$nop%" nosearch="on" nototal="on" }%
To get this:
$dollarpercntSEARCH{
for level three, $dollardollarpercntSEARCH{
for level four, etc.
%SEARCH{ "\.*" scope="topic" type="regex" nosearch="on" nototal="on" order="modified" reverse="on" format="| [[$topic]] | $wikiusername | $date |" limit="7" }%
To get this:
TWikiRegistration | EbenMoglen | 25 Sep 2019 - 18:08 |
TWikiPreferences | EbenMoglen | 04 Sep 2014 - 00:22 |
NewUserTemplate | IanSullivan | 08 Nov 2012 - 20:08 |
BlackListPlugin | IanSullivan | 13 Jan 2012 - 22:38 |
TWikiWebSideBar | IanSullivan | 09 Apr 2009 - 21:02 |
WebLeftBar | IanSullivan | 09 Apr 2009 - 20:37 |
WebTopicCreator | EbenMoglen | 04 Feb 2009 - 01:39 |
%CALC{$SET(weekold, $TIMEADD($TIME(), -7, day))}%
%SEARCH{ "." scope="topic" type="regex" nosearch="on" nototal="on" order="modified" reverse="on" format="$percntCALC{$IF($TIME($date) < $GET(weekold), <nop>, | [[$topic]] | $wikiusername | $date | $rev |)}$percnt" limit="100" }%
weekold
variable to the serialized date of exactly one week ago
$percnt
makes sure that the CALC gets executed once for each search hit
weekold
date
<nop>
is returned, which gets removed at the end of the TWiki rendering process
%URLPARAM{"..."}%
variable. Example:
Write this:
<form action="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%"> Find Topics: <input type="text" name="q" size="32" value="%URLPARAM{"q"}%" /> <input type="submit" class="twikiSubmit" value="Search" /> </form> Result: %SEARCH{ search="%URLPARAM{"q"}%" format=" * $web.$topic: %BR% $summary" nosearch="on" }%To get this: Result:
Attach
link at the bottom of the page. The Attach
screen lets you browse for a file, add a comment, and upload it. The uploaded file will show up in the File Attachment table. *.php
files are renamed to *.php.txt
so that no one can place code that would be read in a .php file.
%ATTACHFILESIZELIMIT%
variable of the TWikiPreferences, currently set at 10000 KB. Manage
on the Attachment to be moved.
Move
. The attachment and its version history are moved. The original location is stored as topic Meta Data.
Trash
, topic TrashAttachment
.
Attach
file: Sample.txt
Edit
topic and enter: %ATTACHURL%/Sample.txt
Preview
: %ATTACHURL%/Sample.txt
text appears as: /twiki/pub/TWiki/FileAttachment/Sample.txt, a link to the text file.
%PUBURLPATH%/%WEB%/OtherTopic/Sample.txt
(if it's within the same web)
%PUBURLPATH%/Otherweb/OtherTopic/Sample.txt
(if it's in a different web)
Attach
file: Sample.txt
Edit
topic and write text: %INCLUDE{"%ATTACHURL%/Sample.txt"}%
Attach
file: Smile.gif
Edit
topic and write text: %ATTACHURL%/Smile.gif
Preview
: text appears as /twiki/pub/TWiki/FileAttachment/Smile.gif, an image.
I | Attachment | Action | Size | Date | Who | Comment |
---|---|---|---|---|---|---|
![]() | Sample.txt | manage | 0.1 K | 22 Jul 2000 - 19:37 | TWikiContributor | Just a sample |
![]() | Smile.gif | manage | 0.1 K | 22 Jul 2000 - 19:38 | TWikiContributor | Smiley face |
Manage
link takes you to a new page that looks a bit like this (depending on what skin is selected):
Sample.txt
(UploadingUser)h
means the attachment is hidden, it isn't listed when viewing a topic.
Hide file
checkbox, then click Change properties
.
YourForm
, ExpenseReportForm
, InfoCategoryForm
, RecordReviewForm
, whatever you need.
Name
, Type
, Size
, Values
, Tooltip message
, and Attributes
(see sample below).
Example:See structure of a form for full details of what types are available and what all the columns mean. You can also retrieve possible values for
| *Name* | *Type* | *Size* | *Values* | *Tooltip message* | *Attributes* |
| TopicClassification | select | 1 | NoDisclosure, PublicSupported, PublicFAQ | blah blah... | |
| OperatingSystem | checkbox | 3 | OsHPUX, OsLinux, OsSolaris, OsWin | blah blah... | |
| OsVersion | text | 16 | | blah blah... | |
Name Type Size Values Tooltip message Attributes TopicClassification select 1 NoDisclosure, PublicSupported, PublicFAQ blah blah... OperatingSystem checkbox 3 OsHPUX, OsLinux, OsSolaris, OsWin blah blah... OsVersion text 16 blah blah...
select
, checkbox
or radio
types from other topics:
Example:Field values can also be obtained as the result of a FormattedSearch. For example,
- In the WebForm topic, define the form:
Name Type Size Values Tooltip message Attributes TopicClassification select 1 blah blah... OperatingSystem checkbox 3 blah blah... OsVersion text 16 blah blah...
Leave the
Values
field blank.
- Then in the TopicClassification topic, define the possible values:
| *Name* |
| NoDisclosure |
| Public Supported |
| Public FAQ |
Name NoDisclosure Public Supported Public FAQ
%SEARCH{"Office$" scope="topic" web="%MAINWEB%" nonoise="on" type="regex" format="$web.$topic" separator=", " }%
when used in the value field of the form definition, this will find all topic names in the Main web which end in "Office" and use them as the legal field values.
WEBFORMS
variable in WebPreferences is optional and defines a list of possible form templates.
Example:
- Set WEBFORMS = BugForm, FeatureForm, Books.BookLoanForm
WEBFORMS
enabled, an extra button is added to the edit view. If the topic doesn't have a Form, an Add Form button appears at the end of the topic. If a Form is present, a Change button appears in the top row of the Form. The buttons open a screen that enables selection of a form specified in WEBFORMS
, or the No form option.
SEARCH
to define WEBFORMS
.
WebTopicEditTemplate
topic in a web, or a new topic that serves as an application specific template topic. Initial Form values can be set there.
formtemplate
parameter in the (edit or save) URL. Initial values can then be provided in the URLs or as form values: name
, ex: ?BugPriority=1
namevalue=1
, ex: ?ColorRed=1
. <form name="newtopic" action="%SCRIPTURLPATH{"edit"}%/%WEB%/"> <input type="hidden" name="formtemplate" value="MyForm" /> New topic name <input type="text" name="topic" size="40" /> <input type="submit" class="twikiSubmit" value="Create" /> </form>
Name
, Type
, Size
, Values
, Tooltip message
, and Attributes
.
The Name
, Type
and Size
columns are required. Other columns are optional. The form must have a header row (e.g. | *Name* | *Type* | *Size* |
).
Name
is the name of the form field.
The Type
, Size
and Value
fields describe the legal values for this field, and how to display them. Type
checkbox
specifies one or more checkboxes. The Size
field specifies how many checkboxes will be displayed on each line. The Value
field should be a comma-separated list of item labels. Type
checkbox+buttons
will add Set and Clear buttons to the basic checkbox
type.
Type
radio
is like checkbox
except that radio buttons are mutually exclusive; only one can be selected.
Type
label
specifies read-only label text, The Value
field should contian the text of the label.
Type
select
specifies a select box. The Value
field should contain a comma-separated list of options for the box. The Size
field can specify a fixed size for the box (e.g. 1
, or a range e.g. 3..10
. If you specify a range, then the box will never be smaller than 3 items, never larger than 10, and will be 5 high if there are only 5 options. select
type: select+multi
turns multiselect on for the select, to allow Shift+Click and Ctrl+Click to select (or deselect) multiple items.
select+values
allows the definition of values that are different to the displayed text. For example: | Field 9 | select+values | 5 | One, Two=2, Three=III, Four | Various values formats |shows but the values or options
Two
and Three
are 2
and III
respectively.select+multi+values
Type
text
specifies a one-line text field. Size
specifies the text box width in number of characters. Value
is the initial (default) content when a new topic is created with this form template.
Type
textarea
specifies a multi-line text box. The Size
field should specify columns x rows, e.g. 80x6
; default size is 40x5. As for text
, the Value
field specifies the initial text
Type
date
specifies a single-line text box and a button next to it; clicking on the button will bring up a calendar from which the user can select a date. The date can also be typed into the text box. Size
specifies the text box width in characters. As for text
, the Value
field specifies the initial text
Tooltip message
is a message that will be displayed when the cursor is hovered over the field in edit
view.
Attributes
specifies special attributes for the field. Multiple attributes can be entered, separated by spaces. H
indicates that this field should not be shown in view mode. However, the field is available for editing and storing information.
M
indicates that this field is mandatory. The topic cannot be saved unless a value is provided for this field. If the field is found empty during topic save, an error is raised and the user is redirected to an oops
page. Mandatory fields are indicated by an asterisks next to the field name.
| *Name* | *Type* | *Size* | | Name | text | 80 | | Date | date | 30 |Field Name Notes:
Aeroplane Manufacturers
is equivalent to AeroplaneManufacturers
.
label
field has no name, it will not be shown when the form is viewed, only when it is edited.
select
, checkbox
or radio
field, and want to get the values from another topic, you can use [[...]]
links. This notation can also be used when referencing another topic to obtain field values, but a name other than the topic name is required as the name of the field.
label
, text
, and textarea
fields the value may also contain commas. checkbox
fields cannot be initialized through the form template.
$quot
("), $percnt
(%), $dollar
($), $n
(newline), and $nop
can be used to prevent expansion.
| *Name* | *Type* | *Size* | | AeroplaneManufacturers | select | |the TWiki will look for the topic AeroplaneManufacturers to get the possible values for the
select
.
The AeroplaneManufacturers topic must contain a table, where each row of the table describes a possible value. The table only requires one column, Name
. Other columns may be present, but are ignored.
For example:
| *Name* | | Routan | | Focke-Wulf | | De Havilland |Notes:
Values
column must be empty in the referring form definition.
checkbox
+multi
anywhere in the name
SubmitExpenseReport
topic where you can create new expense reports, a SubmitVacationRequest
topic, and so on. These can specify the required template topic with its associated form. Template topics has more.
FORMFIELD
, SEARCH
and METASEARCH
variables in TWikiVariables, and TWiki Formatted Search.
ExampleSearching forms this way is obviously pretty inefficient, but it's easy to do. If you want better performance, take a look at some of the structured wiki extensions that support higher performance searching e.g. TWiki:Plugins.DBCachePlugin.
TWiki users often want to have an overview of topics they contributed to. With the$formfield
parameter it is easy to display the value of a classification field next to the topic link:| *Topic* | *Classification* | %SEARCH{"%MAINWEB%.UserName" scope="text" nosearch="on" nototal="on" order="modified" reverse="on" format="|<b>[[$web.$topic][$topic]]</b> |<nop>$formfield(TopicClassification) |" web="Sandbox"}%
text
fields when a topic is saved. If you need linefeeds in a field, make sure it is a textarea
.
%TMPL:<key>%
and %TMPL:<key>{"attr"}%
.
%TMPL:INCLUDE{"file"}%
: Includes a template file. The file is found as described below.
%TMPL:DEF{"block"}%
: Define a block. All text between this and the next %TMPL:END%
directive is removed and saved for later use with %TMPL:P
.
%TMPL:END%
: Ends a block definition.
%TMPL:P{"var"}%
: Includes a previously defined block.
%{...}%
: is a comment.
twiki.tmpl
master template, like twiki.print.tmpl
, that redefines the header and footer.
%TMPL:DEF{"x"}% x%P%z%TMPL:END%
then %TMPL:P{"x" P="y"}%
will expand to xyz
.
Note that parameters can simply be ignored; for example=%TMPL:P{"x"}%= will expand to x%P%z.
Any alphanumeric characters can be used in parameter names. You are highly recommended to use parameter names that cannot be confused with TWikiVariables.
Note that three parameter names, context
, then
and else
are reserved. They are used to support a limited form of "if" condition that you can use to select which of two templates to use, based on a context identifier:
%TMPL:DEF{"link_inactive"}%<input type="button" disabled value="Link>%TMPL:END% %TMPL:DEF{"link_active"}%<input type="button" onclick="link()" value="Link" />%TMPL:END% %TMPL:P{context="inactive" then="inactive_link" else="active_link"}% for %CONTEXT%When the "inactive" context is set, then this will expand the "link_inactive" template; otherwise it will expand the "link_active" template. See IfStatements for details of supported context identifiers.
twiki/templates
directory, or can also be read from user topics. As an example, twiki/templates/view.tmpl
is the default template file for the twiki/bin/view
script.
Templates that are included using %TMPL:INCLUDE%
are also found using the same search algorithm, unless you explicitly put '.tmpl'
at the end of the template name. In this case, the string is assumed to be the full name of a template in the templates
directory, and the algorithm isn't used.
TWiki uses the following search order to determine which template file or topic to use for a particular script. The skin path is set as described in TWikiSkins.
For example, theLegend:
- templates/web/script.skin.tmpl for each skin on the skin path
this usage is supported for compatibility only and is deprecated. Store web-specific templates in TWiki topics instead.
- templates/script.skin.tmpl for each skin on the skin path
- templates/web/script.tmpl
this usage is supported for compatibility only and is deprecated. Store web-specific templates in TWiki topics instead.
- templates/script.tmpl
- The TWiki topic aweb.atopic if the template name can be parsed into aweb.atopic
- The TWiki topic web.SkinSkinScriptTemplate for each skin on the skin path
- The TWiki topic web.ScriptTemplate
- The TWiki topic %TWIKIWEB%.SkinSkinScriptTemplate for each skin on the skin path
- The TWiki topic %TWIKIWEB%.ScriptTemplate
- script refers to the script name, e.g
view
,edit
- Script refers to the same, but with the first character capitalized, e.g
View
- skin refers to a skin name, e.g
dragon
,pattern
. All skins are checked at each stage, in the order they appear in the skin path.- Skin refers to the same, but with the first character capitalized, e.g
Dragon
- web refers to the current web
example
template file will be searched for in the following places, when the current web is Thisweb
and the skin path is print,pattern
: templates/Thisweb/example.print.tmpl
deprecated; don't rely on it
templates/Thisweb/example.pattern.tmpl
deprecated; don't rely on it
templates/example.print.tmpl
templates/example.pattern.tmpl
templates/Thisweb/example.tmpl
deprecated; don't rely on it
templates/example.tmpl
Thisweb.PrintSkinExampleTemplate
Thisweb.PatternSkinExampleTemplate
Thisweb.ExampleTemplate
TWiki.PrintSkinExampleTemplate
TWiki.PatternSkinExampleTemplate
TWiki.ExampleTemplate
view
and edit
scripts, for example when a topic-specific template is required. Two preference variables can be user to override the templates used: VIEW_TEMPLATE
sets the template to be used for viewing a topic
EDIT_TEMPLATE
sets the template for editing a topic.
view
and edit
respectively. The template search order is as specified above.
%TMPL:INCLUDE{"twiki"}%
, the templating system will include the next twiki.SKIN in the skin path.
For example, to create a customisation of pattern skin, where you only want to over-ride the breadcrumbs for the view script, you can create only a view.yourlocal.tmpl:
%TMPL:INCLUDE{"view"}% %TMPL:DEF{"breadcrumb"}% We don't want any crumbs %TMPL:END%and then set SKIN=yourlocal,pattern
%TMPL:DEF
and %TMPL:END%
) to define common sections that appear in two or more other templates. twiki.tmpl
is the default master template.
Template variable: Defines: %TMPL:DEF{"sep"}%
"|" separator %TMPL:DEF{"htmldoctype"}%
Start of all HTML pages %TMPL:DEF{"standardheader"}%
Standard header (ex: view, index, search) %TMPL:DEF{"simpleheader"}%
Simple header with reduced links (ex: edit, attach, oops) %TMPL:DEF{"standardfooter"}%
Footer, excluding revision and copyright parts %TMPL:DEF{"oops"}%
Skeleton of oops dialog
When you create a new topic, TWiki locates a topic to use as a content template according to the following search order:
Topic Name: What it is: WebTopicViewTemplate Error page shown when you try to view a nonexistent topic WebTopicNonWikiTemplate Alert page shown when you try to view a nonexistent topic with a non-WikiName WebTopicEditTemplate Default text shown when you create a new topic.
templatetopic
CGI parameter
Variable: Description: %DATE%
Signature format date. See VarDATE %GMTIME%
Date/time. See VarGMTIME %GMTIME{...}%
Formatted date/time. See VarGMTIME2 %NOP%
A no-operation variable that gets removed. Useful to prevent a SEARCH from hitting an edit template topic; also useful to escape a variable, such as %URLPA%NOP%RAM{...}%
escaping URLPARAM%STARTSECTION{type="templateonly"}%
...
%ENDSECTION{type="templateonly"}%Text that gets removed when a new topic based on the template is created. See notes below. %SERVERTIME%
Date/time. See VarSERVERTIME %SERVERTIME{...}%
Formatted date/time. See VarSERVERTIME2 %USERNAME%
Login name of user who is instantiating the new topic, e.g. guest %URLPARAM{"name"}%
Value of a named URL parameter %WIKINAME%
WikiName of user who is instantiating the new topic, e.g. TWikiGuest %WIKIUSERNAME%
User name of user who is instantiating the new tpoic, e.g. Main.TWikiGuest
%STARTSECTION{type="templateonly"}%
...
%ENDSECTION{type="templateonly"}%
markers are used to embed text that you do not want expanded when a new topic based on the template topic is created. For example, you might want to write in the template topic:
This template can only be changed by: * Set ALLOWTOPICCHANGE = %MAINWEB%.TWikiAdminGroupThis will restrict who can edit the template topic, but will get removed when a new topic based on that template topic is created.
%NOP%
can be used to prevent expansion of TWiki variables that would otherwise be expanded during topic creation e.g.i escape %nop>SERVERTIME%
with %SER%NOP%VERTIME%
.
All other variables are unchanged, e.g. are carried over "as is" into the new topic.
templatetopic
specifies ExampleTopicTemplate as the template topic to use. Here is the HTML source of the form:
<form name="new" action="%SCRIPTURLPATH{edit}%/%WEB%/"> * New example topic: <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="26" /> <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" /> <input type="hidden" name="topicparent" value="%TOPIC%" /> <input type="hidden" name="onlywikiname" value="on" /> <input type="hidden" name="onlynewtopic" value="on" /> <input type="submit" class="twikiSubmit" value="Create" /> (date format is <nop>YYYYxMMxDD) </form>See TWikiScripts#edit for details of the parameters that the
edit
script understands.
%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%
AUTOINC<n>
to the topic name in the edit and save scripts, it gets replaced with an auto-incremented number on topic save. <n>
is a number starting from 0, and may include leading zeros. Leading zeros are used to zero-pad numbers so that auto-incremented topic names can sort properly. Deleted topics are not re-used to ensure uniqueness of topic names. That is, the auto-incremented number is always higher than the existing ones, even if there are gaps in the number sequence.
Examples: BugAUTOINC0
- creates topic names Bug0
, Bug1
, Bug2
, ... (does not sort properly)
ItemAUTOINC0000
- creates topic names Item0000
, Item0001
, Item0002
, ... (sorts properly up to 9999)
DocIDAUTOINC10001
- start with DocID10001
, DocID10002
, ... (sorts properly up to 99999; auto-links)
[[%SCRIPTURLPATH{"edit"}%/%WEB%/BugIDAUTOINC00000?templatetopic=BugTemplate&topicparent=%TOPIC%&t=%SERVERTIME{"$day$hour$min$sec"}%][Create new item]]=
oopsbase.tmpl
and an example oops dialog oopstest.tmpl
based on the base template. %TMPL:P{"sep"}%
%TMPL:DEF{"sep"}% | %TMPL:END% <html> <head> <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title> <base href="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%"> <meta name="robots" content="noindex"> </head> <body bgcolor="#FFFFFF"> <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr> <td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%"> <a href="%WIKIHOMEURL%"> <img src="%PUBURLPATH%/wikiHome.gif" border="0"></a> </td> <td> <b>%WIKITOOLNAME% . %WEB% . </b><font size="+2"> <B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font> </td> </tr> <tr bgcolor="%WEBBGCOLOR%"> <td colspan="2"> %TMPL:P{"webaction"}% </td> </tr> </table> --- ++ %TMPL:P{"heading"}% %TMPL:P{"message"}% <table width="100%" border="0" cellpadding="3" cellspacing="0"> <tr bgcolor="%WEBBGCOLOR%"> <td valign="top"> Topic <b>%TOPIC%</b> . { %TMPL:P{"topicaction"}% } </td> </tr> </table> </body>
%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END% %TMPL:DEF{"webaction"}% test =webaction= %TMPL:END% %TMPL:DEF{"heading"}% Test heading %TMPL:END% %TMPL:DEF{"message"}% Test =message=. Blah blah blah blah blah blah blah blah blah blah blah... * Some more blah blah blah blah blah blah blah blah blah blah... * Param1: %PARAM1% * Param2: %PARAM2% * Param3: %PARAM3% * Param4: %PARAM4% %TMPL:END% %TMPL:DEF{"topicaction"}% Test =topicaction=: [[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}% [[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END% %TMPL:INCLUDE{"oopsbase"}%
.../bin/oops/Sandbox/TestTopic2?template=oopstest¶m1=WebHome¶m2=WebNotify
twiki/templates
directory and are named according to the skin: <scriptname>.<skin>.tmpl
. Skin files may also be defined in TWiki topics - see TWikiTemplates for details.
To start creating a new skin, copy the default TWikiTemplates (like view.tmpl
), or copy an existing skin to use as a base for your own skin. You should only need to copy the files you intend to customise, as TWiki can be configured to fall back to another skin if a template is not defined in your skin. Name the files as described above (for example view.myskin.tmpl
.
For your own TWiki skin you are encouraged to show a small 80x31 pixel <a href="http://twiki.org/"><img src="%PUBURL%/%TWIKIWEB%/TWikiLogos/T-logo-80x15.gif" alt="This site is powered by the TWiki collaboration platform" width="80" height="15" title="This site is powered by the TWiki collaboration platform" border="0" /></a>
The standard TWiki skins show the logo in the %WEBCOPYRIGHT%
variable.
text
skin, and skin names starting with rss
have hard-coded meanings.
The following template files are used for TWiki screens, and are referenced in the TWiki core code. If a skin doesn't define its own version of a template file, then TWiki will fall back to the next skin in the skin path, or finally, to the default version of the template file.
(Certain template files are expected to provide certain TMPL:DEFs - these are listed in sub-bullets) addform
- used to select a new form for a topic
attachagain
- used when refreshing an existing attachment
attachnew
- used when attaching a new file to a topic
attachtables
- defines the format of attachments at the bottom of the standard topic view ATTACH:files:footer
, ATTACH:files:header
, ATTACH:files:row
, ATTACH:versions:footer
, ATTACH:versions:header
, ATTACH:versions:row
changeform
- used to change the form in a topic
changes
- used by the changes
script
edit
- used for the edit screen
form
formtables
- used to defined the format of forms FORM:display:footer
, FORM:display:header
, FORM:display:row
login
- used for loggin in when using the TemplateLoginManager LOG_IN
, LOG_IN_BANNER
, LOG_OUT
, LOGGED_IN_BANNER
, NEW_USER_NOTE
, UNRECOGNISED_USER
moveattachment
- used when moving an attachment
oopsaccessdenied
- used to format Access Denied messages no_such_topic
, no_such_web
, only_group
, topic_access
oopsattention
- used to format Attention messages already_exists
, bad_email
, bad_ver_code
, bad_wikiname
, base_web_missing
, confirm
, created_web
, delete_err
, invalid_web_color
, invalid_web_name
, in_a_group
, mandatory_field
, merge_notice
, missing_action
, missing_fields
, move_err
, missing_action
, no_form_def
, no_users_to_reset
, notwikiuser
, oversized_upload
, password_changed
, password_mismatch
, problem_adding
, remove_user_done
, rename_err
, rename_not_wikiword
, rename_topic_exists
, rename_web_err
, rename_web_exists
, rename_web_prerequisites
, reset_bad
, reset_ok
, save_error
, send_mail_error
, thanks
, topic_exists
, unrecognized_action
, upload_name_changed
, web_creation_error
, web_exists
, web_missing
, wrong_password
, zero_size_upload
oopschangelanguage
- used to prompt for a new language when internationalisation is enabled
oopsgeneric
- a basic dialog for user information; provides "ok" button only
oopslanguagechanged
- used to confirm a new language when internationalisation is enabled
oopsleaseconflict
- used to format lease Conflict messages lease_active
, lease_old
preview
- used for previewing edited topics before saving
rdiff
- used for viewing topic differences
registernotify
- used by the user registration system
registernotifyadmin
- used by the user registration system
rename
- used when renaming a topic
renameconfirm
- used when renaming a topic
renamedelete
- used when renaming a topic
renameweb
- used when renaming a web
renamewebconfirm
- used when renaming a web
renamewebdelete
- used when renaming a web
searchbookview
- used to format inline search results in book view
searchformat
- used to format inline search results
search
- used by the search
CGI script
settings
view
- used by the view
CGI script
viewprint
- used to create the printable view
twiki.tmpl
is a master template conventionally used by other templates, but not used directly by code.
TMPL:INCLUDE
the default templates, or templates from other skins, when you are defining your own skin, you run the risk that the included file might change and break your skin.
%TMPL:INCLUDE{"twiki"}%
, the templating system will include the next twiki.SKIN in the skin path.
For example, to create a customisation of pattern skin, where you only want to remove the edit & WYSIWYG buttons from view page, you create only a view.yourlocal.tmpl
:
%TMPL:INCLUDE{"view"}% %TMPL:DEF{"edit_topic_link"}%%TMPL:END% %TMPL:DEF{"edit_wysiwyg_link"}%%TMPL:END%and then set
SKIN=yourlocal,pattern
.
Because ClassicSkin and the default templates use the same Template definition names, you can over-ride the edit links in them (or any skin derived from them) using the same view.yourlocal.tmpl
(just set SKIN=yourlocal,classic either in TWikiPreferences for globally, or a Web's Webname.WebPreferences for a particular web)
Variable: | Expanded to: |
---|---|
%WEBLOGONAME% | Filename of web logo |
%WEBLOGOIMG% | Image URL of web logo |
%WEBLOGOURL% | Link of web logo |
%WEBLOGOALT% | Alt text of web logo |
%WIKILOGOURL% | Link of page logo |
%WIKILOGOIMG% | Image URL of page logo |
%WIKILOGOALT% | Alt text of page logo |
%WEBBGCOLOR% | Web-specific background color, defined in the WebPreferences |
%WIKITOOLNAME% | The name of your TWiki site |
%SCRIPTURL% | The script URL of TWiki |
%SCRIPTURLPATH% | The script URL path |
%SCRIPTSUFFIX% | The script suffix, ex: .pl , .cgi |
%WEB% | The name of the current web. |
%TOPIC% | The name of the current topic. |
%WEBTOPICLIST% | Common links of current web, defined in the WebPreferences. It includes a Go box |
%TEXT% | The topic text, e.g. the content that can be edited |
%META{"form"}% | TWikiForm, if any |
%META{"attachments"}% | FileAttachment table |
%META{"parent"}% | The topic parent |
%EDITTOPIC% | Edit link |
%REVTITLE% | The revision title, if any, ex: (r1.6) |
%REVINFO% | Revision info, ex: r1.6 - 24 Dec 2002 - 08:12 GMT - TWikiGuest |
%WEBCOPYRIGHT% | Copyright notice, defined in the WebPreferences |
%BROADCASTMESSAGE% | Broadcast message at the beginning of your view template, can be used to alert users of scheduled downtimes; can be set in TWikiPreferences |
http://www.google.com/
to jump to an external web site. The feature is handy if you build a skin that has a select box of frequently used links, like Intranet home, employee database, sales database and such. A little JavaScript gets into action on the onchange
method of the select tag to fill the selected URL into the "Go" box field, then submits the form.
Here is an example form that has a select box and the "Go" box for illustration purposes. You need to have JavaScript enabled for this to work:
Note: Redirect to a URL only works if it is enabled in configure
(Miscellaneous, {AllowRedirectUrl}
).
styles.pattern.tmpl
.
<style type='text/css' media='all'>@import url('%PUBURLPATH%/%TWIKIWEB%/MySkin/mystyle.css');</style>
attachtables.tmpl
template using the %TMPL:DEF
macro syntax described in TWikiTemplates. These macros are:
Macro | Description |
---|---|
ATTACH:files:header | Standard title bar |
ATTACH:files:row | Standard row |
ATTACH:files:footer | Footer for all screens |
ATTACH:files:header:A | Title bar for upload screens, with attributes column |
ATTACH:files:row:A | Row for upload screen |
ATTACH:files:footer:A | Footer for all screens |
Macro | Description |
---|---|
ATTACH:versions:header | Header for versions table on upload screen |
ATTACH:versions:row | Row format for versions table on upload screen |
ATTACH:versions:footer | Footer for versions table on upload screen |
ATTACH:row
macros are expanded for each file in the attachment table, using the following special tags:
Tag | Description |
---|---|
%A_URL% | URL that will recover the file |
%A_REV% | Revision of this file |
%A_ICON% | A file icon suitable for representing the attachment content |
%A_FILE% | The name of the file |
%A_SIZE% | The size of the file |
%A_DATE% | The date the file was uploaded |
%A_USER% | The user who uploaded it |
%A_COMMENT% | The comment they put in when uploading it |
%A_ATTRS% | The attributes of the file as seen on the upload screen e.g "h" for a hidden file |
view.
skin.tmpl
, where skin is the name of the skin e.g. pattern
. If no template is found, then the fallback is to use view.tmpl
. Each skin on the path is searched for in turn. For example, if you have set the skin path to local,pattern
then view.local.tmpl
will be searched for first, then view.pattern.tmpl
and finally view.tmpl
.
The basic skin is defined by a SKIN
setting:
Set SKIN = catskin, bearskin
?skin=catskin,bearskin
:
Setting SKIN
(or the ?skin
parameter in the URL) replaces the existing skin path setting, for the current page only. You can also extend the existing skin path as well, using covers.
Set COVER = ruskin
ruskin, catskin, bearskin
). There is also an equivalent cover
URL parameter. The difference between setting SKIN
vs. COVER
is that if the chosen template is not found (e.g., for included templates), SKIN
will fall back onto the next skin in line, or the default skin, if only one skin was present, while COVER
will always fall back onto the current skin.
An example would be invoking the printable mode, which is achieved by applying ?cover=print
. The view.print.tmpl
simply invokes the viewprint
template for the current skin which then can appropriately include all other used templates for the current skin. Where the printable mode be applied by using SKIN
, all skins would have the same printable appearance.
The full skin path is built up as follows: SKIN
setting (or ?skin
if it is set), then COVER
setting is added, then ?cover
.
text
skin is reserved for TWiki internal use.
Skin names starting with rss
also have a special meaning; if one or more of the skins in the skin path starts with 'rss' then 8-bit characters will be encoded as XML entities in the output, and the content-type
header will be forced to text/xml
.
Related Topics: TWikiSkinBrowser, AdminDocumentationCategory, DeveloperDocumentationCategory, TWiki:TWiki.TWikiSkinsSupplement
-- Contributors: TWiki:Main.PeterThoeny, TWiki:Main.MikeMannix, TWiki:Main.CrawfordCurrie
META
variable name/value pairs
META
variables to store topic data that's separate from the main free-form content. This includes program-generated info like FileAttachment and topic movement data, and user-defined TWikiForms info. Use META
variables to format and display Meta Data.
%META:<type>{key1="value1" key2="value2" ...}%
name
, this appears first for easier searching (note the order of the variables themselves is defined).
\n
(new line) is represented in values by %_N_
and "
(double-quotes) by %_Q_%
.
Example of Format%META:TOPICINFO{version="1.6" date="976762663" author="LastEditorWikiName" format="1.0"}% text of the topic %META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="TopicMoverWikiName" date="976762680"}% %META:TOPICPARENT{name="NavigationByTopicContext"}% %META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }% %META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }% %META:FORM{name="WebFormTemplate"}% %META:FIELD{name="OperatingSystem" value="OsWin"}% %META:FIELD{name="TopicClassification" value="PublicFAQ"}%
Key | Comment |
---|---|
version | Same as RCS version |
date | integer, unix time, seconds since start 1970 |
author | last to change topic, is the REMOTE_USER |
format | Format of this topic, will be used for automatic format conversion |
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%
Key | Comment |
---|---|
from | Full name, i.e., web.topic |
to | Full name, i.e., web.topic |
by | Who did it, is the REMOTE_USER, not WikiName |
date | integer, unix time, seconds since start 1970 |
Key | Comment |
---|---|
name | The topic from which this was created, typically when clicking on a ? questionmark link, or by filling out a form. Normally just TopicName , but it can be a full Web.TopicName format if the parent is in a different Web. |
Key | Comment |
---|---|
name | Name of file, no path. Must be unique within topic |
version | Same as RCS revision |
path | Full path file was loaded from |
size | In bytes |
date | integer, unix time, seconds since start 1970 |
user | the REMOTE_USER, not WikiName |
comment | As supplied when file uploaded |
attr | h if hidden, optional |
Key | Comment |
---|---|
movedfrom | full topic name - web.topic |
movedby | the REMOTE_USER, not WikiName |
movedto | full topic name - web.topic |
moveddate | integer, unix time, seconds since start 1970 |
Key | Comment |
---|---|
name | A topic name - the topic represents one of the TWikiForms. Can optionally include the web name (i.e., web.topic), but doesn't normally |
Key | Name |
---|---|
name | Ties to entry in TWikiForms template, is title with all bar alphanumerics and . removed |
title | Full text from TWikiForms template |
value | Value user has supplied via form |
diff
function output appears in a logical order
META:TOPICINFO
META:TOPICPARENT
(optional)
META:TOPICMOVED
(optional)
META:FILEATTACHMENT
(0 or more entries)
META:FORM
(optional)
META:FIELD
(0 or more entries; FORM required)
Raw Text
link can be clicked to show the text of a topic (i.e., as seen when editing). This is done by adding raw=on
to URL. raw=debug
shows the meta data as well as the topic data, ex: debug view for this topic
view
, preview
and edit
scripts.
You can render form fields in topic text by using the FORMFIELD variable. Example:%FORMFIELD{"TopicClassification"}%
Variable usage: | Comment: |
---|---|
%META{"form"}% | Show form data, see TWikiForms. |
%META{"formfield"}% | Show form field value. Parameter: name="field_name" . Example:%META{ "formfield" name="TopicClassification" }% |
%META{"attachments"}% | Show attachments, except for hidden ones. Options: all="on" : Show all attachments, including hidden ones. |
%META{"moved"}% | Details of any topic moves. |
%META{"parent"}% | Show topic parent. Options: dontrecurse="on" : By default recurses up tree, at some cost. nowebhome="on" : Suppress WebHome. prefix="..." : Prefix for parents, only if there are parents, default "" . suffix="..." : Suffix, only appears if there are parents, default "" . separator="..." : Separator between parents, default is " > " . |
Meta.pm
code that supports the format needs only minor alteration.
Related Topics: DeveloperDocumentationCategory, UserDocumentationCategory
-- Contributors: TWiki:Main.JohnTalintyre, TWiki:Main.MikeMannix, TWiki:Main.PeterThoeny, TWiki:Main.CrawfordCurrie
%FAILEDPLUGINS%
variable can be used to debug failures. You may also want to check your webserver error log and the various TWiki log files.
ab
utility. Example on Unix:time wget -qO /dev/null /twiki/bin/view/TWiki/AbcPlugin
DISABLEDPLUGINS
to be a comma-separated list of names of plugins to disable. Define it in Main.TWikiPreferences to disable those plugins everywhere, in the WebPreferences topic to disable them in an individual web, or in a topic to disable them in that topic. For example,
* Set DISABLEDPLUGINS = SpreadSheetPlugin, EditTablePlugin
{PluginsOrder}
in the Plugins section of configure.
%<pluginname>_<var>%
. For example, %RUBBERPLUGIN_SETTING%
shows the value of SETTING in the RubberPlugin topic.
%ACTIVATEDPLUGINS%
%PLUGINDESCRIPTIONS%
"$SUM( $ABOVE() )"
to TWiki tables and other topic textExternalSite:Page
text to external sites based on aliases defined in a rules topic :-)
or %FAILEDPLUGINS%
Plugin | Errors |
---|---|
SpreadSheetPlugin | none |
ActionTrackerPlugin | none |
AttachmentListPlugin | none |
BreadCrumbsPlugin | none |
CalendarPlugin | none |
CommentPlugin | none |
CompareRevisionsAddonPlugin | none |
EditTablePlugin | none |
FilterPlugin | none |
FlexWebListPlugin | none |
FootNotePlugin | none |
GluePlugin | none |
IfDefinedPlugin | none |
InterwikiPlugin | none |
JQueryPlugin | none |
NatSkinPlugin | none |
PreferencesPlugin | none |
RedDotPlugin | none |
RenderListPlugin | none |
SlideShowPlugin | none |
SmiliesPlugin | none |
TablePlugin | none |
TreeBrowserPlugin | none |
TreePlugin | none |
TwistyPlugin | none |
VotePlugin | none |
WysiwygPlugin | none |
Handler | Plugins |
---|---|
afterEditHandler | ActionTrackerPlugin |
afterSaveHandler | TreePlugin |
beforeCommonTagsHandler | PreferencesPlugin TwistyPlugin WysiwygPlugin |
beforeEditHandler | ActionTrackerPlugin WysiwygPlugin |
beforeSaveHandler | ActionTrackerPlugin CommentPlugin WysiwygPlugin |
commonTagsHandler | SpreadSheetPlugin ActionTrackerPlugin CalendarPlugin CommentPlugin CompareRevisionsAddonPlugin EditTablePlugin FilterPlugin FootNotePlugin GluePlugin IfDefinedPlugin JQueryPlugin NatSkinPlugin RedDotPlugin SlideShowPlugin SmiliesPlugin |
initPlugin | SpreadSheetPlugin ActionTrackerPlugin AttachmentListPlugin BreadCrumbsPlugin CalendarPlugin CommentPlugin CompareRevisionsAddonPlugin EditTablePlugin FilterPlugin FlexWebListPlugin FootNotePlugin GluePlugin IfDefinedPlugin InterwikiPlugin JQueryPlugin NatSkinPlugin PreferencesPlugin RedDotPlugin RenderListPlugin SlideShowPlugin SmiliesPlugin TablePlugin TreeBrowserPlugin TreePlugin TwistyPlugin VotePlugin WysiwygPlugin |
modifyHeaderHandler | WysiwygPlugin |
postRenderingHandler | EditTablePlugin FootNotePlugin NatSkinPlugin PreferencesPlugin RedDotPlugin TwistyPlugin WysiwygPlugin |
preRenderingHandler | InterwikiPlugin SmiliesPlugin TablePlugin TreeBrowserPlugin |
redirectCgiQueryHandler | RedDotPlugin |
startRenderingHandler | RenderListPlugin This handler is deprecated - please check for updated versions of the plugins that use it! |
lib/TWiki/Func.pm
) describes all the interfaces available to Plugins. Plugins should only use the interfaces described in this module.
Func.pm
, you run the risk of creating security holes. Also, your Plugin will likely break and require updating when you upgrade to a new version of TWiki.
lib/TWiki/Plugins/EmptyPlugin.pm
module.
DISABLE_
from the function name.
eval
block like this:eval { require IPC::Run }
return "<font color=\"red\">SamplePlugin: Can't load required modules ($@)</font>" if $@;
$VERSION='0.000'
variable, beginning at 1.000
.
initPlugin
handler should check all dependencies and return TRUE if the initialization is OK or FALSE if something went wrong. initPlugin
handler).
$TWiki::Plugins::VERSION
in the TWiki::Plugins
module contains the TWiki Plugin API version, currently 1.11. %PLUGINVERSION{}%
variable to query the Plugin API version or the version of installed Plugins.
%TWiki::cfg
hash than adding it as preferences in the Plugin topic MyFirstPlugin.pm
MyFirstPlugin.txt
MyFirstPlugin
topic. Other needed Perl code is best placed in a lib/TWiki/Plugins/MyFirstPlugin/
directory.
The Plugin API handles the details of connecting your Perl module with main TWiki code. When you're familiar with the Plugin API, you're ready to develop Plugins.
lib/TWiki/Plugins/EmptyPlugin.pm
to <name>Plugin.pm
. The EmptyPlugin.pm
module contains mostly empty functions, so it does nothing, but it's ready to be used. Customize it. Refer to the Plugin API specs for more information.
If your Plugin uses its own modules and objects, you must include the name of the Plugin in the package name. For example, write Package MyFirstPlugin::Attrs;
instead of just Package Attrs;
. Then call it using:
use TWiki::Plugins::MyFirstPlugin::Attrs; $var = MyFirstPlugin::Attrs->new();
MyFirstPlugin
, press enter and create the new topic
OUTLINE: Doc Topic Contents
Check the Plugins web on TWiki.org for the latest Plugin doc topic template. Here's a quick overview of what's covered: Syntax Rules: <Describe any special text formatting that will be rendered.>" Example: <Include an example of the Plugin in action. Possibly include a static HTML version of the example to compare if the installation was a success!>" Plugin Settings: <Description and settings for custom Plugin %VARIABLES%, and those required by TWiki.>"Plugin Installation Instructions: <Step-by-step set-up guide, user help, whatever it takes to install and run, goes here.>" Plugin Info: <Version, credits, history, requirements - entered in a form, displayed as a table. Both are automatically generated when you create or edit a page in the TWiki:Plugins web.>"
- Plugins Preferences <If user settings are needed, explain... Entering values works exactly like TWikiPreferences and WebPreferences: six (6) spaces and then:>"
- Set <EXAMPLE = value added>
Plugin
, ex: MyFirstPlugin.pm
, and a documentation page with the same name(MyFirstPlugin.txt
).
lib/TWiki/Plugins/MyFirstPlugin.pm
data/TWiki/MyFirstPlugin.txt
pub/TWiki/MyFirstPlugin/uparrow.gif
[a required graphic]
MyFirstPlugin.zip
) and add the entire directory structure from Step 1. The archive should look like this: lib/TWiki/Plugins/MyFirstPlugin.pm
data/TWiki/MyFirstPlugin.txt
pub/TWiki/MyFirstPlugin/uparrow.gif
MyFirstPlugin
MyFirstPlugin.zip
Dev
, ex: MyFirstPluginDev
. This is the discussion page for future development. (User support for Plugins is handled in TWiki:Support.)
TWiki::Func::getWorkArea()
function, which gives you a persistant directory where you can store data files. By default they will not be web accessible. The directory is guaranteed to exist, and to be writable by the webserver user. For convenience, TWiki::Func::storeFile()
and TWiki::Func::readFile()
are provided to persistently store and retrieve simple data in this area.
TWiki::Func::saveAttachment()
function to store the data.
Recommendation for file name: _FooBarPlugin_img123.gif
TWiki::Func::saveAttachment()
function to store the data.
Recommendation for file names in Plugin attachment area: _Main_roundedge-ul.gif
Dev
, such as MyFirstPluginDev
. The Plugin development topic is a great resource to discuss feature enhancements and to get feedback from the TWiki community.
TWiki::Plugins
version in which the handler was first deprecated. For example, if we need to define the endRenderingHandler
for compatibility with TWiki::Plugins
versions before 1.1, we would add this to the plugin:
package TWiki::Plugins::SinkPlugin; use vars qw( %TWikiCompatibility ); $TWikiCompatibility{endRenderingHandler} = 1.1;If the currently-running TWiki version is 1.1 or later, then the handler will not be called and the warning will not be issued. TWiki with versions of
TWiki::Plugins
before 1.1 will still call the handler as required.
%PLUGINVERSION%
variable. The 'Since' field in the function
documentation refers to the VERSION number and the date that the function
was addded.
Note: Beware! These methods should only ever be called
from the context of a TWiki Plugin. They require a Plugins SESSION context to be
established before they are called, and will not work if simply called from
another TWiki module. For example,
use TWiki; print TWiki::Func::getSkin(),"\n";will fail with
Can't call method "getSkin" on an undefined value at TWiki/Func.pm line 83
.
If you want to call the methods outside the context of a plugin, you can create a Plugins SESSION object. For example,
the script:
use TWiki: $TWiki::Plugins::SESSION = new TWiki(); print TWiki::Func::getSkin(),"\n";will work happily.
SKIN
and COVER
preferences variables or the skin
and cover
CGI parameters
Return: $skin
Comma-separated list of skins, e.g. 'gnu,tartan'
. Empty string if none.
Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
$host
URL host, e.g. "http://example.com:80"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web
- Web name, e.g. 'Main'
$topic
- Topic name, e.g. 'WebNotify'
$script
- Script name, e.g. 'view'
...
- an arbitrary number of name,value parameter pairs that will be url-encoded and added to the url. The special parameter name '#' is reserved for specifying an anchor. e.g. getScriptUrl('x','y','view','#'=>'XXX',a=>1,b=>2) will give .../view/x/y?a=1&b=2#XXX
$url
URL, e.g. "http://example.com:80/cgi-bin/view.pl/Main/WebNotify"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web
- Web name, e.g. 'Main'
. The current web is taken if empty
$topic
- Topic name, e.g. 'WebNotify'
$url
URL, e.g. "http://example.com:80/cgi-bin/view.pl/Main/WebNotify"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web
- Web name, e.g. 'Main'
. The current web is taken if empty
$topic
- Topic name, e.g. 'WebNotify'
$template
- Oops template name, e.g. 'oopsmistake'
. The 'oops' is optional; 'mistake' will translate to 'oopsmistake'.
$param1
... $param4
- Parameter values for %PARAM1% ... %PARAMn% variables in template, optional
$url
URL, e.g. "http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked¶m1=joe"
This might be used like this:
my $url = TWiki::Func::getOopsUrl($web, $topic, 'oopsmistake', 'I made a boo-boo'); TWiki::Func::redirectCgiQuery( undef, $url ); return 0;Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002) Since TWiki::Plugins::VERSION 1.1, the recommended approach is to throw an oops exception.
use Error qw( :try ); throw TWiki::OopsException($web, $topic, undef, 0, [ 'I made a boo-boo' ]);and let TWiki handle the cleanup.
$path
URL path of pub directory, e.g. "/pub"
Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
$query
CGI query object; or 0 if script is called as a shell script
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$key
- Session key
$value
Value associated with key; empty string if not set
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 200)
$key
- Session key
$value
- Value associated with key
setSessionValue
. $key
- name of value stored in session to be cleared. Note that you cannot clear AUTHUSER
.
sub initPlugin { TWiki::Func::getContext()->{'MyID'} = 1; ...This can be used in SecondPlugin.pm like this:
sub initPlugin { if( TWiki::Func::getContext()->{'MyID'} ) { ... } ...or in a template, like this:
%TMPL:DEF{"ON"}% Not off %TMPL:END% %TMPL:DEF{"OFF"}% Not on %TMPL:END% %TMPL:P{context="MyID" then="ON" else="OFF"}%or in a topic:
%IF{"context MyID" then="MyID is ON" else="MyID is OFF"}%Note: all plugins have an automatically generated context identifier if they are installed and initialised. For example, if the FirstPlugin? is working, the context ID 'FirstPlugin' will be set. Since: TWiki::Plugins::VERSION 1.1
$key
- Preferences key
$web
- Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
$value
Preferences value; empty string if not set
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
* Set COLOR = red
"MYPLUGIN_COLOR"
for $key
my $color = TWiki::Func::getPreferencesValue( "MYPLUGIN_COLOR" );
* Set WEBBGCOLOR = #FFFFC0
my $webColor = TWiki::Func::getPreferencesValue( 'WEBBGCOLOR', 'Sandbox' );
$NO_PREFS_IN_TOPIC
is enabled in the plugin, then
preferences set in the plugin topic will be ignored.
$key
- Plugin Preferences key w/o PLUGINNAME_ prefix.
$value
Preferences value; empty string if not set
Note: This function will will only work when called from the Plugin.pm file itself. it will not work if called from a sub-package (e.g. TWiki::Plugins::MyPlugin::MyModule)
Since: TWiki::Plugins::VERSION 1.021 (27 Mar 2004)
NOTE: As of TWiki4.1, if $NO_PREFS_IN_TOPIC
is enabled in the plugin, then
preferences set in the plugin topic will be ignored.
$key
- Preferences key
$web
- Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
$value
Preferences flag '1'
(if set), or "0"
(for preferences values "off"
, "no"
and "0"
)
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
* Set SHOWHELP = off
"MYPLUGIN_SHOWHELP"
for $key
my $showHelp = TWiki::Func::getPreferencesFlag( "MYPLUGIN_SHOWHELP" );
$NO_PREFS_IN_TOPIC
is enabled in the plugin, then
preferences set in the plugin topic will be ignored.
$key
- Plugin Preferences key w/o PLUGINNAME_ prefix.
"off"
, "no"
and "0"
, or values not set at all. True otherwise.
Note: This function will will only work when called from the Plugin.pm file itself. it will not work if called from a sub-package (e.g. TWiki::Plugins::MyPlugin::MyModule)
Since: TWiki::Plugins::VERSION 1.021 (27 Mar 2004)
NOTE: As of TWiki4.1, if $NO_PREFS_IN_TOPIC
is enabled in the plugin, then
preferences set in the plugin topic will be ignored.
$name
Name of tool, e.g. 'TWiki'
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
$name
Name, e.g. 'Main'
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
$name
Name, e.g. 'TWiki'
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
DefaultUserLogin
Return: $loginName
Default user name, e.g. 'guest'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$wikiName
Wiki Name, e.g. 'JohnDoe'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$wikiName
Wiki Name, e.g. "Main.JohnDoe"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$wikiName
- Wiki name, e.g. 'Main.JohnDoe'
or 'JohnDoe'
$loginName
Login name of user, e.g. 'jdoe'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$loginName
- Login name, e.g. 'jdoe'
$dontAddWeb
- Do not add web prefix if "1"
$wikiName
Wiki name of user, e.g. 'Main.JohnDoe'
or 'JohnDoe'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web
- Web name, required, e.g. 'Sandbox'
$type
- Access type, required, e.g. 'VIEW'
, 'CHANGE'
.
$wikiName
- WikiName of remote user, required, e.g. "PeterThoeny"
. If $wikiName
is '', 0 or undef
then access is always permitted.
$text
- Topic text, optional. If 'perl false' (undef, 0 or ''), topic $web.$topic
is consulted. $text
may optionally contain embedded %META:PREFERENCE
tags. Provide this parameter if: $meta
parameter.
$topic
- Topic name, required, e.g. 'PrivateStuff'
$web
- Web name, required, e.g. 'Sandbox'
$meta
- Meta-data object, as returned by readTopic
. Optional. If undef
, but $text
is defined, then access controls will be parsed from $text
. If defined, then metadata embedded in $text
will be ignored. This parameter is always ignored if $text
is undefined. Settings in $meta
override Set
settings in $text.
ThatWeb.ThisTopic
, then a call to checkAccessPermissions('SPIN', 'IncyWincy', undef, 'ThisTopic', 'ThatWeb', undef)
will return true
.
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
$filter
- spec of web types to recover
$filter
may also contain the word 'public' which will further filter
out webs that have NOSEARCHALL set on them.
'allowed' filters out webs the current user can't read.
For example, the deprecated getPublicWebList function can be duplicated
as follows:
my @webs = TWiki::Func::getListOfWebs( "user,public" );Since: TWiki::Plugins::VERSION 1.1
$web
- Web name, required, e.g. 'Sandbox'
$newWeb
is the name of the new web.
$baseWeb
is the name of an existing web (a template web). If the base web is a system web, all topics in it will be copied into the new web. If it is a normal web, only topics starting with 'Web' will be copied. If no base web is specified, an empty web (with no topics) will be created. If it is specified but does not exist, an error will be thrown.
$opts
is a ref to a hash that contains settings to be modified in
use Error qw( :try ); use TWiki::AccessControlException; try { TWiki::Func::createWeb( "Newweb" ); } catch Error::Simple with { my $e = shift; # see documentation on Error::Simple } catch TWiki::AccessControlException with { my $e = shift; # see documentation on TWiki::AccessControlException } otherwise { ... };Since: TWiki::Plugins::VERSION 1.1
use Error qw( :try ); use TWiki::AccessControlException; try { TWiki::Func::moveWeb( "Oldweb", "Newweb" ); } catch Error::Simple with { my $e = shift; # see documentation on Error::Simple } catch TWiki::AccessControlException with { my $e = shift; # see documentation on TWiki::AccessControlException } otherwise { ... };To delete a web, move it to a subweb of
Trash
TWiki::Func::moveWeb( "Deadweb", "Trash.Deadweb" );Since: TWiki::Plugins::VERSION 1.1
$web
- Web name, required, e.g. 'Sandbox'
@topics
Topic list, e.g. ( 'WebChanges', 'WebHome', 'WebIndex', 'WebNotify' )
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web
- Web name, optional, e.g. 'Main'
.
$topic
- Topic name, required, e.g. 'TokyoOffice'
, or "Main.TokyoOffice"
normalizeWebTopicName
.
Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
$web
Web name, e.g. "Main"
, or empty
$topic
Topic name, e.g. "MyTopic"
, or "Main.MyTopic"
( $oopsUrl, $loginName, $unlockTime )
- The $oopsUrl
for calling redirectCgiQuery(), user's $loginName
, and estimated $unlockTime
in minutes, or ( '', '', 0 ) if no lease exists. $script
The script to invoke when continuing with the edit
$web
Web name, e.g. "Main"
, or empty
$topic
Topic name, e.g. "MyTopic"
, or "Main.MyTopic"
$lock
1 to lease the topic, 0 to clear the lease=
edit
script
always takes out a lease.
It is impossible to fully lock a topic. Concurrent changes will be
merged.
Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
$web
- web for the topic
$topic
- topic name
$meta
- reference to TWiki::Meta object
$text
- text of the topic (without embedded meta-data!!!
\%options
- ref to hash of save options \%options
may include: dontlog | don't log this change in twiki log |
comment | comment for save |
minor | True if this is a minor change, and is not to be notified |
my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic ) $text =~ s/APPLE/ORANGE/g; TWiki::Func::saveTopic( $web, $topic, $meta, $text, { comment => 'refruited' } );Note: Plugins handlers ( e.g.
beforeSaveHandler
) will be called as
appropriate.
$web
- Web name, e.g. 'Main'
, or empty
$topic
- Topic name, e.g. 'MyTopic'
, or "Main.MyTopic"
$text
- Topic text to save, assumed to include meta data
$ignorePermissions
- Set to "1"
if checkAccessPermission() is already performed and OK
$dontNotify
- Set to "1"
if not to notify users of the change
$oopsUrl
Empty string if OK; the $oopsUrl
for calling redirectCgiQuery() in case of error
This method is a lot less efficient and much more dangerous than saveTopic
.
Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
my $text = TWiki::Func::readTopicText( $web, $topic ); # check for oops URL in case of error: if( $text =~ /^http.*?\/oops/ ) { TWiki::Func::redirectCgiQuery( $query, $text ); return; } # do topic text manipulation like: $text =~ s/old/new/g; # do meta data manipulation like: $text =~ s/(META\:FIELD.*?name\=\"TopicClassification\".*?value\=\")[^\"]*/$1BugResolved/; $oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text
$web
source web - required
$topic
source topic - required
$newWeb
dest web
$newTopic
dest topic
use Error qw( :try ); try { moveTopic( "Work", "TokyoOffice", "Trash", "ClosedOffice" ); } catch Error::Simple with { my $e = shift; # see documentation on Error::Simple } catch TWiki::AccessControlException with { my $e = shift; # see documentation on TWiki::AccessControlException } otherwise { ... };
$web
- Web name, optional, e.g. 'Main'
$topic
- Topic name, required, e.g. 'TokyoOffice'
$rev
- revsion number, or tag name (can be in the format 1.2, or just the minor number)
$attachment
-attachment filename
( $date, $user, $rev, $comment )
List with: ( last update date, login name of last user, minor part of top revision number ), e.g. ( 1234561, 'phoeny', "5" )
$date | in epochSec |
$user | Wiki name of the author (not login name) |
$rev | actual rev number |
$comment | WHAT COMMENT? |
$meta->getRevisionInfo
instead if you can - it is significantly
more efficient, and returns a user object that contains other user
information.
NOTE: prior versions of TWiki may under some circumstances have returned
the login name of the user rather than the wiki name; the code documentation
was totally unclear, and we have been unable to establish the intent.
However the wikiname is obviously more useful, so that is what is returned.
Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
$web
- web for topic
$topic
- topic
$time
- time (in epoch secs) for the rev
$web
- Web name, required, e.g. 'Main'
$topic
- Topic name, required, e.g. 'TokyoOffice'
$rev
- revision to read (default latest)
( $meta, $text )
Meta data object and topic text
$meta
is a perl 'object' of class TWiki::Meta
. This class is
fully documented in the source code documentation shipped with the
release, or can be inspected in the lib/TWiki/Meta.pm
file.
This method ignores topic access permissions. You should be careful to use checkAccessPermissions
to ensure the current user has read access to the topic.
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web
- Web name, e.g. 'Main'
, or empty
$topic
- Topic name, e.g. 'MyTopic'
, or "Main.MyTopic"
$rev
- Topic revision to read, optional. Specify the minor part of the revision, e.g. "5"
, not "1.5"
; the top revision is returned if omitted or empty.
$ignorePermissions
- Set to "1"
if checkAccessPermission() is already performed and OK; an oops URL is returned if user has no permission
$text
Topic text with embedded meta data; an oops URL for calling redirectCgiQuery() is returned in case of an error
This method is more efficient than readTopic
, but returns meta-data embedded in the text. Plugins authors must be very careful to avoid damaging meta-data. You are recommended to use readTopic instead, which is a lot safer..
Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
$web
- Web name, optional, e.g. Main
.
$topic
- Topic name, required, e.g. TokyoOffice
, or Main.TokyoOffice
$attachment
- attachment name, e.g.=logo.gif=
normalizeWebTopicName
.
Since: TWiki::Plugins::VERSION 1.1
$web
- web for topic
$topic
- topic
$name
- attachment name
$rev
- revision to read (default latest)
readTopic
. If the attachment does not exist, or cannot be read, undef
will be returned. If the revision is not specified, the latest version will
be returned.
View permission on the topic is required for the
read to be successful. Access control violations are flagged by a
TWiki::AccessControlException. Permissions are checked for the current user.
my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic ); my @attachments = $meta->find( 'FILEATTACHMENT' ); foreach my $a ( @attachments ) { try { my $data = TWiki::Func::readAttachment( $web, $topic, $a->{name} ); ... } catch TWiki::AccessControlException with { }; }Since: TWiki::Plugins::VERSION 1.1
$web
- web for topic
$topic
- topic to atach to
$attachment
- name of the attachment
$opts
- Ref to hash of options
$opts
may include:
dontlog | don't log this change in twiki log |
comment | comment for save |
hide | if the attachment is to be hidden in normal topic view |
stream | Stream of file to upload |
file | Name of a file to use for the attachment data. ignored if stream is set. Local file on the server. |
filepath | Client path to file |
filesize | Size of uploaded data |
filedate | Date |
try { TWiki::Func::saveAttachment( $web, $topic, 'image.gif', { file => 'image.gif', comment => 'Picture of Health', hide => 1 } ); } catch Error::Simple with { # see documentation on Error } otherwise { ... };Since: TWiki::Plugins::VERSION 1.1
$web
source web - required
$topic
source topic - required
$attachment
source attachment - required
$newWeb
dest web
$newTopic
dest topic
$newAttachment
dest attachment
use Error qw( :try ); try { # move attachment between topics moveAttachment( "Countries", "Germany", "AlsaceLorraine.dat", "Countries", "France" ); # Note destination attachment name is defaulted to the same as source } catch TWiki::AccessControlException with { my $e = shift; # see documentation on TWiki::AccessControlException } catch Error::Simple with { my $e = shift; # see documentation on Error::Simple };Since: TWiki::Plugins::VERSION 1.1
$name
- Template name, e.g. 'view'
$skin
- Comma-separated list of skin names, optional, e.g. 'print'
$text
Template text
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$name
- template file name
$skin
- comma-separated list of skins to use (default: current skin)
$web
- the web to look in for topics that contain templates (default: current web)
$def
- template name
$query
- CGI query object. If not given, the default CGI query will be used. In most cases you should not pass this parameter.
$contentLength
- Length of content
$query
- CGI query object. Ignored, only there for compatibility. The session CGI query object is used instead.
$url
- URL to redirect to
$passthru
- enable passthrough.
$passthru
parameter allows you to pass the parameters that were passed
to the current query on to the target URL, as long as it is another URL on the
same TWiki installation. If $passthru
is set to a true value, then TWiki
will save the current URL parameters, and then try to restore them on the
other side of the redirect. Parameters are stored on the server in a cache
file (see {PassthroughDir} in =configure
).
Note that if $passthru
is set, then any parameters in $url
will be lost
when the old parameters are restored. if you want to change any parameter
values, you will need to do that in the current CGI query before redirecting
e.g.
my $query = TWiki::Func::getCgiQuery(); $query->param(-name => 'text', -value => 'Different text'); TWiki::Func::redirectCgiQuery( undef, TWiki::Func::getScriptUrl($web, $topic, 'edit'), 1);
$passthru
does nothing if $url
does not point to a script in the current
TWiki installation.
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$header
to the HTML header (the tag).
This is useful for Plugins that want to include some javascript custom css. $id
- Unique ID to prevent the same HTML from being duplicated. Plugins should use a prefix to prevent name clashes (e.g EDITTABLEPLUGIN_JSCALENDAR)
$header
- the HTML to be added to the section. The HTML must be valid in a HEAD tag - no checks are performed.
$header
will be expanded before being inserted into the
section.
Note that this is not the same as the HTTP header, which is modified through the Plugins modifyHeaderHandler
.
Since: TWiki::Plugins::VERSION 1.1
example:
TWiki::Func::addToHEAD('PATTERN_STYLE','<link id="twikiLayoutCss" rel="stylesheet" type="text/css" href="%PUBURL%/TWiki/PatternSkin/layout.css" media="all" />')
%VARIABLES%
$text
- Text with variables to expand, e.g. 'Current user is %WIKIUSER%'
$topic
- Current topic name, e.g. 'WebNotify'
$web
- Web name, optional, e.g. 'Main'
. The current web is taken if missing
$text
Expanded text, e.g. 'Current user is TWikiGuest'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
See also: expandVariablesOnTopicCreation
$text
- Text to render, e.g. '*bold* text and =fixed font='
$web
- Web name, optional, e.g. 'Main'
. The current web is taken if missing
$text
XHTML text, e.g. '<b>bold</b> and <code>fixed font</code>'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
renderText()
$pre
- Text occuring before the TWiki link syntax, optional
$web
- Web name, required, e.g. 'Main'
$topic
- Topic name to link to, required, e.g. 'WebNotify'
$label
- Link label, required. Usually the same as $topic
, e.g. 'notify'
$anchor
- Anchor, optional, e.g. '#Jump'
$createLink
- Set to '1'
to add question linked mark after topic name if topic does not exist;'0'
to suppress link for non-existing topics
$text
XHTML anchor, e.g. '<a href='/cgi-bin/view/Main/WebNotify#Jump'>notify</a>'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$text
- text of the mail, including MIME headers
$retries
- number of times to retry the send (default 1)
To: liz@windsor.gov.uk From: serf@hovel.net CC: george@whitehouse.gov Subject: Revolution Dear Liz, Please abolish the monarchy (with King George's permission, of course) Thanks, A. PeasantLeave a blank line between the last header field and the message body. Since: TWiki::Plugins::VERSION 1.1
$wikiName
- wiki name of the user
$text
- the text to process
%DATE%
Signature-format date
%SERVERTIME%
See TWikiVariables
%GMTIME%
See TWikiVariables
%USERNAME%
Base login name
%WIKINAME%
Wiki name
%WIKIUSERNAME%
Wiki name with prepended web
%URLPARAM{...}%
- Parameters to the current CGI query
%NOP%
No-op
commonTagsHandler
. $var
- The name of the variable, i.e. the 'MYVAR' part of %MYVAR%. The variable name must match /^[A-Z][A-Z0-9_]*$/ or it won't work.
\&fn
- Reference to the handler function.
$syntax
can be 'classic' (the default) or 'context-free'. 'classic' syntax is appropriate where you want the variable to support classic TWiki syntax i.e. to accept the standard %MYVAR{ "unnamed" param1="value1" param2="value2" }%
syntax, as well as an unquoted default parameter, such as %MYVAR{unquoted parameter}%
. If your variable will only use named parameters, you can use 'context-free' syntax, which supports a more relaxed syntax. For example, %MYVAR{param1=value1, value 2, param3="value 3", param4='value 5"}%
sub handler(\%session, \%params, $topic, $web)where:
\%session
- a reference to the TWiki session object (may be ignored)
\%params
- a reference to a TWiki::Attrs object containing parameters. This can be used as a simple hash that maps parameter names to values, with _DEFAULT being the name for the default parameter.
$topic
- name of the topic in the query
$web
- name of the web in the query
sub initPlugin{ TWiki::Func::registerTagHandler('EXEC', \&boo); } sub boo { my( $session, $params, $topic, $web ) = @_; my $cmd = $params->{_DEFAULT}; return "NO COMMAND SPECIFIED" unless $cmd; my $result = `$cmd 2>&1`; return $params->{silent} ? '' : $result; } }would let you do this:
%EXEC{"ps -Af" silent="on"}%
Registered tags differ from tags implemented using the old TWiki approach (text substitution in commonTagsHandler
) in the following ways: commonTagsHandler
is only called later, when all system tags have already been expanded (though they are expanded again after commonTagsHandler
returns).
FRED
defines both %FRED{...}%
and also %FRED%
.
return '%SERVERTIME%';
). It won't work.
$alias
- The name .
\&fn
- Reference to the function.
sub handler(\%session)where:
\%session
- a reference to the TWiki session object (may be ignored)
TWiki::Func::registerRESTHandler('example', \&restExample);This adds the
restExample
function to the REST dispatch table
for the EmptyPlugin under the 'example' alias, and allows it
to be invoked using the URL
http://server:port/bin/rest/EmptyPlugin/example
note that the URL
http://server:port/bin/rest/EmptyPlugin/restExample
(ie, with the name of the function instead of the alias) will not work.
$searchString
- the search string, in egrep format
$web
- The web to search in
\@topics
- reference to a list of topics to search
\%option
- reference to an options hash
\%options
hash may contain the following options: type
- if regex
will perform a egrep-syntax RE search (default '')
casesensitive
- false to ignore case (defaulkt true)
files_without_match
- true to return files only (default false). If files_without_match
is specified, it will return on the first match in each topic (i.e. it will return only one match per topic, and will not return matching lines).
my $result = TWiki::Func::searchInWebContent( "Slimy Toad", $web, \@topics, { casesensitive => 0, files_without_match => 0 } ); foreach my $topic (keys %$result ) { foreach my $matching_line ( @{$result->{$topic}} ) { ...etcSince: TWiki::Plugins::VERSION 1.1
$filename
- Full path name of file
$text
Content of file, empty if not found
NOTE: Use this function only for the Plugin workarea, not for topics and attachments. Use the appropriate functions to manipulate topics and attachments.
Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
$filename
- Full path name of file
$text
- Text to save
$name
- Name of the expression to retrieve. See notes below
my $upper = TWiki::Func::getRegularExpression('upperAlpha'); my $alpha = TWiki::Func::getRegularExpression('mixedAlpha'); my $capitalized = qr/[$upper][$alpha]+/;Those expressions marked type 'RE' are precompiled regular expressions that can be used outside square brackets. For example:
my $webRE = TWiki::Func::getRegularExpression('webNameRegex'); my $isWebName = ( $s =~ m/$webRE/ );
Name | Matches | Type |
---|---|---|
upperAlpha | Upper case characters | String |
upperAlphaNum | Upper case characters and digits | String |
lowerAlpha | Lower case characters | String |
lowerAlphaNum | Lower case characters and digits | String |
numeric | Digits | String |
mixedAlpha | Alphabetic characters | String |
mixedAlphaNum | Alphanumeric characters | String |
wikiWordRegex | WikiWords | RE |
webNameRegex | User web names | RE |
anchorRegex | #AnchorNames | RE |
abbrevRegex | Abbreviations e.g. GOV, IRS | RE |
emailAddrRegex | email@address.com | RE |
tagNameRegex | Standard variable names e.g. %THIS_BIT% (THIS_BIT only) | RE |
$web
- Web name, identifying variable, or empty string
$topic
- Topic name, may be a web.topic string, required.
Input | Return |
---|---|
( 'Web', 'Topic' ) | ( 'Web', 'Topic' ) |
( '', 'Topic' ) | ( 'Main', 'Topic' ) |
( '', '' ) | ( 'Main', 'WebHome' ) |
( '', 'Web/Topic' ) | ( 'Web', 'Topic' ) |
( '', 'Web/Subweb/Topic' ) | ( 'Web/Subweb', 'Topic' ) |
( '', 'Web.Topic' ) | ( 'Web', 'Topic' ) |
( '', 'Web.Subweb.Topic' ) | ( 'Web/Subweb', 'Topic' ) |
( 'Web1', 'Web2.Topic' ) | ( 'Web2', 'Topic' ) |
configure
.
The symbols %USERSWEB%, %SYSTEMWEB%, %DOCWEB%, %MAINWEB% and %TWIKIWEB% can be used in the input to represent the web names set in $cfg{UsersWebName} and $cfg{SystemWebName}. For example:
Input | Return |
---|---|
( '%USERSWEB%', 'Topic' ) | ( 'Main', 'Topic' ) |
( '%SYSTEMWEB%', 'Topic' ) | ( 'TWiki', 'Topic' ) |
( '', '%DOCWEB%.Topic' ) | ( 'TWiki', 'Topic' ) |
$text
- Text to write; timestamp gets added
$text
- Text to write; timestamp gets added
$time
- Time in epoc seconds
$format
- Format type, optional. Default e.g. '31 Dec 2002 - 19:30'
. Can be '$iso'
(e.g. '2002-12-31T19:30Z'
), '$rcs'
(e.g. '2001/12/31 23:59:59'
, '$http'
for HTTP header format (e.g. 'Thu, 23 Jul 1998 07:21:56 GMT'
), or any string with tokens '$seconds, $minutes, $hours, $day, $wday, $month, $mo, $year, $ye, $tz'
for seconds, minutes, hours, day of month, day of week, 3 letter month, 2 digit month, 4 digit year, 2 digit year, timezone string, respectively
$timezone
- either not defined (uses the displaytime setting), 'gmtime', or 'servertime'
$text
Formatted time string
Note: | if you used the removed formatGmTime, add a third parameter 'gmtime' |
$text
- Word to test
$attr
- Attribute string
%params
Hash containing all parameters. The nameless parameter is stored in key _DEFAULT
Since: TWiki::Plugins::VERSION 1.025 (26 Aug 2004)
%TEST{ 'nameless' name1="val1" name2="val2" }%
{...}
to get: 'nameless' name1="val1" name2="val2"
%params
hash contains now: _DEFAULT => 'nameless'
name1 => "val1"
name2 => "val2"
$attr
- Attribute string
$name
- Name, optional
$value
Extracted value
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
%TEST{ 'nameless' name1="val1" name2="val2" }%
{...}
to get: 'nameless' name1="val1" name2="val2"
my $noname = TWiki::Func::extractNameValuePair( $text );
my $val1 = TWiki::Func::extractNameValuePair( $text, "name1" );
my $val2 = TWiki::Func::extractNameValuePair( $text, "name2" );
TWiki::Plugins
version in which the handler was first deprecated. For example, if we need to define the endRenderingHandler
for compatibility with TWiki::Plugins
versions before 1.1, we would add this to the plugin:
package TWiki::Plugins::SinkPlugin; use vars qw( %TWikiCompatibility ); $TWikiCompatibility{endRenderingHandler} = 1.1;If the currently-running TWiki version is 1.1 or later, then the handler will not be called and the warning will not be issued. TWiki with versions of
TWiki::Plugins
before 1.1 will still call the handler as required.
The following functions are retained for compatibility only. You should
stop using them as soon as possible.
getScriptUrl
instead.
Return: $path
URL path of TWiki scripts, e.g. "/cgi-bin"
WARNING: you are strongly recommended not to use this function, as the
{ScriptUrlPaths} URL rewriting rules will not apply to urls generated
using it.
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
getListOfWebs
instead.
Get list of all public webs, e.g. all webs that do not have the NOSEARCHALL
flag set in the WebPreferences
Return: @webs
List of all public webs, e.g. ( 'Main', 'Know', 'TWiki' )
Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
formatTime
instead.
Format the time to GM time $time
- Time in epoc seconds
$format
- Format type, optional. Default e.g. '31 Dec 2002 - 19:30'
, can be 'iso'
(e.g. '2002-12-31T19:30Z'
), 'rcs'
(e.g. '2001/12/31 23:59:59'
, 'http'
for HTTP header format (e.g. 'Thu, 23 Jul 1998 07:21:56 GMT'
)
$text
Formatted time string
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$dir
Data directory, e.g. '/twiki/data'
This function violates store encapsulation and is therefore deprecated.
Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
$dir/Web/TopicName
Return: $dir
Pub directory, e.g. '/htdocs/twiki/pub'
This function violates store encapsulation and is therefore deprecated.
Use readAttachment
and saveAttachment
instead.
Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
twiki/bin
and twiki/tools
directories. This topic describes the interfaces to some of those scripts. All scripts in the twiki/bin
directory can be called from the CGI (Common Gateway Interface) environment or from the command line. The scripts in the twiki/tools
directory can only be called from the command line.
twiki/bin
directory.
guest
).
twiki/bin
directory on the perl path to run the scripts from the command line. To avoid issues with file permissions, run the scripts as the web server user such as nobody
or www
.
Parameters are passed on the command line using '-name' - for example,
$ cd /usr/local/twiki/bin $ save -topic MyWeb.MyTopic -user admin -action save -text "New text of the topic"All parameters require a value, even if that is the empty string.
Parameter | Description | Default |
---|---|---|
topic | If this is set to a URL, TWiki will immediately redirect to that URL. Otherwise it overrides the URL and is taken as the topic name (you can pass Web.TopicName) | |
user | Command-line only; set the name of the user performing the action. Note: this usage is inherently insecure, as it bypasses webserver login constraints. For this reason only authorised users should be allowed to execute scripts from the command line. | |
skin | Overrides the default skin path (see TWikiSkins) | |
cover | Specifies temporary skin path to prepend to the skin path for this script only (see TWikiSkins) |
attach
upload
. This script is part of the transactions sequence executed when a file is uploaded from the browser. it just generates the "new attachment" page for a topic.
Parameter | Description | Default |
---|---|---|
filename | Name of existing attachment (if provided, this is a "manage attachment" action) | none (in which case this is a "new attachment" action) |
changes
changes
script can receive one parameter:
Parameter | Description | Default |
---|---|---|
minor | If 0, show only major changes. If 1, show all the changes (both minor and major) | 0 |
%SEARCH%
, while this script reads the changes
file in each web, making it much faster.
NOTE: The result from changes
script and the topic WebChanges can be different, if the changes
file is deleted from a web. In particular, in new installations the changes
script will return no results while the WebChanges topic will.
configure
configure
is the browser script used for inspection and configuration of the TWiki configuration. None of the parameters to this script are useable for any purpose except configure
. See configure.
edit
edit
scipt understands the following parameters, typically supplied by HTML input fields:
Parameter | Description | Default |
---|---|---|
action | Optional. Use the editaction template instead of the standard edit. If action=text, then hide the form. If action=form hide the normal text area and only edit the form. | |
onlynewtopic | If set, error if topic already exists | |
onlywikiname | If set, error if topic name is not a WikiWord | |
templatetopic | The name of the template topic, copied to get the initial content | |
text | Initial text for the topic | |
topicparent | The parent topic | |
formtemplate | Name of the form to instantiate in the topic. Overrides the form set in the templatetopic if defined. | |
contenttype | Optional parameter that defines the application type to write into the CGI header. Defaults to text/html . May be used to invoke alternative client applications | |
anyname | Any parameter can passed to the new topic; if the template topic contains %URLPARAM{"anyname"}% , it will be replaced by its value | |
breaklock | If set, any lease conflicts will be ignored, and the edit will proceed even if someone is already editing the topic. | |
redirectto | If the user continues from edit to save, and if the save process is successful, save will redirect to this topic or URL. The parameter value can be a TopicName , a Web.TopicName , or a URL.Note: Redirect to a URL only works if it is enabled in configure (Miscellaneous {AllowRedirectUrl} ). |
Status
the parameter name is Status
. X
characters in the topic name will be converted on save to a number such that the resulting topic name is unique in the target web.
EDIT_SKIN
, which is used as the value of the cover
parameter in edit
URLs. This allows you to override the default edit skin on a web, topic or user basis.
login
Parameter | Description | Default |
---|---|---|
origurl | URL that was being accessed when an access violation occurred. the login process will redirect to this URL if it is successful | none |
username | username of user logging in | none |
password | password of user logging in | none |
logon
manage
Parameter | Description | Default |
---|---|---|
action | One of createweb , deleteUserAccount , editSettings or saveSettings | none |
action=createweb
Parameter | Description | Default |
---|---|---|
newweb | Name of the new web | '' |
baseweb | Name of the web to copy to create the new web | '' |
webbgcolor | value for WEBBGCOLOR | '' |
sitemapwhat | Value for SITEMAPWHAT | '' |
sitemapuseto | Value for SITEMAPUSETO | '' |
nosearchall | Value for NOSEARCHALL | '' |
action=deleteUserAccount
Parameter | Description | Default |
---|---|---|
password | Users' password | none |
action=editSettings
action=bulkRegister
Parameter | Description | Default |
---|---|---|
OverwriteHomeTopics | Whether to overwrite existing home topics or not | false |
EmailUsersWithDetails | Whether to mail registered users or not | false |
LogTopic | Topic to save the log in | Same as topic name, with 'Result' appended. |
action=saveSettings
Parameter | Description | Default |
---|---|---|
text | Text of the topic | '' |
originalrev | Revision that the edit started on | Most recent revision |
oops
oops
templates are used with the oops
script to generate system messages. This is done to make internationalisation or other local customisations simple.
The oops
script supports the following parameters:
Parameter | Description | Default |
---|---|---|
template | Name of the template file to display | |
def | Optional, can be set to the name of a single definition within template . This definition will be instantiated in the template wherever %INSTANTIATE% is seen. This lets you use a single template file for many messages. For an example, see oopsmanagebad.tmpl . | |
paramN | Where N is an integer from 1 upwards. These values will be substituted into template for %PARAM1% etc. |
passwd
Parameter | Description | Default |
---|---|---|
action | one of changePassword or resetPassword | none |
manage
, action=changePassword
.
action=changePassword
Parameter | Description | Default |
---|---|---|
username | Username | |
oldpassword | Existing password (plain text) | |
password | New password (plain text) | |
passwordA | New password confirmation (plain text) | |
TopicName | ? |
preview
save
script.
rdiff
Parameter | Description | Default |
---|---|---|
rev1 | the higher revision | |
rev2 | the lower revision | |
render | the rendering style {sequential, sidebyside, raw, debug} | DIFFRENDERSTYLE, sequential |
type | {history, diff, last} history diff, version to version, last version to previous | diff |
context | number of lines of context |
register
Parameter | Description | Default |
---|---|---|
action | register or verify or resetPassword or approve |
rename
Parameter | Description | Default |
---|---|---|
skin | skin(s) to use | |
newweb | new web name | |
newtopic | new topic name | |
breaklock | ||
attachment | ||
confirm | if defined, requires a second level of confirmation | |
currentwebonly | if defined, searches current web only for links to this topic | |
nonwikiword | if defined, a non-wikiword is acceptable for the new topic name |
resetpasswd
Parameter | Description | Default |
---|---|---|
LoginName | list of usernames to reset | none - error if not set |
Introduction | message to be sent alongside the reset, most often used to announce to the user that they have been given an account. | '' |
rest
TWiki::Func::registerRESTHandler
method. The rest
script will print the result directly to the browser unless the endPoint
parameter is specified, in which case it will output a redirect to the given topic.
The rest
script supports the following parameters:
username | If TemplateLogin , or a similar login manager not embedded in the web server, is used, then you need to pass a username and password to the server. The username and password parameters are used for this purpose. |
password | See username |
topic | If defined as the full name (including web) of a topic, then when the script starts up plugins will be passed this as the "current" topic. If not defined, then %USERWEB%.WebHome will be passed to plugins. |
endPoint | Where to redirect the response once the request is served, in the form "Web.Topic" |
rest
script should always require authentication in any TWiki that has logins. Otherwise there is a risk of opening up major security holes. So make sure you add it to the list of authenticated scripts if you are using ApacheLogin
.
rest
script assumes that it will be called with URL in the form:
http://my.host/bin/rest/<subject>/<verb>
where <subject>
must be the WikiWord name of one of the installed TWikiPlugins, and the <verb>
is the alias for the function registered using the TWiki::Func::registerRESTHandler
method. The <subject>
and <verb>
are then used to lookup and call the registered function.
<subject>
and <verb>
are checked for illegal characters exactly in the same way as the web and topic names.
As an example, the EmptyPlugin has registered a function to be used with the rest
script under the subject EmptyPlugin and the verb example. Click below to see the rest
script in action (run as TWikiGuest).
Call the Plugin
Note that for Plugins to register REST handlers, they must be enabled in configure
.
save
save
script performs a range of save-related functions, as selected by the action
parameter.
Parameter | Description | Default |
---|---|---|
action_save=1 | default; save, return to view, dontnotify is off | |
action_quietsave=1 | save, and return to view, dontnotify is on | |
action_checkpoint | save and redirect to the edit script, dontnotify is on | |
action_cancel | exit without save, return to view | |
action_preview | preview edited text | |
action_addform | Redirect to the "change form" page. | |
action_replaceform... | Redirect to the "change form" page. | |
action_delRev | Administrators only delete the most recent revision of the topic - all other parameters are ignored. You have to be a member of TWikiAdminGroup to use this, and not all store implementations will support it. | |
action_repRev | Administrators only replace the text of the most recent revision of the topic with the text in the text parameter. text must included embedded meta-data tags. All other parameters are ignored. You have to be a member of TWikiAdminGroup to use this, and not all store implementations will support it. | |
onlynewtopic | If set, error if topic already exists | |
onlywikiname | If set, error if topic name is not a WikiWord | |
dontnotify | if defined, suppress change notification | |
templatetopic | Name of a topic to use as a template for the text and form | |
text | New text of the topic | |
forcenewrevision | if set, forces a revision even if TWiki thinks one isn't needed | |
topicparent | If 'none' remove any current topic parent. If the name of a topic, set the topic parent to this. | |
formtemplate | if defined, use the named template for the form | |
editaction | When action is checkpoint , add form or replace form... , this is used as the action parameter to the edit script that is redirected to after the save is complete. | |
originalrev | Revision on which the edit started. | |
edit | The script to use to edit the topic when action is checkpoint | edit |
editparams | The parameter string to use to edit the topic | |
redirectto | The save process will redirect to this topic or URL if it is successful. (Typically this would be the URL that was being viewed when edit was invoked). The parameter value can be a TopicName , a Web.TopicName , or a URL.Note: Redirect to a URL only works if it is enabled in configure (Miscellaneous {AllowRedirectUrl} ). | view topic being edited |
oops
page.
The parameters are interpreted in according to the following rules.
X
characters in the topic name will be converted to a number such that the resulting topic name is unique in the target web.
save
, checkpoint
, quietsave
, or preview
: text
parameter, if it is defined, templatetopic
, if it is defined,
formtemplate
, if defined templatetopic
, if defined,
templatetopic
, if defined,
text
and originalrev
is > 0 and is not the same as the revision number of the most recent revision. If merging is enabled both the topic and the meta-data are merged.
Form field values are passed in parameters named 'field' - for example, if I have a field Status
the parameter name is Status
.
search
%SEARCH%
functionality driven by the following CGI parameters:
Parameter: | Description: | Default: |
---|---|---|
"text" | Search term. Is a keyword search, literal search or regular expression search, depending on the type parameter. SearchHelp has more | required |
search="text" | (Alternative to above) | N/A |
web="Name" web="Main, Know" web="all" | Comma-separated list of webs to search. See TWikiVariables#VarSEARCH for more details. | Current web |
topic="WebPreferences" topic="*Bug" | Limit search to topics: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. | All topics in a web |
excludetopic="Web*" excludetopic="WebHome, WebChanges" | Exclude topics from search: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. | None |
type="keyword" type="literal" type="regex" | Do a keyword search like soap "web service" -shampoo ; a literal search like web service ; or RegularExpression search like soap;web service;!shampoo | %SEARCHVAR- DEFAULTTYPE% preferences setting (literal) |
scope="topic" scope="text" scope="all" | Search topic name (title); the text (body) of topic; or all (both) | "text" |
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 |
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 |
nototal="on" | Do not show number of topics found | Show number |
zeroresults="off" | Suppress all output if there are no hits | zeroresults="on" , displays: "Number of topics: 0" |
noempty="on" | Suppress results for webs that have no hits. | Show webs with no hits |
header="..." format="..." | Custom format results: see FormattedSearch for usage, variables & examples | Results in table |
expandvariables="on" | Expand variables before applying a FormattedSearch on a search hit. Useful to show the expanded text, e.g. to show the result of a SpreadSheetPlugin %CALC{}% instead of the formula | Raw text |
multiple="on" | Multiple hits per topic. Each hit can be formatted. The last token is used in case of a regular expression ";" and search | Only one hit per topic |
nofinalnewline="on" | If on , the search variable does not end in a line by itself. Any text continuing immediately after the search tag on the same line will be rendered as part of the table generated by the search, if appropriate. | off |
separator=", " | Line separator between hits | Newline "$n" |
statistics
Parameter | Description | Default |
---|---|---|
webs | comma-separated list of webs to run stats on | all accessible webs |
logdate | YYYYMM to generate statistics for | current month |
twiki
upload
multipart/form-data
format.
Parameter | Description | Default |
---|---|---|
hidefile | if defined, will not show file in attachment table | |
filepath | local (client) path name of the file being uploaded. This is used to look up the data for the file in the HTTP query. | |
filename | deprecated, do not use | |
filecomment | Comment to associate with file in attachment table | |
createlink | if defined, will create a link to file at end of topic | |
changeproperties | if defined, this is a property change operation only - no file will be uploaded. | null |
curl
to upload files from the command line using this script.
view
Parameter | Description | Default |
---|---|---|
raw=on | Shows the text of the topic in a scrollable textarea | |
raw=debug | As raw=on , but also shows the metadata (forms etc) associated with the topic. | |
raw=text | Shows only the source of the topic, as plain text (Content-type: text/plain). Only shows the body text, not the form or other meta-data. | |
raw=all | Shows only the source of the topic, as plain text (Content-type: text/plain), with embedded meta-data. This may be useful if you want to extract the source of a topic to a local file on disc. | |
section | Allows to view only a part of the topic delimited by a named section (see VarSTARTSECTION). If the given section is not present, no topic content is displayed. | &nb |