TWiki Webmaster Reference (ver. 01 Sep 2001)

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

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

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

Related Topics: TWikiSite, TWikiHistory, TWikiPlannedFeatures, TWikiEnhancementRequests

TWiki Access Control

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

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

Tip: TWiki:TWiki.TWikiAccessControlSupplement on TWiki.org has additional documentation on access control.

An Important Control Consideration

Your organization will learn that, while fostering an open collaborative environment, soft security (peer review), together with version control (complete audit trail) will take care of any security concern you might have.

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

• Peer influence is enough to ensure that only relevant content is posted.
• Peer editing - the ability for anyone to rearrange all content on a page - keeps topics focused.
• In TWiki, content is transparently preserved under revision control:
  • Edits can easily be rolled back to a previous revision if needed.
  • Users are encouraged to edit and refactor (condense a long topic), since there's a safety net.

As a collaboration guideline:

• Create broad-based Groups (for more and varied input), and...
• Avoid creating view-only topics (if you can read it, you should be able to contribute to it).

Permissions settings of the webs on this TWiki site

Web	Sitemap	VIEW		CHANGE		RENAME
	Listed	DENY	ALLOW	DENY	ALLOW	DENY	ALLOW
TWiki	on				TWikiAdminGroup		TWikiAdminGroup

Please Note:

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

Note: Above table comes from SitePermissions

Authentication vs. Access Control

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

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

Users and Groups

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

Managing Users

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

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

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

Managing Groups

The 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 the 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 >

The GROUP setting is a comma-separated list of users and/or other groups. Example:

• Set GROUP = SomeUser, OtherUser, SomeGroup

The ALLOWTOPICCHANGE setting defines who is allowed to change the group topic; it is a comma delimited list of users and groups. You typically want to restrict that to the members of the group itself, so it should contain the name of the topic. This prevents users not in the group from editing the topic to give themselves or others access. For example, for the MarketingGroup topic write:

• Set ALLOWTOPICCHANGE = MarketingGroup

Note: TWiki has strict formatting rules. Make sure you have a real bullet. (In raw edit it is three or six spaces, an asterisk, and an extra space in front of any access control rule.)

The Super Admin Group

A 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 the 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

On a large TWiki installation having hundreds or thousands of webs, a single super admin group may not be able to take care of all of those webs. One way to deal with that is to have a super admin group for each web. AutonomousWebs shows how to.

Restricting Access

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

• Restricting VIEW blocks viewing and searching of content. When you restric VIEW to a topic or web, this also restricts INCLUDE and Formatted SEARCH from showing the content of the topics.
• Restricting CHANGE blocks creating new topics, changing topics or attaching files.
• Restricting RENAME prevents renaming of topics within a web.

Note that there is an important distinction between CHANGE access and RENAME access. A user can CHANGE a topic, but thanks to version control their changes cannot be lost (the history of the topic before the change is recorded). However if a topic or web is renamed, that history may be lost. Typically a site will only give RENAME access to administrators and content owners.

Controlling access to a Web

You 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:

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

• You can define these settings in the WebPreferences topic, preferable towards the end of the topic:
  • Set DENYWEBVIEW = < comma-delimited list of Users and Groups >
  • Set ALLOWWEBVIEW = < comma-delimited list of Users and Groups >
  • Set DENYWEBCHANGE = < comma-delimited list of Users and Groups >
  • Set ALLOWWEBCHANGE = < comma-delimited list of Users and Groups >
  • Set DENYWEBRENAME = < comma-delimited list of Users and Groups >
  • Set ALLOWWEBRENAME = < comma-delimited list of Users and Groups >

For example, set this to restrict a web to be viewable only by the MarketingGroup:

• Set ALLOWWEBVIEW = Main.MarketingGroup

If your site allows hierarchical webs, then access to sub-webs is determined from the access controls of the parent web, plus the access controls in the sub-web. So, if the parent web has 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

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

• You can define these settings in any topic, preferable towards the end of the topic:
  • Set DENYTOPICVIEW = < comma-delimited list of Users and Groups >
  • Set ALLOWTOPICVIEW = < comma-delimited list of Users and Groups >
  • Set DENYTOPICCHANGE = < comma-delimited list of Users and Groups >
  • Set ALLOWTOPICCHANGE = < comma-delimited list of Users and Groups >
  • Set DENYTOPICRENAME = < comma-delimited list of Users and Groups >
  • Set ALLOWTOPICRENAME = < comma-delimited list of Users and Groups >

For example, set this to restrict a topic to be viewable only by the MarketingExecGroup:

• Set ALLOWTOPICVIEW = Main.MarketingExecGroup

You may want to allow or deny access to a topic in addition to the ALLOWEB* or DENYWEB* specifies. In that case having + as the first non-space character of ALLOWTOPIC* or DENYTOPIC* has that effect. For example, the following setting allows view by MarketingExecGroup in addition to the people ALLOWWEBVIEW allows.

• Set ALLOWTOPICVIEW = + Main.MarketingExecGroup

See "How TWiki evaluates ALLOW/DENY settings" below for more on how ALLOW and DENY interacts.

If the same setting is defined multiple times the last one overrides the previous. They are not OR'ed together.

Allowing public access to specific topics in a restricted web

You may want to completely open up access to a specific topic within a restricted web - allowing access by anybody. There is a special group for that - Main.AllUsersGroup. The following setting allows view access to the topic by anybody even if they are not authenticated.

• Set ALLOWTOPICVIEW = Main.AllUsersGroup

Alternatively, you can grant access only to authenticated users by Main.AllAuthUsersGroup. If an unauthenticated user accesses a topic having the following setting, they are asked to authenticate themself.

• Set ALLOWTOPICVIEW = Main.AllAuthUsersGroup

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

As mentioned in the following section, meaning of an empty value set to DENYTOPICVIEW, DENYTOPICCHANGE, and DENYTOPICRENAME has been changed in TWiki 6.0. To keep those TWiki topics having empty DENYTOPICOPERAION accessible by everybody, those need to be replaced with

• Set ALLOWTOPICOPERATION = Main.AllUsersGroup

For that, tools/eliminate_emptydenytopic is provided. After upgrading from pre 6.0 to post 6.0, you need to run it.

Empty values in access control variables

Setting an empty value to an access control variable is the same as not setting at all:

• Set ALLOWTOPICVIEW =

Since TWiki 4.0 and prior to TWiki 6.0 setting DENYTOPICVIEW, DENYTOPICCHANGE, or DENYTOPICRENAME to an empty value meant "do not deny anyone regardless of the corresponding ALLOWTOPICX", which is no longer the case. Back then, setting an empty value to DENYTOPICX was the only way to open up a topic to everybody in a restricted web. Now that we have AllUsersGroup and AllAuthUsersGroup, there is no need for that behaviour, which caused a lot of confusion and debate.

Securing File Attachments

By default, TWiki does not secure file attachments. Without making the following changes to the twiki.conf file, it is possible for anyone who has access to the server to gain access to an attachment if they know the attachment's fully qualified path, even though access to the topic associated with the attachment is secured. This is because attachments are referred to directly by Apache, and are not by default delivered via TWiki scripts. This means that the above instructions for controlling to topics do not apply to attachments unless you make the changes as described below.

An effective way to secure attachments is to apply the same access control settings to attachments as those applied to topics. This security enhancement can be accomplished by instructing the webserver to redirect accesses to attachments via the TWiki 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/viewfile

Notes:

• It is recommended to use TWiki:TWiki/ApacheConfigGenerator to generate the Apache config file for your TWiki.
• You will need to restart your Apache server after this change.
• Images embedded in topics will load slower since attached images will also be delivered by the viewfile script. The TWiki web and Sandbox web are excluded for performance reasons.
• The viewfile script sets the mime type based upon file name suffix. Unknown types are served as text/plain which can result in corrupt files.

