Web | Sitemap | VIEW | CHANGE | RENAME | |||
---|---|---|---|---|---|---|---|
Listed | DENY | ALLOW | DENY | ALLOW | DENY | ALLOW | |
![]() ![]() |
on | TWikiAdminGroup, TWikiRegistrationAgent, AAOGeneralGroup | TWikiAdminGroup, AAOGeneralGroup | ||||
![]() ![]() |
on | TWikiAdminGroup | TWikiAdminGroup | ||||
![]() ![]() |
on | * | TWikiAdminGroup, AAOGeneralGroup | * | TWikiAdminGroup |
Main
web. To create a new group, visit TWikiGroups and enter the name of the new group ending in Group
into the "new group" form field. This will create a new group topic with two important settings: Set GROUP = < list of Users and/or Groups >
Set ALLOWTOPICCHANGE = < list of Users and/or Groups >
Set GROUP = SomeUser, OtherUser, SomeGroup
Set ALLOWTOPICCHANGE = MarketingGroup
TWikiAdminGroup
. The system administrator may have chosen a different name for this group if your local TWiki uses an alternate group mapping manager but for simplicity we will use the default name TWikiAdminGroup in the rest of this topic.
You can create new administrators simply by adding them to the TWikiAdminGroup topic. For example, Set GROUP = RobertCailliau, TimBernersLee
Set DENYWEBVIEW = < comma-delimited list of Users and Groups >
Set ALLOWWEBVIEW = < comma-delimited list of Users and Groups >
Set DENYWEBCHANGE = < comma-delimited list of Users and Groups >
Set ALLOWWEBCHANGE = < comma-delimited list of Users and Groups >
Set DENYWEBRENAME = < comma-delimited list of Users and Groups >
Set ALLOWWEBRENAME = < comma-delimited list of Users and Groups >
Set ALLOWWEBVIEW = Main.MarketingGroup
ALLOWWEBVIEW
set, this will also apply to the subweb. Also note that you will need to ensure that the parent web's FINALPREFERENCES
does not include the access control settings listed above. Otherwise you will not be able override the parent web's access control settings in sub-webs.
Creation and renaming of sub-webs is controlled by the WEBCHANGE setting on the parent web (or ROOTCHANGE for root webs). Renaming is additionally restricted by the setting of WEBRENAME in the web itself.
Note: If you restrict access to the Main, make sure to add the TWikiRegistrationAgent
so that users can register. Example: Set ALLOWWEBCHANGE = TWikiAdminGroup, TWikiRegistrationAgent
Set DENYTOPICVIEW = < comma-delimited list of Users and Groups >
Set ALLOWTOPICVIEW = < comma-delimited list of Users and Groups >
Set DENYTOPICCHANGE = < comma-delimited list of Users and Groups >
Set ALLOWTOPICCHANGE = < comma-delimited list of Users and Groups >
Set DENYTOPICRENAME = < comma-delimited list of Users and Groups >
Set ALLOWTOPICRENAME = < comma-delimited list of Users and Groups >
Set ALLOWTOPICVIEW = Main.MarketingExecGroup
Set ALLOWTOPICVIEW = Main.AllUsersGroup
Set ALLOWTOPICVIEW = Main.AllAuthUsersGroup
Set ALLOWTOPICOPERATION = Main.AllUsersGroup
tools/eliminate_emptydenytopic
is provided.
After upgrading from pre 6.0 to post 6.0, you need to run it.
Set ALLOWTOPICVIEW =
viewfile
script, which honors the TWiki access controls settings to topics. See the notes below for implications.
The preferred method to secure attachments is by editing the twiki.conf
file to include:
ScriptAlias /do /filesystem/path/to/twiki/bin Alias /pub/TWiki /filesystem/path/to/twiki/pub/TWiki Alias /pub/Sandbox /filesystem/path/to/twiki/pub/Sandbox ScriptAlias /pub /filesystem/path/to/twiki/bin/viewfileNotes:
viewfile
script. The TWiki web and Sandbox web are excluded for performance reasons.
viewfile
script sets the mime type based upon file name suffix. Unknown types are served as text/plain which can result in corrupt files.
Set DENYROOTCHANGE = < comma-delimited list of Users and Groups >
Set ALLOWROOTCHANGE = < comma-delimited list of Users and Groups >
ROOTCHANGE
access to rename an existing top-level web. You just need WEBCHANGE
in the web itself.
Set DENYTOPIC =
) canCreateWeb($cUID, $web)
method of the user mapping manager is called if the method exists.
If it returns true, TWiki goes ahead and create the web without checking access control variables.
Please read AllowWebCreateByUserMappingManager for more details.
DYNAMIC_ACCESS_CONTROL
'on' at WebPreferences of the web, TWiki variables in access control variables mentioned above are expanded.
* Set DYNAMIC_ACCESS_CONTROL = on * Set ALLOWWEBCHANGE = %IF{"'%CALCULATE{$SUBSTRING(%TOPIC%, -6, 6)}%' = 'Public'" then="%WIKINAME%" else="CroniesGroup"}%
* Set DYNAMIC_ACCESS_CONTROL = on * Set ALLOWWEBVIEW = %IF{"'%CALCULATE{$SUBSTRING(%TOPIC%, 1, 6)}%' = 'ReqEnt' and '%FORMFIELD{Requestor}%' != '%WIKINAME%'" then="SupportGroup" else="%WIKINAME%"}%Specifically the following access control variables are subject to TWiki variable expansion in their values.
* Set DYNAMIC_ACCESS_CONTROL = on * Set MEMBERS = JaneSmith, JoeSchmoe * Set ALLOWWEBVIEW = %MEMBERS%This is not a good way to use dynamic access control but it does restrict access only to those listed in MEMBERS. However, access control doesn't work as expected when WebA.TopicB is accessed from WebC.TopicD by
%INCLUDE{WebA.TopicB}%
or other variables.
This is because %MEMBERS%
is defined in WebA and may have a different value in other webs.
You may think the following lines cheat the access control on WebA but actually not.
* Set MEMBERS = %WIKINAME% %INCLUDE{WebA.TopicB}%This is because when a topic (e.g. WebC.TopicD) is accessed from browser and the topic refers to another topic in a different web (e.g. WebA.TopicB) and the different web employs dynamic access control, access to another topic is defined being on the safer side.
* Set MEMBERS = JaneSmith, JoeSchmoe * Set ALLOWTOPICVIEW = %MEMBERS%[This is not a good way to use dynamic access control
lib/LocalSite.cfg
$TWiki::cfg{DemoteUserPreferences}= 1;and having the following line on your WebPreferences and then finalise
DENYUSERPREFEENCES
.
* Set DENYUSERPREFEENCES = allPlease read TWikiVariables#ControllingUserLevelPrefsOverride for details. Again by default, predefined variables such as
%IF{...}%
can be overridden by preferences variables.
If user preferences are disabled, ordinary users cannot attack using user preferences, but topic level preferences may cause unexpected consequences.
As such, all predefined variables need to be made un-overridable by having the following line on WebPreferences and then finalise OVERRIDABLEPREDEFINEDVARIABLES
.
* Set OVERRIDABLEPREDEFINEDVARIABLES =Please read TWikiVariables#PredefinedVariables for details.
TOPIC_ACCESS_CONTACT
varialbe on WebPreferences. e.g.
* Set TOPIC_ACCESS_CONTACT = If you need to access this site, please apply [[Main.AccessForm][here]]Please note that setting it on a topic other than WebPreferences does not take effect. This is a limitation of the current implementation.
USER:userid
and LDAPGROUP:group-name
and use them for access control. For example:
* Set ALLOWWEBCHANGE = UID:buzz, LDAPGROUP:foo-barIn a large organization, TWiki may need to depend on user and group data provided by its infrastructure. Custom user/group notations are handy in such situations though it's not trivial to implement. Please read here for details.
backuprestore
, configure
, login
, logon
and resetpasswd
with the following configure setting: $TWiki::cfg{AuthScripts} = 'attach, changes, edit, manage, oops, preview, rdiff, rdiffauth, register, rename, rest, save, search, twiki_cgi, upload, statistics, view, viewauth, viewfile';
twiki/bin
also to the {AuthScripts}
configure setting. twiki/bin
and twiki/pub
directories to all but valid users. In the Apache config file for TWiki (twiki.conf
or .htaccess
), replace the <FilesMatch "(attach|edit|...
section with this:
<FilesMatch ".*"> require valid-user </FilesMatch>Notes:
Set DENYWEBVIEW = < list of Users and Groups >
Set ALLOWWEBVIEW = < list of Users and Groups >
DENYWEBVIEW
is evaluated before ALLOWWEBVIEW
. Access is denied if the authenticated person is in the DENYWEBVIEW
list, or not in the ALLOWWEBVIEW
list. Access is granted if DENYWEBVIEW
and ALLOWWEBVIEW
are not defined.
Edit topic preference settings
under More topic actions
menu. Preferences set in this manner are not visible in the topic text, but take effect nevertheless. Access control settings added as topic preference settings are stored in the topic meta data and they override settings defined in the topic text.
Alternatively, place them in HTML comment markers, but this exposes the access setting during ordinary editing.
<!--
* Set DENYTOPICCHANGE = Main.SomeGroup
-->
all webs
search option from accessing obfuscated webs. Do so by enabling the NOSEARCHALL
variable in WebPreferences: Set NOSEARCHALL = on
$TWiki::cfg{Access}{Topic}{WebAutomation} = { DENYCHANGE => 'Main.AllUsersGroup', };In addition to
ALLOWCHANGE
, you can sepcify DENYCHANGE
, ALLOWVIEW
, DENYVIEW
, ALLOWRENAME
, and DENYRENAME
as follows.
$TWiki::cfg{Access}{Topic}{SpecialTopic} = { DENYVIEW => 'JoeSchmoe', ALLOWVIEW => 'FooGroup', };
$TWiki::cfg{Access}{Topic}{TOPICNAME}
has precedence over DENYTOPIC*
and ALLOWTOPIC*
.
For example, if the configuration for WebAutomation is there as above, there is no way to allow non-adminsitrators to change the WebAutomation topic of any web.
As a way to configure access control, this may look crude.
The reason why configured this way is that this can be part of plugin/add-on/contrib's configuration.
For example, Config.spec
of AutomationAddOn would have the following lines, with which proper access control to WebAutomation topics is implemented without the administrator knowing it.
$TWiki::cfg{Access}{Topic}{WebAutomation} = { DENYCHANGE => 'Main.AllUsersGroup', };
.tmpl
.
They are usually HTML with embedded template directives.
The directives are expanded when TWiki wants to generate a user interface screen.
%TMPL:<key>%
and %TMPL:<key>{"attr"}%
.
%TMPL:INCLUDE{"file"}%
: Includes a template file. The file is found as described below.
%TMPL:DEF{"block"}%
: Define a block. All text between this and the next %TMPL:END%
directive is removed and saved for later use with %TMPL:P
.
%TMPL:END%
: Ends a block definition.
%TMPL:P{"var"}%
: Includes a previously defined block.
%{...}%
: is a comment.
twiki.tmpl
master template, like twiki.print.tmpl
, that redefines the header and footer.
%TMPL:DEF{"x"}% x%P%z%TMPL:END%
then %TMPL:P{"x" P="y"}%
will expand to xyz
.
Note that parameters can simply be ignored; for example, %TMPL:P{"x"}%
will expand to x%P%z.
Any alphanumeric characters can be used in parameter names.
You are highly recommended to use parameter names that cannot be confused with TWikiVariables.
Note that three parameter names, context
, then
and else
are reserved.
They are used to support a limited form of "if" condition that you can use to select which of two templates to use, based on a context identifier:
%TMPL:DEF{"link_inactive"}%<input type="button" disabled value="Link>%TMPL:END% %TMPL:DEF{"link_active"}%<input type="button" onclick="link()" value="Link" />%TMPL:END% %TMPL:P{context="inactive" then="inactive_link" else="active_link"}% for %CONTEXT%When the "inactive" context is set, then this will expand the "link_inactive" template; otherwise it will expand the "link_active" template. See IfStatements for details of supported context identifiers.
twiki/templates/view.tmpl
is the default template file for the twiki/bin/view
script.
You can save templates in other directories as long as they are listed in the {TemplatePath}
configuration setting.
The {TemplatePath}
is defined in the Miscellaneous section of the configure page.
You can also save templates in user topics (IF there is no possible template match in the templates
directory).
The {TemplatePath}
configuration setting defines which topics will be accepted as templates.
Templates that are included with an explicit '.tmpl'
extension are looked for only in the templates/
directory.
For instance %TMPL:INCLUDE{"example.tmpl"}%
will only return templates/example.tmpl
, regardless of {TemplatePath}
and SKIN settings.
The out-of-the-box setting of {TemplatePath}
supports the following search order to determine which template file or topic to use for a particular script or %TMPL:INCLUDE{"script"}%
statement.
The skin path is set as described in TWikiSkins.
view
, edit
View
dragon
, pattern
. All skins are checked at each stage, in the order they appear in the skin path.
Dragon
example
template file will be searched for in the following places, when the current web is Thisweb
and the skin path is print,pattern
:
templates/Thisweb/example.print.tmpl
deprecated; don't rely on it
templates/Thisweb/example.pattern.tmpl
deprecated; don't rely on it
templates/example.print.tmpl
templates/example.pattern.tmpl
templates/Thisweb/example.tmpl
deprecated; don't rely on it
templates/example.tmpl
Thisweb.PrintSkinExampleTemplate
Thisweb.PatternSkinExampleTemplate
Thisweb.ExampleTemplate
TWiki.PrintSkinExampleTemplate
TWiki.PatternSkinExampleTemplate
TWiki.ExampleTemplate
view
and edit
scripts, for example when a topic-specific template is required. Two preference variables can be used to override the templates used: VIEW_TEMPLATE
sets the template to be used for viewing a topic
EDIT_TEMPLATE
sets the template for editing a topic.
view
and edit
respectively. The template search order is as specified above.
{TemplatePath}
so that another directory, such as the %USERSWEB%
appears at the front. You can then put your own templates into that directory or web and these will override the standard templates. (Note that such will increase the lookup time for templates by searching your directory first.)
%TMPL:INCLUDE{"twiki"}%
, the templating system will include the next twiki.SKIN in the skin path.
For example, to create a customization of pattern skin, where you only want to over-ride the breadcrumbs for the view script, you can create only a view.yourlocal.tmpl:
%TMPL:INCLUDE{"view"}% %TMPL:DEF{"breadcrumb"}% We don't want any crumbs %TMPL:END%and then set SKIN=yourlocal,pattern The default
{TemplatePath}
will not give you the desired result if you put these statements in the topic Thisweb.YourlocalSkinViewTemplate
. The default {TemplatePath}
will resolve the request to the template/view.pattern.tmpl
, before it gets to the Thisweb.YourlocalSkinViewTemplate
resolution. You can make it work by prefixing the {TemplatePath}
with: $web.YourlocalSkin$nameTemplate
.
twiki.tmpl
is the default master template. It defines the following sections.
Template variable: | Defines: |
---|---|
%TMPL:DEF{"sep"}% |
"|" separator |
%TMPL:DEF{"htmldoctype"}% |
Start of all HTML pages |
%TMPL:DEF{"standardheader"}% |
Standard header (ex: view, index, search) |
%TMPL:DEF{"simpleheader"}% |
Simple header with reduced links (ex: edit, attach, oops) |
%TMPL:DEF{"standardfooter"}% |
Footer, excluding revision and copyright parts |
Topic Name: | What it is: |
---|---|
WebTopicViewTemplate | Alert page shown when you try to view a nonexistent topic. This page is usually used as a prompt to help you create a new topic. |
WebTopicNonWikiTemplate | Alert page shown when you try to view a nonexistent topic with a non-WikiName. Again, this page is used as a prompt to help you create the new topic. |
WebTopicEditTemplate | Default text used in a new topic. |
<MyCustomNamed>Template | Whenever you create a topic ending in the word "Template", it is automatically added to the list of available templates in the "Use Template" drop down field on the WebCreateNewTopic page. |
edit
script, TWiki locates a topic to use as a content template according to the following search order: templatetopic
CGI parameter Variable: | Description: |
---|---|
%DATE% |
Signature format date. See VarDATE |
%GMTIME% |
Date/time. See VarGMTIME |
%GMTIME{...}% |
Formatted date/time. See VarGMTIME2 |
%NOP% |
A no-operation variable that gets removed. Useful to prevent a SEARCH from hitting an edit template topic; also useful to escape a variable, such as %URLPA%NOP%RAM{...}% escaping URLPARAM |
%STARTSECTION{type="templateonly"}% |
Text that gets removed when a new topic based on the template is created. See notes below. |
%SERVERTIME% |
Date/time. See VarSERVERTIME |
%SERVERTIME{...}% |
Formatted date/time. See VarSERVERTIME2 |
%USERNAME% |
Login name of user who is instantiating the new topic, e.g. guest |
%URLPARAM{"name"}% |
Value of a named URL parameter. See VarURLPARAM. |
%WIKINAME% |
WikiName of user who is instantiating the new topic, e.g. TWikiGuest |
%WIKIUSERNAME% |
User name of user who is instantiating the new tpoic, e.g. Main.TWikiGuest |
%STARTSECTION{type="templateonly"}% ... %ENDSECTION{type="templateonly"}%
section. For example, you might want to write this in the template topic:
%STARTSECTION{type="templateonly"}% This template can only be changed by: * Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup %ENDSECTION{type="templateonly"}%This will restrict who can edit the template topic, but will be removed when a new topic based on that template topic is created.
%NOP%
can be used to prevent expansion of TWiki variables that would otherwise be expanded during topic creation. For example, escape %SERVERTIME%
with %SER%NOP%VERTIME%
.
type="expandvariables"
section in the template topic, such as:
...Example: If you have the following content in a template topic:
* %SYSTEMWEB%.ATasteOfTWiki - view a short introductory presentation on TWiki for beginners * %SYSTEMWEB%.WelcomeGuest - starting points on TWiki * %SYSTEMWEB%.TWikiUsersGuide - complete TWiki documentation * Sandbox.%HOMETOPIC% - try out TWiki on your own * Sandbox.%TOPIC%Sandbox - just for meyou will get this raw text in new topics based on that template topic:
* TWiki.ATasteOfTWiki - view a short introductory presentation on TWiki for beginners * TWiki.WelcomeGuest - starting points on TWiki * TWiki.TWikiUsersGuide - complete TWiki documentation * Sandbox.WebHome - try out TWiki on your own * Sandbox.JimmyNeutronSandbox - just for me
EOTC__
(EOTC followed by two underscores; EOTC stands for Expand On Topic Creation), you can have the variable expanded.
Here's an example.
%EOTC__SEARCH{"." topic="%URLPARAM{prefix}%*" nonoise="on" format="$percntINCLUDE{$topic}$percnt" separator="$n" }%This yields a series of
%INCLUDE{...}%
s, which are not expanded.
This is not achievable by an expandvariables
section.
formtemplate
CGI parameter to the edit
script to specify the name of a form to attach.
See TWikiScripts for information about all the other parameters to edit
.
AUTOINC<n>
to the topic name in the edit and save scripts, and it will be replaced with an auto-incremented number on topic save. <n>
is a number starting from 0, and may include leading zeros. Leading zeros are used to zero-pad numbers so that auto-incremented topic names can sort properly. Deleted topics are not re-used to ensure uniqueness of topic names. That is, the auto-incremented number is always higher than the existing ones, even if there are gaps in the number sequence.
Examples: BugAUTOINC0
- creates topic names Bug0
, Bug1
, Bug2
, ... (does not sort properly)
ItemAUTOINC0000
- creates topic names Item0000
, Item0001
, Item0002
, ... (sorts properly up to 9999)
DocIDAUTOINC10001
- start with DocID10001
, DocID10002
, ... (sorts properly up to 99999; auto-links)
AUTOINC<n>
are preserved, but are not taken into account when calculating the next increment. Use this to create topic names that have a unique identifier (serial number) and a descriptive text.
Example: BlogAUTOINC0001-my-first-blog
- creates topic name Blog0001-my-first-blog
BlogAUTOINC0001-my-crazy-cats
- creates topic name Blog0002-my-crazy-cats
BlogAUTOINC0001-fondue-recipe
- creates topic name Blog0003-fondue-recipe
[[%SCRIPTURLPATH{edit}%/%WEB%/BugIDAUTOINC00001?templatetopic=BugTemplate;topicparent=%TOPIC%;t=%SERVERTIME{"$day$hour$min$sec"}%][Create new item]]
templatetopic
specifies ExampleTopicTemplate as the template topic to use. Here is the raw text of the form:
%EDITFORMFIELD{ "new" type="start" action="edit" topic="Sandbox.%TOPIC%" }% * New example topic: %EDITFORMFIELD{ "topic" type="text" value="ExampleTopicAUTOINC0001" size="30" }% %EDITFORMFIELD{ "templatetopic" type="hidden" value="%SYSTEMWEB%.ExampleTopicTemplate" }% %EDITFORMFIELD{ "topicparent" type="hidden" value="%HOMETOPIC%" }% %EDITFORMFIELD{ "onlywikiname" type="hidden" value="on" }% %EDITFORMFIELD{ "onlynewtopic" type="hidden" value="on" }% %EDITFORMFIELD{ "form" type="submit" value="Create" }% %EDITFORMFIELD{ "form" type="end" }%Here is the equivalent form using a hand-crafted HTML form:
<form name="new" action="%SCRIPTURLPATH{edit}%/Sandbox/%HOMETOPIC%"> * New example topic: <input type="text" name="topic" value="ExampleTopicAUTOINC0001" size="30" /> <input type="hidden" name="templatetopic" value="%SYSTEMWEB%.ExampleTopicTemplate" /> <input type="hidden" name="topicparent" value="%HOMETOPIC%" /> <input type="hidden" name="onlywikiname" value="on" /> <input type="hidden" name="onlynewtopic" value="on" /> <input type="submit" class="twikiSubmit" value="Create" /> </form>
save
script instead of the edit
script in the form action. When you specify the save script in an HTML form tag you have to use the "post" method. This is done automatically when using the EDITFORMFIELD variable. Example when using the HTML form tag:
<form name="new" action="%SCRIPTURLPATH{save}%/Sandbox/" method="post"> ... </form>
edit
and save
scripts understand many more parameters, see TWikiScripts#edit and TWikiScripts#save for details.
%WIKIUSERNAME%
and %DATE%
variables in your topic templates to include the signature of the person creating a new topic. The variables are expanded into fixed text when a new topic is created. The standard signature is: -- %WIKIUSERNAME% - %DATE%
* Set SKIN = tagme, topmenu, pattern
twiki/templates
directory and are named according to the skin: <scriptname>.<skin>.tmpl
. Skin files may also be defined in TWiki topics - see TWikiTemplates for details.
To start creating a new skin, copy the default TWikiTemplates (like view.tmpl
), or copy an existing skin to use as a base for your own skin. You should only need to copy the files you intend to customize, as TWiki can be configured to fall back to another skin if a template is not defined in your skin. Name the files as described above (for example view.myskin.tmpl
).
If you use PatternSkin as your starting point, and you want to modify the layout, colors or even the templates to suit your own needs, have a look first at the topics PatternSkinCustomization and PatternSkinCssCookbook.
For your own TWiki skin we encourage you to show a small TWiki logo at the bottom of your skin:
%WEBCOPYRIGHT%
variable.
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.
<p />
in the generated html. It will produce invalid html, and may break the page layout.
twiki.pattern.tmpl
contains %TMPL:INCLUDE{"twiki"}%
, the templating system will include the next twiki.SKIN in the skin path (which is explained below). For example, to create a customization of pattern skin, where you only want to remove the edit & WYSIWYG buttons from view page, you create only a view.yourlocal.tmpl
:
%TMPL:INCLUDE{"view"}% %TMPL:DEF{"edit_topic_link"}%%TMPL:END% %TMPL:DEF{"edit_wysiwyg_link"}%%TMPL:END%and then set
SKIN=yourlocal,pattern
.
Variable: | Expanded to: |
---|---|
%WEBLOGONAME% |
Filename of web logo |
%WEBLOGOIMG% |
Image URL of web logo |
%WEBLOGOURL% |
Link of web logo |
%WEBLOGOALT% |
Alt text of web logo |
%WIKILOGOURL% |
Link of page logo |
%WIKILOGOIMG% |
Image URL of page logo |
%WIKILOGOALT% |
Alt text of page logo |
%WEBBGCOLOR% |
Web-specific background color, defined in the WebPreferences |
%WIKITOOLNAME% |
The name of your TWiki site |
%SCRIPTURL% |
The script URL of TWiki |
%SCRIPTURLPATH% |
The script URL path |
%SCRIPTSUFFIX% |
The script suffix, ex: .pl , .cgi |
%WEB% |
The name of the current web. |
%TOPIC% |
The name of the current topic. |
%WEBTOPICLIST% |
Common links of current web, defined in the WebPreferences. It includes a Jump box |
%TEXT% |
The topic text, e.g. the content that can be edited |
%META{"form"}% |
TWikiForm, if any |
%META{"attachments"}% |
FileAttachment table |
%META{"parent"}% |
The topic parent |
%EDITTOPIC% |
Edit link |
%REVTITLE% |
The revision title, if any, ex: (r1.6) |
%REVINFO% |
Revision info, ex: r1.6 - 24 Dec 2002 - 08:12 GMT - TWikiGuest |
%WEBCOPYRIGHT% |
Copyright notice, defined in the WebPreferences |
%BROADCASTMESSAGE% |
Broadcast message at the beginning of your view template, can be used to alert users of scheduled downtimes; can be set in TWikiPreferences |
http://www.google.com/
to jump to an external web site. The feature is handy if you build a skin that has a select box of frequently used links, like Intranet home, employee database, sales database and such. A little JavaScript gets into action on the onchange
method of the select tag to fill the selected URL into the "Go" box field, then submits the form.
Here is an example form that has a select box and the Jump Box for illustration purposes. You need to have JavaScript enabled for this to work:
Note: Redirect to a URL only works if it is enabled in configure
(Miscellaneous, {AllowRedirectUrl}
).
styles.pattern.tmpl
.
<style type='text/css' media='all'>@import url('%PUBURLPATH%/%SYSTEMWEB%/MySkin/mystyle.css');</style>
attachtables.tmpl
template using the %TMPL:DEF
macro syntax described in TWikiTemplates. These macros are:
Macro | Description |
---|---|
ATTACH:files:header |
Standard title bar |
ATTACH:files:row |
Standard row |
ATTACH:files:footer |
Footer for all screens |
ATTACH:files:header:A |
Title bar for upload screens, with attributes column |
ATTACH:files:row:A |
Row for upload screen |
ATTACH:files:footer:A |
Footer for all screens |
Macro | Description |
---|---|
ATTACH:versions:header |
Header for versions table on upload screen |
ATTACH:versions:row |
Row format for versions table on upload screen |
ATTACH:versions:footer |
Footer for versions table on upload screen |
ATTACH:row
macros are expanded for each file in the attachment table, using the following special tags:
Tag | Description |
---|---|
%A_URL% |
viewfile URL that will recover the file |
%A_REV% |
Revision of this file |
%A_ICON% |
A file icon suitable for representing the attachment content |
%A_FILE% |
The name of the file. To get the 'pub' url of the file, use %PUBURL%/%WEB%/%TOPIC%/%A_FILE% |
%A_SIZE% |
The size of the file |
%A_DATE% |
The date the file was uploaded |
%A_USER% |
The user who uploaded it |
%A_COMMENT% |
The comment they put in when uploading it |
%A_ATTRS% |
The attributes of the file as seen on the upload screen e.g "h" for a hidden file |
view.
skin.tmpl
, where skin is the name of the skin e.g. pattern
. If no template is found, then the fallback is to use view.tmpl
. Each skin on the path is searched for in turn. For example, if you have set the skin path to local,pattern
then view.local.tmpl
will be searched for first, then view.pattern.tmpl
and finally view.tmpl
.
The basic skin is defined by a SKIN
setting:
Set SKIN = catskin, bearskin
?skin=catskin,bearskin
:
Setting SKIN
(or the ?skin
parameter in the URL) replaces the existing skin path setting, for the current page only. You can also extend the existing skin path as well, using covers.
Set COVER = ruskin
ruskin, catskin, bearskin
). There is also an equivalent cover
URL parameter. The difference between setting SKIN
vs. COVER
is that if the chosen template is not found (e.g., for included templates), SKIN
will fall back onto the next skin in line, or the default skin, if only one skin was present, while COVER
will always fall back onto the current skin.
An example would be invoking the printable mode, which is achieved by applying ?cover=print
. The view.print.tmpl
simply invokes the viewprint
template for the current skin which then can appropriately include all other used templates for the current skin. Where the printable mode be applied by using SKIN
, all skins would have the same printable appearance.
The full skin path is built up as follows: SKIN
setting (or ?skin
if it is set), then COVER
setting is added, then ?cover
.
* Set SKIN = %IF{ "'%HTTP{"User-Agent"}%'~'*iPhone*' OR '%HTTP{"User-Agent"}%'~'*Android*'" then="print, pattern" else="topmenu, pattern" }%
text
skin is reserved for TWiki internal use.
Skin names starting with rss
also have a special meaning; if one or more of the skins in the skin path starts with 'rss' then 8-bit characters will be encoded as XML entities in the output, and the content-type
header will be forced to text/xml
.
Related Topics: TWikiSkinBrowser, AdminDocumentationCategory, DeveloperDocumentationCategory, TWiki:TWiki.TWikiSkinsSupplement%VARIABLE%
or %VARIABLE{ parameter="value" }%
- that expand into content whenever a topic is rendered for viewing. There are two types of variables:
%T%
renders as %CALCULATE{}%
is handled by the SpreadSheetPlugin
Categories:
|
![]() |
Variables:
![]() |
%T%
to get %TOPIC%
to get TWikiVariables
(a predefined variable)
%CALCULATE{ "$UPPER(Text)" }%
to get TEXT
(a variable defined by a plugin)
!%TOPIC%
to get %TOPIC%
%ALLVARIABLES%
to get a full listing of all variables defined for a particular topic
%MYVAR%
, %MyVar%
, %My2ndVar%
, and %My_Var%
are valid names. Variables are case sensitive, e.g. %MyVAR%
and %MYVAR%
are not the same.
By convention all settings, predefined variables and variables handled by extensions are always UPPER-CASE.
%USERPREFSTOPIC%
in the user's subweb is read instead
$TWiki::cfg{DemoteUserPreferences}
is true, this step is deferred to a later step. On this TWiki installation, $TWiki::cfg{DemoteUserPreferences}
is false
EXTRAPREFERENCES
is defined at this point, it's regarded as having comma separated list of topics. Those topics are read in the listed order as if they were WebPreferences
$TWiki::cfg{DemoteUserPreferences}
is true as mentioned at the step 4
preview
will show the wrong thing, and you must save
the topic to see it correctly.
The syntax for setting variables is the same anywhere in TWiki (on its own TWiki bullet line, including nested bullets): [multiple of 3 spaces] * [space] Set [space] VARIABLENAME [space] = [space] value
Examples:
* Set VARIABLENAME1 = value * Set VARIABLENAME2 = valueSpaces between the = sign and the value will be ignored. You can split a value over several lines by indenting following lines with spaces - as long as you don't try to use * as the first character on the following line. Example:
* Set VARIABLENAME = value starts here and continues hereWhatever you include in your variable will be expanded on display, exactly as if it had been entered directly. Example: Create a custom logo variable
%MYLOGO%
, define the Variable on the web's WebPreferences topic, and upload a logo file, ex: mylogo.gif
. You can upload by attaching the file to WebPreferences, or, to avoid clutter, to any other topic in the same web, e.g. LogoTopic
. Sample variable setting in WebPreferences:
* Set MYLOGO = %PUBURL%/%WEB%/LogoTopic/mylogo.gifYou can also set preferences variables on a topic by clicking the link
Edit topic preference settings
under More topic actions
. Use the same * Set VARIABLENAME = value
syntax. Preferences set in this manner are not visible in the topic text, but take effect nevertheless.
$TWiki::cfg{DemoteUserPreferences}
has been introduced to avoid it.
If it's set to true, user level variables are set at the last step instead of the step 4.
But this is not enough.
To guarantee a certain result, you need to finalise critical preferences variables set at the web or topic level, which is cumbersome.
So preferences variables DENYUSERPREFEENCES
and ALLOWUSERPREFEENCES
have been introduced. DENYUSERPREFEENCES
and ALLOWUSERPREFEENCES
may have comma separated list of variable names
DENYUSERPREFEENCES
, the variable cannot be overridden at the user level. There is a special value "all", which means no preferences variables can be overridden at the user level
ALLOWUSERPREFEENCES
is set and not empty, only the listed preferences variables can be overridden. There is a special value "all", which means any preferences variable can be overridden at the user level. But actually, "all" is not necessary since a blank value or not setting ALLOWUSERPREFEENCES
has the same effect
DENYUSERPREFEENCES
takes precedence over ALLOWUSERPREFEENCES
. If a variable is listed on both, it cannot be overridden. If DENYUSERPREFEENCES
is "all", the value of ALLOWUSERPREFEENCES
doesn't matter.
* Set DENYUSERPREFERENCES = allIf you allow
INYMCEPLUGIN_DISABLE
and SKIN
to be set at the user level:
* Set ALLOWUSERPREFERENCES = TINYMCEPLUGIN_DISABLE, SKINIf you allow user preferences to set anything other than
TINYMCEPLUGIN_DISABLE
or SKIN
:
* Set DENYUSERPREFERENCES = TINYMCEPLUGIN_DISABLE, SKINPlease note
DENYUSERPREFEENCES
and ALLOWUSERPREFEENCES
affect user preferences regardless of $TWiki::cfg{DemoteUserPreferences}
.
You can set those variables at the site level while $TWiki::cfg{DemoteUserPreferences}
setting to false.
If you do so, you should finalise DENYUSERPREFEENCES
and ALLOWUSERPREFEENCES
.
Otherwise, they might be overridden by user preferences.
You will get the most benefit of DENYUSERPREFEENCES
and ALLOWUSERPREFEENCES
by setting $TWiki::cfg{DemoteUserPreferences}
to true.
That way, each web can specify how much user level preferences overriding is allowed.
* Set EXAMPLE = Example variable using %DEFAULT%, %PARAM1% and %PARAM2% * Set DEMO = Demo using %DEFAULT{ default="(undefined)" }%, %PARAM1{ default="(undefined)" }% and %PARAM2{ default="(undefined)" }%A special
%DEFAULT%
variable denotes the default (nameless) parameter of the calling variable. Variables optionally may list a default="..."
parameter that gets used in case the calling variable does not specify that parameter.
To use a parameterized variable (or call a macro), add parameters within the curly brackets, such as:
* %EXAMPLE{ "foo" PARAM1="bar" PARAM2="baz" }% * %DEMO{ "demo" PARAM2="parameter 2" }% -- note that PARAM1 is missingwhich resolves to:
%PARAM1%
gets expanded to bar
.
* Set DRINK = red wine * Set FAVORITE = My %DEFAULT{default="favorite"}% dish is %DISH{default="steak"}%, my %DEFAULT{default="favorite"}% drink is %DRINK%.
%DISH{default="steak"}%
), or as a preferences setting (Set DRINK = ...
).
Use Variables:
%FAVORITE{ DISH="Sushi" DRINK="Sake" }%Returns:
%FAVORITE{}%Returns:
%FAVORITE{ "preferred" }%Returns:
Local
in place of Set
in the variable definition. For example, if the user sets the following in their home topic:
* Set EDITBOXHEIGHT = 10 * Local EDITBOXHEIGHT = 20Then when they are editing any other topic, they will get a 10 high edit box. However when they are editing their home topic, they will get a 20 high edit box.
Local
can be used wherever a preference needs to take a different value depending on where the current operation is being performed.
Use this powerful feature with great care! %ALLVARIABLES%
can be used to get a listing of the values of all variables in their evaluation order, so you can see variable scope if you get confused.
%BB%
- line break and bullet combined
%BB2%
- level 2 bullet with line break
%BB3%
- level 3 bullet with line break
%BB4%
- level 4 bullet with line break
%BR%
- line break
%BULLET%
- bullet sign
%CARET%
- caret symbol
%VBAR%
- vertical bar
%H%
- %I%
- %M%
- %N%
- %P%
- %Q%
- %S%
- %T%
- %U%
- %X%
- %Y%
- %RED% text %ENDCOLOR%
- colored text (also %YELLOW%
, %ORANGE%
, %PINK%
, %PURPLE%
, %TEAL%
, %NAVY%
, %BLUE%
, %AQUA%
, %LIME%
, %GREEN%
, %OLIVE%
, %MAROON%
, %BROWN%
, %BLACK%
, %GRAY%
, %SILVER%
, %WHITE%
)
%REDBG% text %ENDBG%
- colored background (also %YELLOWBG%
, %ORANGEBG%
, %PINKBG%
, %PURPLEBG%
, %TEALBG%
, %NAVYBG%
, %BLUEBG%
, %AQUABG%
, %LIMEBG%
, %GREENBG%
, %OLIVEBG%
, %MAROONBG%
, %BROWNBG%
, %BLACKBG%
, %GRAYBG%
, %SILVERBG%
, %WHITEBG%
)
%SEARCH%
, are powerful and general tools.
%IF{...}%
, %SCRIPT{...}%
, and %INCLUDE{...}%
can be overridden
OVERRIDABLEPREDEFINEDVARIABLES
having a comma separated list of predefined variables specifies which predefined variables are overridable
*Set OVERRIDABLEPREDEFINEDVARIABLES =
DATE
and LANGUAGE
predefined variables can be overridden but all the other predefined variables cannot*Set OVERRIDABLEPREDEFINEDVARIABLES = DATE, LANGUAGE
%INCLUDINGTOPIC%
, %INCLUDE%
, and the mighty %SEARCH%
.
Var<name>
in the TWiki web. For example, a %LIGHTSABER%
variable has a documentation topic called VarLIGHTSABER. The topic is expected to have a specific format so that reports in this TWikiVariables topic, in TWikiVariablesSearch and in category topics work as expected.
Basic structure of a variable documentation topic:
#VarLIGHTSABER
---+++
(level 3) heading with variable name, --
, short description
Syntax:
bullet with example syntax
Parameters:
bullet with a table explaining the parameters (optional)
Example:
bullet or two with examples
Expands to:
bullet with expanded variable (optional)
Note:
bullet with notes (optional)
Category:
bullet with one or more of the TWiki variables categories:Related:
bullet with related links. Links have conditional IF so that links work properly locally in variable documentation topics and in the TWikiVariables topic
VarLIGHTSABER
topic:
#VarLIGHTSABER ---+++ LIGHTSABER -- laser sword to fend of unethical competition * The =%<nop>LIGHTSABER{}%= variable is handled by the LightsaberPlugin. * Syntax: =%<nop>LIGHTSABER{ _parameters_ }%= * Parameters: | *Parameter* | *Description* | *Default* | | =color="..."= | Color: =red=, =glue=, =green= | =white= | | =sound="..."= | Sound: =none=, =standard=, =loud= | =none= | * Example: =%<nop>LIGHTSABER{ color="red" }%= shows a red Lightsaber * Expands to: =%LIGHTSABER{ color="red" }%= * Note: The Lightsaber is a fictional weapon in the Star Wars universe, a "laser sword." * Category: FormattingAndRenderingVariables, UIAndVisualizationVariables * Related: [[%IF{"'%INCLUDINGTOPIC%'='TWikiVariables'" then="#"}%VarPLASMA][PLASMA]], LightsaberPlugin
META:
tags
META:
tags.
META:
data includes program-generated info like FileAttachment and topic movement data, and user-defined TWikiForms info.
%META:<type>{key1="value1" key2="value2" ...}%
name
, this appears first for easier searching (note the order of the variables themselves is defined).
Example of Format%META:TOPICINFO{version="1.6" date="976762663" author="LastEditorWikiName" format="1.0"}% text of the topic %META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="TopicMoverWikiName" date="976762680"}% %META:TOPICPARENT{name="NavigationByTopicContext"}% %META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }% %META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }% %META:FORM{name="WebFormTemplate"}% %META:FIELD{name="OperatingSystem" value="OsWin"}% %META:FIELD{name="TopicClassification" value="PublicFAQ"}%
Key | Comment |
---|---|
version | Same as RCS version |
date | integer, unix time, seconds since start 1970 |
author | last to change topic, is the REMOTE_USER |
format | Format of this topic, will be used for automatic format conversion |
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%
Key | Comment |
---|---|
from | Full name, i.e., web.topic |
to | Full name, i.e., web.topic |
by | Who did it, is the REMOTE_USER, not WikiName |
date | integer, unix time, seconds since start 1970 |
Key | Comment |
---|---|
name | The topic from which this was created, typically when clicking on a red-link, or by filling out a form. Normally just TopicName , but it can be a full Web.TopicName format if the parent is in a different Web. |
Key | Comment |
---|---|
name | Name of file, no path. Must be unique within topic |
version | Same as RCS revision |
path | Full path file was loaded from |
size | In bytes |
date | integer, unix time, seconds since start 1970 |
user | the REMOTE_USER, not WikiName |
comment | As supplied when file uploaded |
attr | h if hidden, optional |
Key | Comment |
---|---|
movedfrom | full topic name - web.topic |
movedby | the REMOTE_USER, not WikiName |
movedto | full topic name - web.topic |
moveddate | integer, unix time, seconds since start 1970 |
Key | Comment |
---|---|
name | A topic name - the topic represents one of the TWikiForms. Can optionally include the web name (i.e., web.topic), but doesn't normally |
Key | Name |
---|---|
name | Ties to entry in TWikiForms template, is title with all bar alphanumerics and . removed |
title | Full text from TWikiForms template |
value | Value user has supplied via form |
diff
function output appears in a logical order
META:TOPICINFO
META:TOPICPARENT
(optional)
META:TOPICMOVED
(optional)
META:FILEATTACHMENT
(0 or more entries)
META:FORM
(optional)
META:FIELD
(0 or more entries; FORM required)
Raw Text
link can be clicked to show the text of a topic (i.e., as seen when editing). This is done by adding raw=on
to URL. raw=debug
shows the meta data as well as the topic data, ex: debug view for this topic
view
, preview
and edit
scripts.
You can render form fields in topic text by using the FORMFIELD variable. Example:%FORMFIELD{"TopicClassification"}%
Variable usage: | Comment: |
---|---|
%META{"form"}% |
Show form data, see TWikiForms. |
%META{"formfield"}% |
Show form field value. Parameter: name="field_name" . Example:%META{ "formfield" name="TopicClassification" }% |
%META{"attachments"}% |
Show attachments, except for hidden ones. Options: all="on" : Show all attachments, including hidden ones. |
%META{"moved"}% |
Details of any topic moves. |
%META{"parent"}% |
Show topic parent. Options: dontrecurse="on" : By default recurses up tree, at some cost. nowebhome="on" : Suppress WebHome. prefix="..." : Prefix for parents, only if there are parents, default "" . suffix="..." : Suffix, only appears if there are parents, default "" . separator="..." : Separator between parents, default is " > " . |
yum
, apt-get
, rpm
, etc) to install dependent libraries.
If available, install CPAN (Comprehensive Perl Archive Network) libraries with the OS package manager. For example, to install IO::Socket::SSL
on Fedora/RedHat/CentOS, run yum install perl-IO-Socket-SSL
. CPAN modules can also be installed natively, see TWiki:TWiki.HowToInstallCpanModules%FAILEDPLUGINS%
variable can be used to debug failures. You may also want to check your webserver error log and the various TWiki log files.
ab
utility. Example on Unix:time wget -qO /dev/null /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.
Set VARCACHEPLUGIN_REFRESH = 24
%<pluginname>_<setting>%
, such as %VARCACHEPLUGIN_REFRESH%
.
To learn how this is done, use the TWiki:Plugins.VarCachePluginlib/TWiki/Plugins/YourPlugin/
with variables, such as$TWiki::cfg{Plugins}{RecentVisitorPlugin}{ShowIP} = 0;
$showIP = $TWiki::cfg{Plugins}{RecentVisitorPlugin}{ShowIP} || 0;
Set SHORTDESCRIPTION = Show recent visitors to a TWiki site
our $SHORTDESCRIPTION = 'Show recent visitors to a TWiki site';
our $NO_PREFS_IN_TOPIC = 1;
%ACTIVATEDPLUGINS%
%PLUGINDESCRIPTIONS%
"$SUM( $ABOVE() )"
to TWiki tables or anywhere in topic text ExternalSite:Page
to link to a page on an external site based on aliases defined in a rules topic :-)
as :eek:
as %FAILEDPLUGINS%
Plugin | Errors |
---|---|
SpreadSheetPlugin | none |
BackupRestorePlugin | none |
ColorPickerPlugin | none |
CommentPlugin | none |
DatePickerPlugin | none |
EditTablePlugin | none |
HeadlinesPlugin | none |
InterwikiPlugin | none |
JQueryPlugin | none |
PreferencesPlugin | none |
SetGetPlugin | none |
SlideShowPlugin | none |
SmiliesPlugin | none |
TablePlugin | none |
TagMePlugin | none |
TinyMCEPlugin | none |
TwistyPlugin | none |
WatchlistPlugin | none |
WysiwygPlugin | none |
Handler | Plugins |
---|---|
afterEditHandler | WysiwygPlugin |
afterRenameHandler | TagMePlugin WatchlistPlugin |
afterSaveHandler | TagMePlugin WatchlistPlugin |
beforeCommonTagsHandler | EditTablePlugin PreferencesPlugin TwistyPlugin WysiwygPlugin |
beforeEditHandler | TinyMCEPlugin WysiwygPlugin |
beforeMergeHandler | WysiwygPlugin |
beforeSaveHandler | CommentPlugin WatchlistPlugin WysiwygPlugin |
commonTagsHandler | SpreadSheetPlugin BackupRestorePlugin CommentPlugin EditTablePlugin JQueryPlugin SlideShowPlugin SmiliesPlugin |
initPlugin | SpreadSheetPlugin BackupRestorePlugin ColorPickerPlugin CommentPlugin DatePickerPlugin EditTablePlugin HeadlinesPlugin InterwikiPlugin JQueryPlugin PreferencesPlugin SetGetPlugin SlideShowPlugin SmiliesPlugin TablePlugin TagMePlugin TinyMCEPlugin TwistyPlugin WatchlistPlugin WysiwygPlugin |
modifyHeaderHandler | WysiwygPlugin |
postRenderingHandler | PreferencesPlugin WysiwygPlugin |
preRenderingHandler | InterwikiPlugin SmiliesPlugin TablePlugin |
lib/TWiki/Func.pm
) describes all the interfaces available to plugins. Plugins should only use the interfaces described in this module.
Func.pm
, you run the risk of creating security holes. Also, your plugin will likely break and require updating when you upgrade to a new version of TWiki.
lib/TWiki/Plugins/EmptyPlugin.pm
module.
#
from all lines of the callback.
eval
block like this:eval { require IPC::Run }
return "<font color=\"red\">SamplePlugin: Can't load required modules ($@)</font>" if $@;
lib/TWiki/Plugins/BathPlugin/
.
$NO_PREFS_IN_TOPIC
in your plugin package as that will stop TWiki from reading the plugin topic for every page. Use Config.spec or preferences settings instead. (See details).
$VERSION
variable. This should be an integer, or a subversion version id.
initPlugin
handler should check all dependencies and return 1 if the initialization is OK or 0 if something went wrong. initPlugin
handler).
$TWiki::Plugins::VERSION
in the TWiki::Plugins
module contains the TWiki plugin API version, currently 6.01. %PLUGINVERSION{}%
variable to query the plugin API version or the version of installed plugins.
%TWiki::cfg
hash than adding it as preferences in the plugin topic. configure
describes the steps
MyFirstPlugin.pm
MyFirstPlugin.txt
MyFirstPlugin
topic. Other needed Perl code is best placed in a lib/TWiki/Plugins/MyFirstPlugin/
directory.
The plugin API handles the details of connecting your Perl module with main TWiki code. When you're familiar with the Plugin API, you're ready to develop plugins.
The TWiki:Plugins.BuildContriblib/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:Pluginsweb.>"
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:SupportTWiki::Func::getWorkArea()
function, which gives you a persistent directory where you can store data files. By default they will not be web accessible. The directory is guaranteed to exist, and to be writable by the webserver user. For convenience, TWiki::Func::storeFile()
and TWiki::Func::readFile()
are provided to persistently store and retrieve simple data in this area.
TWiki::Func::saveAttachment()
function to store the data.
Recommendation for file name: _GaugePlugin_img123.gif
TWiki::Func::saveAttachment()
function to store the data.
Recommendation for file names in plugin attachment area: _Main_roundedge-ul.gif
configure
configure
rather than trying to use TWiki preferences variables. These extensions use Config.spec
files to publish their configuration requirements.
Config.spec
files are read during TWiki configuration. Once a Config.spec
has defined a configuration item, it is available for edit through the standard configure
interface. Config.spec
files are stored in the 'plugin directory' e.g. lib/TWiki/Plugins/BathPlugin/Config.spec
.
Config.spec
file Config.spec
file for an extension starts with the extension announcing what it is:
# ---+ Extensions # ---++ BathPlugin # This plugin senses the level of water in your bath, and ensures the plug # is not removed while the water is still warm.This is followed by one or more configuration items. Each configuration item has a type, a description and a default. For example:
# **SELECT Plastic,Rubber,Metal** # Select the plug type $TWiki::cfg{BathPlugin}{PlugType} = 'Plastic'; # **NUMBER** # Enter the chain length in cm $TWiki::cfg{BathPlugin}{ChainLength} = 30; # **BOOLEAN EXPERT** # Set this option to 0 to disable the water temperature alarm $TWiki::cfg{BathPlugin}{TempSensorEnabled} = 1;The type (e.g.
**SELECT**
) tells configure
to how to prompt for the value. It also tells configure
how to do some basic checking on the value you actually enter. All the comments between the type and the configuration item are taken as part of the description. The configuration item itself defines the default value for the configuration item. The above spec defines the configuration items $TWiki::cfg{BathPlugin}{PlugType}
, $TWiki::cfg{BathPlugin}{ChainLength}
, and $TWiki::cfg{BathPlugin}{TempSensorEnabled}
for use in your plugin. For example,
if( $TWiki::cfg{BathPlugin}{TempSensorEnabled} && $curTemperature > 50 ) { die "The bathwater is too hot for comfort"; }The Config.spec file is read by
configure
, which then writes LocalSite.cfg
with the values chosen by the local site admin.
A range of types are available for use in Config.spec
files:
BOOLEAN | A true/false value, represented as a checkbox |
COMMAND length | A shell command |
LANGUAGE | A language (selected from {LocalesDir} |
NUMBER | A number |
OCTAL | An octal number |
PASSWORD length | A password (input is hidden) |
PATH length | A file path |
PERL | A perl structure, consisting of arrays and hashes |
REGEX length | A perl regular expression |
SELECT choices | Pick one of a range of choices |
SELECTCLASS root | Select a perl package (class) |
STRING length | A string |
URL length | A url |
URLPATH length | A relative URL path |
EXPERT | means this an expert option |
M | means the setting is mandatory (may not be empty) |
H | means the option is not visible in configure |
lib/TWiki.spec
for many more examples.
Config.spec
files for non-plugin extensions are stored under the Contrib
directory instead of the Plugins
directory.
Note that from TWiki 5.0 onwards, CGI scripts (in the TWiki bin
directory) provided by extensions must also have an entry in the Config.spec
file. This entry looks like this (example taken from PublishContrib)
# **PERL H** # Bin script registration - do not modify $TWiki::cfg{SwitchBoard}{publish} = [ "TWiki::Contrib::Publish", "publish", { publishing => 1 } ];
PERL
specifies a perl data structure, and H
a hidden setting (it won't appear in configure
). The first field of the data value specifies the class where the function that implements the script can be found. The second field specifies the name of the function, which must be the same as the name of the script. The third parameter is a hash of initial context settings for the script.
TWiki:TWiki/SpecifyingConfigurationItemsForExtensionsDev
, such as MyFirstPluginDev
. The plugin development topic is a great resource to discuss feature enhancements and to get feedback from the TWiki community.
if( $TWiki::Plugins::VERSION >= 1.1 ) { @webs = TWiki::Func::getListOfWebs( 'user,public' ); } else { @webs = TWiki::Func::getPublicWebList( ); }
TWiki::Plugins
version in which the handler was first deprecated. For example, if we need to define the endRenderingHandler
for compatibility with TWiki::Plugins
versions before 1.1, we would add this to the plugin:
package TWiki::Plugins::SinkPlugin; use vars qw( %TWikiCompatibility ); $TWikiCompatibility{endRenderingHandler} = 1.1;If the currently-running TWiki version is 1.1 or later, then the handler will not be called and the warning will not be issued. TWiki with versions of
TWiki::Plugins
before 1.1 will still call the handler as required.