Documentation of the TWiki Implementation (version TWiki-6.1.0, Mon, 16 Jul 2018, build 30610)

• (1) Wiki Username vs. Login Username
• (2) TWiki Access Control
• (3) Wiki Templates
• (4) Wiki Variables
• (5) Notification of Changes by Email
• (6) TWiki Category Table
• (7) Implementation Notes
• (8) Installation Notes
• (9) Upgrading Earlier Versions of TWiki

Related Topics: TWikiWeb, TWikiHistory, TWikiPlannedFeatures, TWikiEnhancementRequests.

---

(1) Wiki Username vs. Login Username

Warning: Can't find topic TWiki.TWikiUsernameVsLoginUsername

---

(2) TWiki Access Control

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

A member of the Super Admin Group has unrestricted access throughout the TWiki, so only trusted staff should be added to this group.

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 >

Note that you do not require ROOTCHANGE access to rename an existing top-level web. You just need WEBCHANGE in the web itself.

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;
';

In this example:

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

And here are some rules:

• 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

That is achieve by the following settings on WebPreferences.

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

DENYROOT* and ALLOWROOT* are not subject to variable expansion. Because there has been no good use cases presented.

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%

This is not a good way to use dynamic access control but it does restrict access only to those listed in MEMBERS. However, access control doesn't work as expected when WebA.TopicB is accessed from WebC.TopicD by %INCLUDE{WebA.TopicB}% or other variables. This is because %MEMBERS% is defined in WebA and may have a different value in other webs.

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

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

This is because when a topic (e.g. WebC.TopicD) is accessed from browser and the topic refers to another topic in a different web (e.g. WebA.TopicB) and the different web employs dynamic access control, access to another topic is defined being on the safer side.

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%

[This is not a good way to use dynamic access control

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;

and having the following line on your WebPreferences and then finalise DENYUSERPREFEENCES.

   * Set DENYUSERPREFEENCES = all

Please read TWikiVariables#ControllingUserLevelPrefsOverride for details.

Again by default, predefined variables such as %IF{...}% can be overridden by preferences variables. If user preferences are disabled, ordinary users cannot attack using user preferences, but topic level preferences may cause unexpected consequences. As such, all predefined variables need to be made un-overridable by having the following line on WebPreferences and then finalise OVERRIDABLEPREDEFINEDVARIABLES.

   * Set OVERRIDABLEPREDEFINEDVARIABLES =

Please read TWikiVariables#PredefinedVariables for details.

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]]

Please note that setting it on a topic other than WebPreferences does not take effect. This is a limitation of the current implementation.

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

In a large organization, TWiki may need to depend on user and group data provided by its infrastructure. Custom user/group notations are handy in such situations though it's not trivial to implement. Please read here for details.

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

---

(3) Wiki Templates

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

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

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%

When the "inactive" context is set, then this will expand the "link_inactive" template; otherwise it will expand the "link_active" template. See IfStatements for details of supported context identifiers.

Finding Templates

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

Legend:

• script refers to the script name, e.g view, edit
• Script refers to the same, but with the first character capitalized, e.g View
• skin refers to a skin name, e.g dragon, pattern. All skins are checked at each stage, in the order they appear in the skin path.
• Skin refers to the same, but with the first character capitalized, e.g Dragon
• web refers to the current web

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

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

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

If these preferences are set locally (using Local instead of Set) for a topic, in WebPreferences, in Main.TWikiPreferences, or TWiki.TWikiPreferences (using Set), the indicated templates will be chosen for view and edit respectively. The template search order is as specified above.

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"}%

The following setting causes Item* topics to be edited with the editform template (edits only the TWiki form of the topic without editing the topic text) while the other topics are edited normally.

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

and then set SKIN=yourlocal,pattern

The default {TemplatePath} will not give you the desired result if you put these statements in the topic Thisweb.YourlocalSkinViewTemplate. The default {TemplatePath} will resolve the request to the template/view.pattern.tmpl, before it gets to the Thisweb.YourlocalSkinViewTemplate resolution. You can make it work by prefixing the {TemplatePath} with: $web.YourlocalSkin$nameTemplate.

Default master template

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

Template variable:	Defines:
%TMPL:DEF{"sep"}%	"|" separator
%TMPL:DEF{"htmldoctype"}%	Start of all HTML pages
%TMPL:DEF{"standardheader"}%	Standard header (ex: view, index, search)
%TMPL:DEF{"simpleheader"}%	Simple header with reduced links (ex: edit, attach, oops)
%TMPL:DEF{"standardfooter"}%	Footer, excluding revision and copyright parts

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:

Topic Name:	What it is:
WebTopicViewTemplate	Alert page shown when you try to view a nonexistent topic. This page is usually used as a prompt to help you create a new topic.
WebTopicNonWikiTemplate	Alert page shown when you try to view a nonexistent topic with a non-WikiName. Again, this page is used as a prompt to help you create the new topic.
WebTopicEditTemplate	Default text used in a new topic.
<MyCustomNamed>Template	Whenever you create a topic ending in the word "Template", it is automatically added to the list of available templates in the "Use Template" drop down field on the WebCreateNewTopic page.

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:

Variable:	Description:
%DATE%	Signature format date. See VarDATE
%GMTIME%	Date/time. See VarGMTIME
%GMTIME{...}%	Formatted date/time. See VarGMTIME2
%NOP%	A no-operation variable that gets removed. Useful to prevent a SEARCH from hitting an edit template topic; also useful to escape a variable, such as %URLPA%NOP%RAM{...}% escaping URLPARAM
%STARTSECTION{type="templateonly"}% ... %ENDSECTION{type="templateonly"}%	Text that gets removed when a new topic based on the template is created. See notes below.
%SERVERTIME%	Date/time. See VarSERVERTIME
%SERVERTIME{...}%	Formatted date/time. See VarSERVERTIME2
%USERNAME%	Login name of user who is instantiating the new topic, e.g. guest
%URLPARAM{"name"}%	Value of a named URL parameter. See VarURLPARAM.
%WIKINAME%	WikiName of user who is instantiating the new topic, e.g. TWikiGuest
%WIKIUSERNAME%	User name of user who is instantiating the new tpoic, e.g. Main.TWikiGuest

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"}%

This will restrict who can edit the template topic, but will be removed when a new topic based on that template topic is created.

%NOP% can be used to prevent expansion of TWiki variables that would otherwise be expanded during topic creation. For example, escape %SERVERTIME% with %SER%NOP%VERTIME%.

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"
}%

This yields a series of %INCLUDE{...}%s, which are not expanded. This is not achievable by an expandvariables section.

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:

• New example topic:

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

---

(4) Wiki Variables

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:

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.

For example, if you don't allow overriding at the user level at all:

   * Set DENYUSERPREFERENCES = all

If you allow INYMCEPLUGIN_DISABLE and SKIN to be set at the user level:

   * Set ALLOWUSERPREFERENCES = TINYMCEPLUGIN_DISABLE, SKIN

If you allow user preferences to set anything other than TINYMCEPLUGIN_DISABLE or SKIN:

   * Set DENYUSERPREFERENCES = TINYMCEPLUGIN_DISABLE, SKIN

Please note DENYUSERPREFEENCES and ALLOWUSERPREFERENCES affect user preferences regardless of $TWiki::cfg{DemoteUserPreferences}. You can set those variables at the site level while $TWiki::cfg{DemoteUserPreferences} setting to false. If you do so, you should finalise DENYUSERPREFEENCES and ALLOWUSERPREFERENCES. Otherwise, they might be overridden by user preferences.

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

which resolves to:

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

The default can be defined with a default parameter (%DISH{default="steak"}%), or as a preferences setting (Set DRINK = ...).

Use Variables:

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

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

%FAVORITE{}%

Returns:
%FAVORITE{}%

%FAVORITE{ "preferred" }%

Returns:
%FAVORITE{ "preferred" }%

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

Then when they are editing any other topic, they will get a 10 high edit box. However when they are editing their home topic, they will get a 20 high edit box. Local can be used wherever a preference needs to take a different value depending on where the current operation is being performed.

Use this powerful feature with great care! %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

---

(5) Notification of Changes by Email

Warning: Can't find topic TWiki.TWikiNotificationOfChanges

---

(6) TWiki Category Table

Warning: Can't find topic TWiki.TWikiCategoryTable

---

(7) Implementation Notes

Warning: Can't find topic TWiki.TWikiImplementation

---

(8) Installation Notes

Warning: Can't find topic TWiki.TWikiInstallationNotes

---

(9) Upgrading Earlier Versions of TWiki

Warning: Can't find topic TWiki.TWikiUpgradeNotes