Controlling who can manage top-level webs

Top 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.

• You can define these settings in the Main.TWikiPreferences topic, preferable towards the end of the topic:
  • Set DENYROOTCHANGE = < comma-delimited list of Users and Groups >
  • Set ALLOWROOTCHANGE = < comma-delimited list of Users and Groups >

How TWiki evaluates ALLOW/DENY settings

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

1. If the user is an administrator
   • access is PERMITTED.
2. If DENYTOPIC is set to a list of wikinames
   • people in the list will be DENIED.
3. If DENYTOPIC is set to empty ( i.e. Set DENYTOPIC = )
   • the access control setting is ignored.
     Attention: The spec changed in TWiki-6.0; access was permitted in earlier TWiki releases.
4. If ALLOWTOPIC is set
   1. people in the list are PERMITTED
   2. everyone else is DENIED
5. If DENYWEB is set to a list of wikinames
   • people in the list are DENIED access
6. If ALLOWWEB is set to a list of wikinames
   • people in the list will be PERMITTED
   • everyone else will be DENIED
7. If you got this far, access is PERMITTED

Allowing web creation/deletion/rename by user mapping manager

There are cases where DENYROOTCHANGE, ALLOWROOTCHANGE, DENYWEBCHANGE, and ALLOWWEBCHANGE, and DENYWEBCHANGE are not capable enough to implement web creation and rename permissions you want. To cope with such cases, when a new web is created, the canCreateWeb($cUID, $web) method of the user mapping manager is called if it exists. If it returns true, TWiki goes ahead and create the web without checking access control variables. Similarly, when a web is renamed (deletion is a form of rename), the canRenameWeb($cUID, $oldWeb, $newWeb) method of the user mapping manager is called if it exists. Please read AllowWebCreateByUserMappingManager for more details.

Forbid certain users to do certain actions by configuration

You may have an unruly registered users (e.g. a crawler program) who don't follow the rules while you don't have control over such users. And the web application container in which TWiki is installed may be managed by somebody else and you don't have tight and quick control.

To cope with such situations, certain users can be forbidden certain scripts by setting {ForbidUserAction}. A good example is worth more than a lengthy explanation, so here it is:

$TWiki::cfg{ForbidUserAction} = '
    AggresiveCrawler: edit, oops, search;
    ReadOnlyUser:     !view, viewfile;
    TotallyForbidden: !nothing;
';

• AggresiveCrawler is forbidden edit, oops, and search scripts.
• ReadOnlyUser is permitted view and viewfile but forbidden the others.
  • If a script list is preceded by !, only the listed scripts are permitted for the user. ! at the beginning of the list negates the list.
• TotallyForbidden is forbidden all actions.
  Here's the logic. There is no script named nothing, which means all scripts don't match "nothing", hence all scripts are forbidden.

• Spaces, tabs, new lines are ignored
• It consists of semicolon separated list of per-user specifications
• A specification consists of a user name, colon, and a comma separated list of scripts
• A user name needs to be in the canonical form. In most cases the canonical user name is the same as the wiki name. But if you are using non-standard user mapping, the canonical user name of a user is different from the wiki name.

User masquerading

There are cases where it's handy to access TWiki on behalf of somebody else retaining a trace of your real identity rather than completely becoming a different user. We call it user masquerading. TWiki provides a framework to implement that. Please read UserMasquerading for more information.

This is an advanced feature and not many TWiki sites are using, but there is a part in the following section mentioning it, it's mentioned here.

Dynamic access control

There are pitfalls and you need to harden your web to avoid unexpected access. Before using this feature, please read this entire section through carefully.

You may want to restrict access dynamically -- based on topic name, a form field value, or some combination of factors. To cope with such situations, the dynamic access control mechanism is provided. If you set DYNAMIC_ACCESS_CONTROL 'on' at WebPreferences of the web, TWiki variables in access control variables mentioned above are expanded.

Example 1 - restriction based on topic name

Let's assume you need to restrict changes only to the CroniesGroup members except with topics whose name ends with Public, which need be changed by anybody. That is achieve by the following settings on WebPrefences.

   * Set DYNAMIC_ACCESS_CONTROL = on
   * Set ALLOWWEBCHANGE = %IF{"'%CALCULATE{$SUBSTRING(%TOPIC%, -6, 6)}%' = 'Public'" then="%WIKINAME%" else="CroniesGroup"}%

Example 2 - restriction based on form field

Let's assume:

• a web storing requests on topics whose name starts with ReqEnt
• Each request topic has a form field "Requestor", which has the wiki name of the requestor
• Users can view only requests they created
• The members of the SupportGroup mail group can view all requests

   * 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.

• DENYTOPIC* (e.g. DENYTOPICVIEW, DENYTOPICCHANGE)
• ALLOWTOIPC*
• DENYWEB*
• ALLOWWEB*

Dynamic access control in accessing a different web's topic

Let's assume WebA has the following lines on WebPreferences.

   * Set DYNAMIC_ACCESS_CONTROL = on
   * Set MEMBERS = JaneSmith, JoeSchmoe
   * Set ALLOWWEBVIEW = %MEMBERS%

You may think the following lines cheat the access control on WebA but actually not.

   * Set MEMBERS = %WIKINAME%
%INCLUDE{WebA.TopicB}%

Topic level dynamic access control

On a topic, it's possible to use a variable defined on the topic for topic level access restriction. E.g.

   * Set MEMBERS = JaneSmith, JoeSchmoe
   * Set ALLOWTOPICVIEW = %MEMBERS%

Dynamic access control and user masquerading

Your user mapping handler may be providing the UserMasquerading feature. In that case, you expect dynamic access control to just work when user masquerading is in effect. Otherwise, you cannot test if your dynamic access control configuration is working as expected on your own.

Dynamic access control does work as expected even if user masquerading is in effect. For that, the following things are happening under the hood.

Let's think about Example 2 mentioned above. When you masquerading as SomebodyElse, you need to be able to see SomebodyElse's requests only. In the access control setting, a form field value is compared with %WIKINAME%. While user masquerading is in effect, your wiki name is YourNameOnBehalfOfSomebodyElse. It cannot match the form field value.

To make dynamic access control work under these circumstances, variable expansion for dynamic access control is skewed as follows. Specifically, the following variables are expanded to the value of SomeboyElse's rather than YourNameOnBehalfOfSomebodyElse's.

• WIKINAME
• USERNAME
• WIKIUSERNAME

Avoiding vulnerability

By default, user level preferences are read before web level preferences. This means a user can set a preferences variable at the user level and finalise it. To prevent this sort of attack, you need to harden your web or site by disabling user preferences by e.g. having the following line on lib/LocalSite.cfg

$TWiki::cfg{DemoteUserPreferences}= 1;

   * Set DENYUSERPREFEENCES = all

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 =

Disabling dynamic access control

You may not be comfortable with dynamic access control because it may slow things down. Or you may not want to be bothered by questions raised by users about it. If so, you can disable it by setting DYNAMIC_ACCESS_CONTROL 'off' and then finalizing at the local site level. (cf. TWikiVariables#Setting_Preferences_Variables)

Access control and INCLUDE

ALLOWTOPICVIEW and ALLOWTOPICCHANGE only applies to the topic in which the settings are defined. If a topic A includes another topic B, topic A does not inherit the access rights of the included topic B.

Examples: Topic A includes topic B

• If the included topic B has ALLOWTOPICCHANGE set to block editing for a user, it does not prevent editing the including topic A.
• If the included topic B has ALLOWTOPICVIEW set to block view for a user, the user can still view topic A but he cannot see the included topic B. He will see a message No permission to view B

Customizing "access denied" message

When access is denied, a page as follows is displayed:

You may want to customize the passage annotated in the red rectangle. For example, with a web restricting access, you may want to show the link to an access request form.

You can achieve that by setting TOPIC_ACCESS_CONTACT varialbe on WebPreferences. e.g.

   * Set TOPIC_ACCESS_CONTACT = If you need to access this site, please apply [[Main.AccessForm][here]]

Custom user/group notations

You can have custom user/group notations such as USER:userid and LDAPGROUP:group-name and use them for access control. For example:

   * Set ALLOWWEBCHANGE = USER:buzz, LDAPGROUP:foo-bar

Access Control quick recipes

Restrict Access to Whole TWiki Site

In a firewalled TWiki, e.g. an intranet wiki or extranet wiki, you want to allow only invited people to access your TWiki. There are three options:

1. Install TWiki Behind Firewall:

The firewall takes care of giving access to TWiki to authorized people only. This is a typical setup for a company wiki. As for TWiki configuration, no special setup is needed.

2. Extranet TWiki Using Template Login:

All TWiki content (pages and attachments) need to be access controlled. The Template Login allows users to login and logout. Only logged in users can access TWiki content.

Configuration: Follow the default setup, then change these configure settings:

• Secure attachments as documented. The TWiki:TWiki.ApacheConfigGenerator is useful to get the setting right.
• Require authentication for all TWiki scripts except 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';
• When you install additional plugins make sure to add scripts they might introduce also to twiki/bin also to the {AuthScripts} configure setting.
  Attention: Some scripts of additional plugins might not be aware of TWiki's template login. Test all new scripts with a non-authenticated user!

3. Extranet TWiki Using Apache Login:

All TWiki content (pages and attachments) need to be access controlled. The Apache Login does not offer a logout; typically the browser needs to be restarted to logout. Only logged in users can access TWiki content.

Configuration: Enable user authentication with ApacheLogin and lock down access to the whole 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:

• In all three options, content can be restricted selectively with ALLOWWEBVIEW and other access control settings documented above. See also the next quick recipe.
• In the extranet setup, someone with access to the site needs to register new users. If you still want public users to be able to register automatically follow TWiki:TWiki.RegisterOnViewRestrictedSite.

Authenticate and Restrict Selected Webs Only

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

1. Restrict view access to selected Users and Groups. Set one or both of these variables in its WebPreferences topic:
   • Set DENYWEBVIEW = < list of Users and Groups >
   • Set ALLOWWEBVIEW = < list of Users and Groups >
   • Note: DENYWEBVIEW is evaluated before ALLOWWEBVIEW. Access is denied if the authenticated person is in the DENYWEBVIEW list, or not in the ALLOWWEBVIEW list. Access is granted if DENYWEBVIEW and ALLOWWEBVIEW are not defined.

Hide Control Settings

Tip: To hide access control settings from normal browser viewing, you can put them into the topic preference settings by clicking the link 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
-->

Obfuscating Webs

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

• Set NOSEARCHALL = on

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

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

Read-only Skin Mode

It is possible to turn the PatternSkin and TopMenuSkin into read-only mode by removing the edit and attach controls (links and buttons). This is mainly useful if you have TWiki application pages or dashboards where you do not want regular users to change content. The read-only skin mode is not a replacement for access control; you can use it in addition to access control. Details at PatternSkinCustomization#ReadOnlySkinMode.

Configuring access control for topics of a certain name in all webs

You may need to restrict access to topics of a certain name in all webs. For example, there might be an add-on refering to a certain topic of all webs. And the add-on does things only administrators are supposed to do. In that case, change to the topic needs to be restricted only to administrators and must not be overridable.

Let's say there is AutomationAddOn which refers to WebAutomation of all webs. And WebAutomation needs to be modifable only by administrators. That can be achieved by the following configuration.

$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',
};

TWiki Templates

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

Overview

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

There are two types of template:

• Master Templates: Define the HTML used to display TWiki pages.
• Template Topics: Define default text when you create a new topic

Tip: TWiki:TWiki.TWikiTemplatesSupplement on TWiki.org has supplemental documentation on TWiki templates.

Master Templates

Master templates are also used in the definition of TWikiSkins.

Master templates are stored as text files with the extension .tmpl. They are usually HTML with embedded template directives. The directives are expanded when TWiki wants to generate a user interface screen.

How Template Directives Work

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

TMPL:P also supports simple parameters. For example, given the definition %TMPL:DEF{"x"}% x%P%z%TMPL:END% then %TMPL:P{"x" P="y"}% will expand to xyz.

Note that parameters can simply be ignored; for example, %TMPL:P{"x"}% will expand to x%P%z.

Any alphanumeric characters can be used in parameter names. You are highly recommended to use parameter names that cannot be confused with TWikiVariables.

Note that three parameter names, context, then and else are reserved. They are used to support a limited form of "if" condition that you can use to select which of two templates to use, based on a context identifier:

%TMPL:DEF{"link_inactive"}%<input type="button" disabled value="Link>%TMPL:END%
%TMPL:DEF{"link_active"}%<input type="button" onclick="link()" value="Link" />%TMPL:END%
%TMPL:P{context="inactive" then="inactive_link" else="active_link"}% for %CONTEXT%

Finding Templates

The master templates shipped with a twiki release are stored in the twiki/templates directory. As an example, 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.

1. 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.
2. templates/script.skin.tmpl for each skin on the skin path
3. templates/web/script.tmpl
   • this usage is supported for compatibility only and is deprecated. Store web-specific templates in TWiki topics instead.
4. templates/script.tmpl
5. The TWiki topic aweb.atopic if the template name can be parsed into aweb.atopic
6. The TWiki topic web.SkinSkinScriptTemplate for each skin on the skin path
7. The TWiki topic web.ScriptTemplate
8. The TWiki topic %SYSTEMWEB%.SkinSkinScriptTemplate for each skin on the skin path
9. The TWiki topic %SYSTEMWEB%.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

For example, the example template file will be searched for in the following places, when the current web is Thisweb and the skin path is print,pattern:

1. templates/Thisweb/example.print.tmpl deprecated; don't rely on it
2. templates/Thisweb/example.pattern.tmpl deprecated; don't rely on it
3. templates/example.print.tmpl
4. templates/example.pattern.tmpl
5. templates/Thisweb/example.tmpl deprecated; don't rely on it
6. templates/example.tmpl
7. Thisweb.PrintSkinExampleTemplate
8. Thisweb.PatternSkinExampleTemplate
9. Thisweb.ExampleTemplate
10. TWiki.PrintSkinExampleTemplate
11. TWiki.PatternSkinExampleTemplate
12. TWiki.ExampleTemplate

Template names are usually derived from the name of the currently executing script; however it is also possible to override these settings in the view and edit scripts, for example when a topic-specific template is required. Two preference variables can be 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.

Both VIEW_TEMPLATE and EDIT_TEMPLATE may contain TWiki variables, which are expanded. For example, the following setting causes Item* topics to be displayed with the custom view template ItemViewTmpl while the other topics are displayed normally.

   * Set VIEW_TEMPLATE = %IF{"'%CALCULATE{$SUBSTRING(%TOPIC%, 1, 4)}%' = 'Item'" then="ItemViewTmpl"}%

   * Set EDIT_TEMPLATE = %IF{"'%CALCULATE{$SUBSTRING(%TOPIC%, 1, 4)}%' = 'Item'" then="editform"}%

Tip: If you want to override existing templates, without having to worry that your changes will get overwritten by the next TWiki update, change the {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 recursion for piecewise customization, or mixing in new features

If there is recursion in the TMPL:INCLUDE chain (eg twiki.classic.tmpl contains %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%

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.

Default master template

twiki.tmpl is the default master template. It defines the following sections.

Template Topics

The second type of template in TWiki are template topics. Template topics define the default text for new topics. There are four types of template topic:

When you create a new topic using the edit script, TWiki locates a topic to use as a content template according to the following search order:

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

Variable Expansion

TWikiVariables located in template topics get expanded as follows when a new topic is created.

1. Default variable expansion

The following variables used in a template topic automatically get expanded when new topic is created based on it:

2. Preventing variable expansion

In a template topic, embed text that you do not want expanded inside a %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"}%

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

3. Causing variable expansion in a section

You can forcefully expand TWikiVariables by placing them inside a 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 me

you 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

4. Specifying variables to be expanded individually

You may want to mix variables to be expanded and variables not to be. By prepending a variable name with 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"
}%

Specifying a Form

When you create a new topic based on a template, you often want the new topic to have a form attached to it. You can attach a form to the template topic, in which case it will be copied into the new topic.

Sometimes this isn't quite what you want, as it copies all the existing data from the template topic into the new topic. To avoid this and use the default values specified in the form definition instead, you can use the 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.

Automatically Generated Unique Topic Names

For TWiki applications it is useful to be able to automatically generate unique topic names, such as BugID0001, BugID0002, etc. You can add 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)

Characters after 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

Example link to create a new topic:

[[%SCRIPTURLPATH{edit}%/%WEB%/BugIDAUTOINC00001?templatetopic=BugTemplate;topicparent=%TOPIC%;t=%SERVERTIME{"$day$hour$min$sec"}%][Create new item]]

Note: After the save operation, the web client is redirected to the newly created topic by default. If the specified topic name contains AUTOINC<n> and you want to redirect to a different URL containing the newly created topic's name, you can use AUTOINC in the redirectto parameter. Let's say the specified topic name is ItemAUTOINC0001, and redirectto is set to %SCRIPTURL{view}%/%WEB%/ViewerTopic?id=ItemAUTOINC. If the latest existing topic is Item0123, a new topic named Item0124 is created, and the web client is redirected to ViewerTopic?id=Item0124 in the current web.

Template Topics in Action

Here is an example for creating new topics (in the Sandbox web) based on a specific template topic and form:

The above form asks for a topic name. A hidden input tag named templatetopic specifies ExampleTopicTemplate as the template topic to use. Here is the 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>

Note: You can create a topic in one step, without going through the edit screen. To do that, specify the 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>

The edit and save scripts understand many more parameters, see TWikiScripts#edit and TWikiScripts#save for details.

TIP: You can use the %WIKIUSERNAME% and %DATE% variables in your topic templates to include the signature of the person creating a new topic. The variables are expanded into fixed text when a new topic is created. The standard signature is:
-- %WIKIUSERNAME% - %DATE%

Using Absolute vs Relative URLs in Templates

When you use TWikiVariables such as %PUBURL% and %PUBURLPATH% in templates you should be aware that using %PUBURL% instead of %PUBURLPATH% puts absolute URLs in the produced HTML. This means that when a user saves a TWiki page in HTML and emails the file to someone outside a company firewall, the receiver has a severe problem viewing it. It is therefore recommended always to use the %PUBURLPATH% to refer to images, CSS, Javascript files etc so links become relative. This way browsers just give up right away and show a usable html file.

Related Topics: TWikiSkins, TWikiForms, TWikiScripts, DeveloperDocumentationCategory, AdminDocumentationCategory

TWiki Skins

A skin overlays regular templates to provide specific look and feel to TWiki screens.

Overview

TWiki uses TWikiTemplates files as the basis of all the screens it uses to interact with users. Each screen has an associated template file that contains the basic layout of the screen. This is then filled in by the code to generate what you see in the browser.

TWiki ships with a default set of template files that give a very basic, CSS-themable, look-and-feel. TWiki also includes support for skins that can be selected to give different, more sophisticated, look and feel. A default TWiki installation will usually start up with the PatternSkin already selected. Skins may also be defined by third parties and loaded into a TWiki installation to give more options. To see how TWiki looks when no skin is selected, view the current page with a non-existing skin.

TWiki topic content is not affected by the choice of skin, however a skin can be defined to use a CSS (Cascading Style Sheet) which can provide a radically different appearance to the text layout.

Relevant links on TWiki.org:

• TWiki:TWiki.TWikiSkinsSupplement - tip: supplemental documentation on TWiki skins
• TWiki:Plugins.SkinPackage - list of all contributed skin packages
• TWiki:Plugins.SkinDevelopment - discussion and feedback on contributed skins
• TWiki:Plugins.SkinBrainstorming - open forum for new skin ideas
• TWiki:Plugins.SkinPackageHowTo - template to create a new skin package

See other types of extensions: TWikiAddOns, TWikiContribs, TWikiPlugins

Changing the default TWiki skin

TWiki ships with the TopMenuSkin activated by default. You can set a skin for the whole site, a single web, a single topic, or for each user individually. This is done by setting the SKIN preferences setting to the name of a skin. If the skin you select doesn't exist, then TWiki will pick up the default templates. For example, to make the SKIN setting work across all topics and webs, put it in TWikiPreferences.

Skins can cascade using a skin path explained below. One skin can be based on another one, and extensions can introduce additional screen elements. For example, the TagMePlugin adds tag elements to the TopMenuSkin, and the TopMenuSkin is based on the PatternSkin, resulting in this skin path:

   * Set SKIN = tagme, topmenu, pattern

Defining Skins

You may want to define your own skin, for example to comply with corporate web guidelines, or because you have a aesthetic vision that you want to share. There are a couple of places you can start doing this.

The TWikiTemplates files used for skins are located in the 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:

<a href="http://twiki.org/"><img src="%PUBURL%/%SYSTEMWEB%/TWikiLogos/T-badge-88x31.gif" alt="This site is powered by the TWiki Enterprise Collaboration Platform" width="88" height="31" title="This site is powered by the TWiki Enterprise Collaboration Platform" border="0" /></a>

Renders as:

Note: TWiki.org has no marketing budget, e.g. we rely on TWiki users to spread the word of TWiki. You can support the open source project by adding logos that point back to TWiki.org, and by mentioning TWiki in social media.

The standard TWiki skins show the logo in the %WEBCOPYRIGHT% variable.

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

The following template files are used for TWiki screens, and are referenced in the TWiki core code. If a skin doesn't define its own version of a template file, then TWiki will fall back to the next skin in the skin path, or finally, to the default version of the template file.

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

• addform - used to select a new form for a topic
• attachagain - used when refreshing an existing attachment
• attachnew - used when attaching a new file to a topic
• attachtables - defines the format of attachments at the bottom of the standard topic view
  • ATTACH:files:footer, ATTACH:files:header, ATTACH:files:row, ATTACH:versions:footer, ATTACH:versions:header, ATTACH:versions:row
• changeform - used to change the form in a topic
• changes - used by the changes script
• edit - used for the edit screen
• form
• formtables - used to defined the format of forms
  • FORM:display:footer, FORM:display:header, FORM:display:row
• login - used for loggin in when using the TemplateLoginManager
  • LOG_IN, LOG_IN_BANNER, LOG_OUT, LOGGED_IN_BANNER, NEW_USER_NOTE, UNRECOGNISED_USER
• moveattachment - used when moving an attachment
• oopsaccessdenied - used to format Access Denied messages
  • no_such_topic, no_such_web, only_group, topic_access
• oopsattention - used to format Attention messages
  • already_exists, bad_email, bad_ver_code, bad_wikiname, base_web_missing, confirm, created_web, delete_err, invalid_web_color, invalid_web_name, in_a_group, mandatory_field, merge_notice, missing_action, missing_fields, move_err, missing_action, no_form_def, no_users_to_reset, notwikiuser, oversized_upload, password_changed, password_mismatch, problem_adding, remove_user_done, rename_err, rename_not_wikiword, rename_topic_exists, rename_web_err, rename_web_exists, rename_web_prerequisites, reset_bad, reset_ok, save_error, send_mail_error, thanks, topic_exists, unrecognized_action, upload_name_changed, web_creation_error, web_exists, web_missing, wrong_password, zero_size_upload
• oopschangelanguage - used to prompt for a new language when internationalisation is enabled
• 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.

Note: Make sure templates do not end with a newline. Any newline will expand to an empty <p /> in the generated html. It will produce invalid html, and may break the page layout.

Partial customization, or adding in new features to an existing skin

You can use recursion in the TMPL:INCLUDE chain (e.g. 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%

Variables in Skins

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

The Jump Box and Navigation Box

The default skins include a Jump Box, to jump to a topic.

The box also understands URLs, e.g. you can type http://www.google.com/ to jump to an external web site. The feature is handy if you build a skin that has a select box of frequently used links, like Intranet home, employee database, sales database and such. A little JavaScript gets into action on the 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}).

Using Cascading Style Sheets

CSS files are gererally attachments to the skin topic that are included in the the skin templates - in the case of PatternSkin in the template styles.pattern.tmpl.

• To see how CSS is used in the default TWiki skin, see: PatternSkin
• If you write a complete new skin, this is the syntax to use in a template file:

<style type='text/css' media='all'>@import url('%PUBURLPATH%/%SYSTEMWEB%/MySkin/mystyle.css');</style>

Attachment Tables

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

The format of tables of file versions in the Upload screen can also be changed, using the macros:

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

Packaging and Publishing Skins

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

Browsing Installed Skins

You can try out all installed skins in the TWikiSkinBrowser.

Activating Skins

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

TWiki works by asking for a template for a particular function - for example, 'view'. The detail of how templates are searched for is described in TWikiTemplates, but in summary, the templates directory is searched for a file called view.skin.tmpl, where skin is the name of the skin e.g. pattern. If no template is found, then the fallback is to use view.tmpl. Each skin on the path is searched for in turn. For example, if you have set the skin path to local,pattern then view.local.tmpl will be searched for first, then view.pattern.tmpl and finally view.tmpl.

The basic skin is defined by a SKIN setting:

• Set SKIN = catskin, bearskin

You can also add a parameter to the URL, such as ?skin=catskin,bearskin:

• http://twiki.oats.inaf.it/twiki/bin/view/TWiki/TWikiSkins?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

This pushes a different skin to the front of the skin search path (so for our example above, that final skin path will be ruskin, catskin, bearskin). There is also an equivalent cover URL parameter. The 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.

Conditional Skin Activation

TWiki skins can be activated conditionally using IfStatements. For example, you might want to use a mobile skin for iPhone and Android user agents, and the default skin otherwise. This example uses the print skin on iPhone and Android:

   * Set SKIN = %IF{
      "'%HTTP{"User-Agent"}%'~'*iPhone*' OR '%HTTP{"User-Agent"}%'~'*Android*'"
      then="print, pattern"
      else="topmenu, pattern"
     }%

Hard-Coded Skins

The text skin is reserved for TWiki internal use.

Skin names starting with rss also have a special meaning; if one or more of the skins in the skin path starts with 'rss' then 8-bit characters will be encoded as XML entities in the output, and the content-type header will be forced to text/xml.

Related Topics: TWikiSkinBrowser, AdminDocumentationCategory, DeveloperDocumentationCategory, TWiki:TWiki.TWikiSkinsSupplement

-- Contributors: TWiki:Main.PeterThoeny, TWiki:Main.MikeMannix, TWiki:Main.CrawfordCurrie

TWiki Variables

Special text strings expand on the fly to display dynamic content, such as 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:

1. Preferences variables: Can be defined and changed by the user.
   Example: %T% renders as
2. Predefined variables: Defined by the TWiki system or by extensions.
   Example: %CALCULATE{}% is handled by the SpreadSheetPlugin

See list of all TWiki Variables currently defined in this TWiki installation.

TWiki Variables Wizard — to Find and Compose Variables

Categories: all Administration Applications & Components Attachments & Files Charting & Drawing Database & Forms Date & Time Development Editing & Content Update Email & Notification Export & Publishing Formatting & Rendering Import Linking & Navigation Searching & Listing Security & Access Control Skins & Templates System Information Tables & Spreadsheets UI& Visualization Users & Authentication Workflow & Automation

Variables:

Pre-load image:

<--
-->

<--
-->

Using Variables

To use a variable type its name. For example,

• type %T% to get (a preferences variable)
• type %TOPIC% to get TWikiVariables (a predefined variable)
• type %CALCULATE{ "$UPPER(Text)" }% to get TEXT (a variable defined by a plugin)

Note:

• To leave a variable unexpanded, precede it with an exclamation point, e.g. type !%TOPIC% to get %TOPIC%
• Variables are expanded relative to the topic they are used in, not the topic they are defined in
• Type %ALLVARIABLES% to get a full listing of all variables defined for a particular topic

Variable Names

Variable names must start with a letter, optionally followed by letters, numbers and underscore '_' characters. Both upper-case and lower-case characters can be used, %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.

Preferences Variables

Unlike predefined variables, preferences variables can be defined by the user in various places.

Setting Preferences Variables

You can set variables in all the following places:

1. system level in TWiki.TWikiPreferences
2. plugin topics (see TWikiPlugins)
3. local site level in Main.TWikiPreferences
4. user level in individual user topics in Main web
   • If UserSubwebs is in effect, the topic specified by %USERPREFSTOPIC% in the user's subweb is read instead
   • If $TWiki::cfg{DemoteUserPreferences} is true, this step is deferred to a later step. On this TWiki installation, $TWiki::cfg{DemoteUserPreferences} is false
5. web level in WebPreferences of each web
6. If 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
7. topic level in topics in webs
8. session variables (if sessions are enabled)
9. user level preferences are set at this point if $TWiki::cfg{DemoteUserPreferences} is true as mentioned at the step 4

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

If you are setting a variable and using it in the same topic, note that TWiki reads all the variable settings from the saved version of the topic before it displays anything. This means you can use a variable anywhere in the topic, even if you set it somewhere inconspicuous near the end. But beware: it also means that if you change the setting of a variable you are using in the same topic, 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 = value

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:

   * Set VARIABLENAME = value starts here
     and continues here

Whatever you include in your variable will be expanded on display, exactly as if it had been entered directly.

Example: Create a custom logo variable

• To place a logo anywhere in a web by typing %MYLOGO%, define the Variable on the web's WebPreferences topic, and upload a logo file, ex: mylogo.gif. You can upload by attaching the file to WebPreferences, or, to avoid clutter, to any other topic in the same web, e.g. LogoTopic. Sample variable setting in WebPreferences:

      * Set MYLOGO = %PUBURL%/%WEB%/LogoTopic/mylogo.gif

You 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.

Controlling User Level Preferences Override

By default, user level variables are set at the step 4 as stated in the previous section. That means a user can finalise some preferences variables so that web level or topic level setting cannot override it. This may result in a situation the web or page owner doesn't expect. $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 ALLOWUSERPREFERENCES have been introduced.

• DENYUSERPREFEENCES and ALLOWUSERPREFERENCES may have comma separated list of variable names
• If a preferences variable is listed in 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
• If ALLOWUSERPREFERENCES 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 ALLOWUSERPREFERENCES has the same effect
• DENYUSERPREFEENCES takes precedence over ALLOWUSERPREFERENCES. If a variable is listed on both, it cannot be overridden. If DENYUSERPREFEENCES is "all", the value of ALLOWUSERPREFERENCES doesn't matter.

   * Set DENYUSERPREFERENCES = all

   * Set ALLOWUSERPREFERENCES = TINYMCEPLUGIN_DISABLE, SKIN

   * Set DENYUSERPREFERENCES = TINYMCEPLUGIN_DISABLE, SKIN

You will get the most benefit of DENYUSERPREFEENCES and ALLOWUSERPREFERENCES by setting $TWiki::cfg{DemoteUserPreferences} to true. That way, each web can specify how much user level preferences overriding is allowed.

Parameterized Variables (Macros)

It is possible to pass parameters to TWiki variables. This is called a macro in a programming language.

To define a parameterized variable, set a variable that contains other variables, such as:

   * 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 missing

• %EXAMPLE{ "foo" PARAM1="bar" PARAM2="baz" }%
• %DEMO{ "demo" PARAM2="parameter 2" }% -- note that PARAM1 is missing

Parameters in the variable definition are expanded using the following sequence:

1. Parameter from variable call. In above example, %PARAM1% gets expanded to bar.
2. Session variable and preferences settings

Example

Define variables:

   * Set DRINK = red wine
   * Set FAVORITE = My %DEFAULT{default="favorite"}% dish is %DISH{default="steak"}%,
                    my %DEFAULT{default="favorite"}% drink is %DRINK%.

Use Variables:

%FAVORITE{ DISH="Sushi" DRINK="Sake" }%

%FAVORITE{}%

%FAVORITE{ "preferred" }%

<--
Redefine what is defined in INCLUDE: 

 Set EXAMPLE = Example variable using favorite, (undefined) and (undefined)
 
 Set DEMO = Demo using favorite,                (undefined) and (undefined)
 
 Set DRINK = red wine
 
 Set FAVORITE = My favorite dish is steak,                    my favorite drink is %DRINK%.
 
-->

Access Control Variables

These are special types of preferences variables to control access to content. TWikiAccessControl explains these security settings in detail.

Local values for variables

Certain topics (a users home topic, web site and default preferences topics) have a problem; variables defined in those topics can have two meanings. For example, consider a user topic. A user may want to use a double-height edit box when they are editing their home topic - but only when editing their home topic. The rest of the time, they want to have a normal edit box. This separation is achieved using Local in place of Set in the variable definition. For example, if the user sets the following in their home topic:

   * Set EDITBOXHEIGHT = 10
   * Local EDITBOXHEIGHT = 20

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 Variables

The following preferences variables are frequently used. They are defined in TWikiPreferences#Miscellaneous_Settings:

• %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% - Help icon
• %I% - Idea icon
• %M% - Moved to icon
• %N% - New icon
• %P% - Refactor icon
• %Q% - Question icon
• %S% - Pick icon
• %T% - Tip icon
• %U% - Updated icon
• %X% - Alert icon
• %Y% - Done icon
• %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%)

There are additional useful preferences variables defined in TWikiPreferences, in Main.TWikiPreferences, and in WebPreferences of every web.

Predefined Variables

Most 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.

• Show all TWiki Variables
• Predefined variables can be overridden by preferences variables (except a few such as TOPIC and WEB)
  • This has long been the case but may not be desirable since even something as fundamental as %IF{...}%, %SCRIPT{...}%, and %INCLUDE{...}% can be overridden
  • So TWiki-6.0.1 has introduced a way to protect predefined variables from being overridden by preferences variables
  • The preferences variable OVERRIDABLEPREDEFINEDVARIABLES having a comma separated list of predefined variables specifies which predefined variables are overridable
  • By default, it's set to "all" (set at TWiki.TWikiPreferences), which means any predefined variable can be overridden, which is for compatibility with prior releases. You can set it to a different value in Main.TWikiPreferences and you may finalise it
  • If it's set as below, all predefined variables are protected

       * Set OVERRIDABLEPREDEFINEDVARIABLES =
    

  • If it's set as below, DATE and LANGUAGE predefined variables can be overridden but all the other predefined variables cannot

       * Set OVERRIDABLEPREDEFINEDVARIABLES = DATE, LANGUAGE
    

• Extensions may extend the set of predefined variables (see individual extension topics for details)
• Take the time to thoroughly read through ALL preference variables. If you actively configure your site, review variables periodically. They cover a wide range of functions, and it can be easy to miss the one perfect variable for something you have in mind. For example, see %INCLUDINGTOPIC%, %INCLUDE%, and the mighty %SEARCH%.

Search or List Variables by Category

All TWiki Variables: ACTIVATEDPLUGINS, ADDTOHEAD, ALLVARIABLES, AQUA, ATTACHURL, ATTACHURLPATH, AUTHREALM, BASETOPIC, BASEWEB, BB, BB2, BB3, BB4, BLACK, BLUE, BR, BROWN, BUBBLESIG, BULLET, CALC, CALCULATE, CARET, CHILDREN, COLORPICKER, COMMENT, CONTENTMODE, COPY, DASHBOARD, DATE, DATEPICKER, DISPLAYTIME, DISPLAYTIME2, EDITACTION, EDITFORM, EDITFORMFIELD, EDITTABLE, ENCODE, ENDBG, ENDCOLOR, ENDCOLUMNS, ENDSECTION, ENTITY, ENV, EXAMPLEVAR, FAILEDPLUGINS, FORM, FORMFIELD, FOURCOLUMNS, GET, GMTIME, GMTIME2, GRAY, GREEN, GROUPS, H, HEADLINES, HIDE, HIDEINPRINT, HOMETOPIC, HTTP, HTTPHOST, HTTPS, I, ICON, ICONURL, ICONURLPATH, IF, INCLUDE, INCLUDINGTOPIC, INCLUDINGWEB, JQENDTAB, JQENDTABPANE, JQTAB, JQTABPANE, LANGUAGE, LANGUAGES, LAQUO, LIME, LOCALSITEPREFS, LOGIN, LOGINURL, LOGOUT, LOGOUTURL, M, MAINWEB, MAKETEXT, MAROON, MDREPO, META, METASEARCH, N, NAVY, NBSP, NOP, NOTIFYTOPIC, OLIVE, ORANGE, P, PARENTBC, PARENTTOPIC, PINK, PLUGINDESCRIPTIONS, PLUGINVERSION, PUBURL, PUBURLPATH, PURPLE, Q, QUERYPARAMS, QUERYSTRING, RAQUO, RED, REDBG, REG, REMOTEADDR, REMOTEPORT, REMOTEUSER, RENDERLIST, REVINFO, REVINFO2, S, SCRIPTNAME, SCRIPTSUFFIX, SCRIPTURL, SCRIPTURL2, SCRIPTURLPATH, SCRIPTURLPATH2, SEARCH, SERVERTIME, SERVERTIME2, SESSIONID, SESSIONVAR, SESSIONVARIABLE, SET, SETGETDUMP, SILVER, SITENAME, SITESTATISTICSTOPIC, SLIDESHOWEND, SLIDESHOWSTART, SPACEDTOPIC, SPACEOUT, STARTINCLUDE, STARTSECTION, STATISTICSTOPIC, STOPINCLUDE, SYSTEMWEB, T, TABLE, TEAL, THREECOLUMNS, TM, TOC, TOC2, TOPIC, TOPICLIST, TOPICTITLE, TOPICURL, TWIKISHEET, TWIKIWEB, TWISTY, TWOCOLUMNS, U, URLPARAM, USERINFO, USERNAME, USERREPORT, USERSIG, USERSWEB, VAR, VBAR, WEB, WEBLIST, WEBPREFSTOPIC, WHITE, WIKIHOMEURL, WIKILOGOALT, WIKILOGOIMG, WIKILOGOURL, WIKINAME, WIKIPREFSTOPIC, WIKITOOLNAME, WIKIUSERNAME, WIKIUSERSTOPIC, WIKIVERSION, WIKIWEBMASTER, WIKIWEBMASTERNAME, WIP, X, Y, YELLOW, total 190 variables

Documenting TWiki Variables

This section is for people documenting TWiki variables of the TWiki core and TWiki extensions.

Each variable is documented in a topic named 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:

• Parent set to TWikiVariables
• An anchor named the same like the topic, such as #VarLIGHTSABER
• A ---+++ (level 3) heading with variable name, --, short description
• A bullet with description of the variable (optional)
• A Syntax: bullet with example syntax
• A Parameters: bullet with a table explaining the parameters (optional)
• An Example: bullet or two with examples
• An Expands to: bullet with expanded variable (optional)
• A Note: bullet with notes (optional)
• A Category: bullet with one or more of the TWiki variables categories:
  AdministrationVariables, ApplicationsAndComponentsVariables, AttachmentsAndFilesVariables, ChartingAndDrawingVariables, DatabaseAndFormsVariables, DateAndTimeVariables, DevelopmentVariables, EditingAndContentUpdateVariables, EmailAndNotificationVariables, ExportAndPublishingVariables, FormattingAndRenderingVariables, ImportVariables, LinkingAndNavigationVariables, SearchingAndListingVariables, SecurityAndAccessControlVariables, SkinsAndTemplatesVariables, SystemInformationVariables, TablesAndSpreadsheetsVariables, UIAndVisualizationVariables, UsersAndAuthenticationVariables, WorkflowAndAutomationVariables
• A Related: bullet with related links. Links have conditional IF so that links work properly locally in variable documentation topics and in the TWikiVariables topic

Example content of a 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

TWiki Plugins

Add functionality to TWiki with readily available plugins; create plugins based on APIs

Overview

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

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

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

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

Relevant links on TWiki.org:

• TWiki:TWiki.TWikiPluginsSupplement - tip: supplemental documentation on TWiki plugins
• TWiki:Plugins.PluginPackage - list of all contributed plugin packages
• TWiki:Plugins.PluginDevelopment - discussion and feedback on contributed plugins
• TWiki:Plugins.PluginBrainstorming - open forum for new plugin ideas
• TWiki:Plugins.PluginPackageHowTo - template to create a new plugin package

See other types of extensions: TWikiAddOns, TWikiContribs, TWikiSkins

Installing Plugins

The TWiki:Plugins web on TWiki.org is the repository for TWiki plugins. Each plugin such as the TWiki:Plugins.ChartPlugin has a topic with user guide, step-by-step installation instructions, a detailed description of any special requirements, version details, and a working example for testing. There's usually a number of other related topics, such as a developers page, and an appraisal page.

Most TWiki plugins are packaged so that they can be installed and upgraded using the configure script. To install a plugin, open up the Extensions tab, follow the "Find More Extensions" link, and follow the instructions. A plugin needs to be enabled after installation.

Plugins can also be installed manually: Download the zip or tgz package of a TWiki plugin from the TWiki.org repository, upload it to the TWiki server, unpack it, and follow the installation instructions found in the plugin topic on TWiki.org.

Special Requirements: Some plugins need certain Perl modules to be pre-installed on the host system. Plugins may also use other resources, like graphics, other modules, applications, and templates. You should be able to find detailed instructions in the plugin's documentation. Use the package manager of the server OS (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.

On-Site Pretesting

If you have a mission critical TWiki installation and you are concerned about installing new plugins, you can test new plugins before making them available by creating a second test TWiki installation, and test the plugin there. It is also possible to configure this test TWiki to use the live data. You can allow selected users access to the test area. Once you are satisfied that it won't compromise your primary installation, you can install it there as well.

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

Some Notes on Plugin Performance

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

If you need to install an "expensive" plugin, but you only need its functionality only in a subset of your data, you can disable it elsewhere by defining the %DISABLEDPLUGINS% TWiki variable.

Define 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

Managing Installed Plugins

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

Enabling/Disabling Plugins

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

Plugin Evaluation Order

By default, TWiki executes plugins in alphabetical order on plugin name. It is possible to change the order, for example to evaluate database variables before the spreadsheet CALCs. This can be done with {PluginsOrder} in the plugins section of configure.

Plugin-Specific Settings

Plugins can be configured with 1. preferences settings and/or 2. with configure settings. Older plugins use plugin preferences settings defined in the plugin topic, which is no longer recommended.

1. Use preferences settings:

Adinistrators can set plugin-specific settings in the local site preferences at Main.TWikiPreferences and users can overload them at the web level and page level. This approach is recommended if users should be able to overload settings. For security this is not recommended for system settings, such as a path to an executable. By convention, preferences setting names start with the plugin name in all caps, and an underscore. For example, to set the cache refresh period of the TWiki:Plugins.VarCachePlugin, add this bullet in Main.TWikiPreferences

• Set VARCACHEPLUGIN_REFRESH = 24

Preferences settings that have been defined in Main.TWikiPreferences can be retrieved anywhere in TWiki with %<pluginname>_<setting>%, such as %VARCACHEPLUGIN_REFRESH%.

To learn how this is done, use the TWiki:Plugins.VarCachePlugin documentation and Perl plugin code as a reference.

2. Use configure settings:

The administrator can set plugin settings in the configure interface. Recommended if only site administrators should be able to change settings. Chose this option to set sensitive or dangerous system settings, such as passwords or path to executables. To define plugin-specific configure settings,

• Create a Config.spec file in lib/TWiki/Plugins/YourPlugin/ with variables, such as
  $TWiki::cfg{Plugins}{RecentVisitorPlugin}{ShowIP} = 0;
• In the plugin, use those those variables, such as
  $showIP = $TWiki::cfg{Plugins}{RecentVisitorPlugin}{ShowIP} || 0;

To learn how this is done, use the TWiki:Plugins.RecentVisitorPlugin documentation and Perl plugin code as a reference.

In either case, define a SHORTDESCRIPTION setting in two places:

• As a setting in the plugin documentation, which is needed for the extension reports on twiki.org. Example:
  
  • Set SHORTDESCRIPTION = Show recent visitors to a TWiki site
• As a global Perl package variable in the plugin package, which is needed by TWiki to show info on installed plugins. Example:
  our $SHORTDESCRIPTION = 'Show recent visitors to a TWiki site';

For better performance, make sure you define this in the plugin package:
our $NO_PREFS_IN_TOPIC = 1;

Listing Active Plugins

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

This site is running TWiki version TWiki-6.1.0, Mon, 16 Jul 2018, build 30610, plugin API version 6.10

%ACTIVATEDPLUGINS%

%PLUGINDESCRIPTIONS%

• SpreadSheetPlugin (2018-07-05, $Rev: 30478 (2018-07-16) $): Add spreadsheet calculation like "$SUM( $ABOVE() )" to TWiki tables or anywhere in topic text
• BackupRestorePlugin (2018-07-10, $Rev: 30551 (2018-07-16) $): Administrator utility to backup, restore and upgrade a TWiki site
• ColorPickerPlugin (2018-07-05, $Rev: 30442 (2018-07-16) $): Color picker, packaged for use in TWiki forms and TWiki applications
• CommentPlugin (2018-07-05, $Rev: 30530 (2018-07-16) $): Quickly post comments to a page without an edit/preview/save cycle
• DBIQueryPlugin (2011-03-13, $Rev: 20722 (2011-05-10) $): Make complex database queries using DBI Perl module
• DatePickerPlugin (2018-07-05, $Rev: 30446 (2018-07-16) $): Pop-up calendar with date picker, for use in TWiki forms, HTML forms and TWiki plugins
• EditTablePlugin (2018-07-05, $Rev: 30448 (2018-07-16) $): Edit TWiki tables using edit fields, date pickers and drop down boxes
• HeadlinesPlugin (2018-07-13, $Rev: 30560 (2018-07-16) $): Show headline news in TWiki pages based on RSS and ATOM news feeds from external sites
• InterwikiPlugin (2018-07-05, $Rev: 30454 (2018-07-16) $): Write ExternalSite:Page to link to a page on an external site based on aliases defined in a rules topic
• JQueryPlugin (2018-07-05, $Rev: 30456 (2018-07-16) $): jQuery JavaScript library for TWiki
• PreferencesPlugin (2018-07-05, $Rev: 30528 (2018-07-16) $): Allows editing of preferences using fields predefined in a form
• SetGetPlugin (2018-07-05, $Rev: 30472 (2018-07-16) $): Set and get variables and JSON objects in topics, optionally persistently across topic views
• SlideShowPlugin (2018-07-05, $Rev: 30474 (2018-07-16) $): Create web based presentations based on topics with headings.
• SmiliesPlugin (2018-07-05, $Rev: 30476 (2018-07-16) $): Render smilies as icons, like  :-)  as or  :eek:  as
• TWikiSheetPlugin (2018-07-15, $Rev: 30604 (2018-07-16) $): Add TWiki Sheet spreadsheet functionality to TWiki tables
• TablePlugin (2018-07-05, $Rev: 30480 (2018-07-16) $): Control attributes of tables and sorting of table columns
• TagMePlugin (2018-07-05, $Rev: 30482 (2018-07-16) $): Tag wiki content collectively or authoritatively to find content by keywords
• TinyMCEPlugin (2018-07-10, $Rev: 30541 (2018-07-16) $): Integration of the Tiny MCE WYSIWYG Editor
• TwistyPlugin (2018-07-06, $Rev: 30497 (2018-07-16) $): Twisty section JavaScript library to open/close content dynamically
• WatchlistPlugin (2018-07-10, $Rev: 30536 (2018-07-16) $): Watch topics of interest and get notified of changes by e-mail
• WysiwygPlugin (2018-07-06, $Rev: 30528 (2018-07-16) $): Translator framework for WYSIWYG editors

%FAILEDPLUGINS%

The TWiki Plugin API

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

Available Core Functions

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

Note: If you use other core functions not described in Func.pm, you run the risk of creating security holes. Also, your plugin will likely break and require updating when you upgrade to a new version of TWiki.

Predefined Hooks

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

• All but the initPlugin are commented out. To enable a callback, remove the leading # from all lines of the callback.

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

Hints on Writing Fast Plugins

• Delay initialization as late as possible. For example, if your plugin is a simple syntax processor, you might delay loading extra Perl modules until you actually see the syntax in the text.
  • For example, use an eval block like this:
    eval { require IPC::Run }
return "<font color=\"red\">SamplePlugin: Can't load required modules ($@)</font>" if $@;
• Keep the main plugin package as small as possible; create other packages that are loaded if and only if they are used. For example, create sub-packages of BathPlugin in lib/TWiki/Plugins/BathPlugin/.
• Avoid using preferences in the plugin topic; Define $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).
• Use registered tag handlers.
• Measure the performance to see the difference.

Version Detection

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

• All plugin packages require a $VERSION variable. This should be an integer, or a subversion version id.

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

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

Security

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

Creating Plugins

With a reasonable knowledge of the Perl scripting language, you can create new plugins or modify and extend existing ones. Basic plug-in architecture uses an Application Programming Interface (API), a set of software instructions that allow external code to interact with the main program. The TWiki Plugin API provides the programming interface for TWiki. Understanding how TWiki is working at high level is beneficial for plugin development.

Anatomy of a Plugin

A (very) basic TWiki plugin consists of two files:

• a Perl module, e.g. MyFirstPlugin.pm
• a documentation topic, e.g. MyFirstPlugin.txt

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

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

The TWiki:Plugins.BuildContrib module provides a lot of support for plugins development, including a plugin creator, automatic publishing support, and automatic installation script writer. If you plan on writing more than one plugin, you probably need it.

Creating the Perl Module

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

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

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

Writing the Documentation Topic

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

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

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

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

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

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

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

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

Packaging for Distribution

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

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

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

Measuring and Improving the Plugin Performance

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

See also Hints on Writing Fast Plugins.

Publishing for Public Use

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

Publish your plugin by following these steps:

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

Once you have done the above steps once, you can use the BuildContrib to upload updates to your plugin.

Thank you very much for sharing your plugin with the TWiki community

Recommended Storage of Plugin Specific Data

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

Plugin Internal Data

You can create a plugin "work area" using the TWiki::Func::getWorkArea() function, which gives you a 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.

Web Accessible Data

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

Recommendation for file name:

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

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

Recommendation for file names in plugin attachment area:

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

Integrating with configure

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.

Structure of a Config.spec file

# ---+ 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.

# **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;

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:

All types can be followed by a comma-separated list of attributes.

See 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 } ];

TWiki:TWiki/SpecifyingConfigurationItemsForExtensions has supplemental documentation on configure settings.

Maintaining Plugins

Discussions and Feedback on Plugins

Each published plugin has a plugin development topic on TWiki.org. Plugin development topics are named after your plugin and end in Dev, such as MyFirstPluginDev. The plugin development topic is a great resource to discuss feature enhancements and to get feedback from the TWiki community.

Maintaining Compatibility with Earlier TWiki Versions

The plugin interface (TWikiFuncDotPm functions and plugin handlers) evolve over time. TWiki introduces new API functions to address the needs of plugin authors. Plugins using unofficial TWiki internal functions may no longer work on a TWiki upgrade.

Organizations typically do not upgrade to the latest TWiki for many months. However, many administrators still would like to install the latest versions of a plugin on their older TWiki installation. This need is fulfilled if plugins are maintained in a compatible manner.

Tip: Plugins can be written to be compatible with older and newer TWiki releases. This can be done also for plugins using unofficial TWiki internal functions of an earlier release that no longer work on the latest TWiki codebase. Here is an example; the TWiki:TWiki.TWikiPluginsSupplement#MaintainPlugins has more details.

    if( $TWiki::Plugins::VERSION >= 1.1 ) {
        @webs = TWiki::Func::getListOfWebs( 'user,public' );
    } else {
        @webs = TWiki::Func::getPublicWebList( );
    }

Handling deprecated functions

From time-to-time, the TWiki developers will add new functions to the interface (either to TWikiFuncDotPm, or new handlers). Sometimes these improvements mean that old functions have to be deprecated to keep the code manageable. When this happens, the deprecated functions will be supported in the interface for at least one more TWiki release, and probably longer, though this cannot be guaranteed.

When a plugin defines deprecated handlers, a warning will be shown in the list generated by %FAILEDPLUGINS%. Admins who see these warnings should check TWiki.org and if necessary, contact the plugin author, for an updated version of the plugin.

Updated plugins may still need to define deprecated handlers for compatibility with old TWiki versions. In this case, the plugin package that defines old handlers can suppress the warnings in %FAILEDPLUGINS%.

This is done by defining a map from the handler name to the TWiki::Plugins version in which the handler was first deprecated. For example, if we need to define the endRenderingHandler for compatibility with TWiki::Plugins versions before 1.1, we would add this to the plugin:

package TWiki::Plugins::SinkPlugin;
use vars qw( %TWikiCompatibility );
$TWikiCompatibility{endRenderingHandler} = 1.1;