Template topics

Foswiki uses several types of templates. Template topics are topics that define the default text for new topics.

(If you are looking for templates used to display existing topics, see SkinTemplates. These are combined with DataForms for custom presentation of topic data (View Template) and custom editing (Edit Template).

Overview

There are four types of template topics:

Topic Name:	What it is:
WebCreateNewTopicTemplate	Page shown when you click on a Create New Topic link. It provides a form requesting the necessary information to create a new, nonexistent topic.
TopicDoesNotExistViewTemplate	Alert page shown when you try to view a nonexistent topic and usually used as a prompt to help you create this new topic. For this reason, the form of the WebCreateNewTopicTemplate is included and therefore shown, too.
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 template topics in the "Use Template" drop down field on the WebCreateNewTopic page.

When you create a new topic using the edit script, the system locates a template topic 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 System web
2. WebTopicEditTemplate in the current web
3. WebTopicEditTemplate in the System web

Macro expansion

When the following macros are used in a template topic, they automatically get expanded when new topic is created based on it:

Macro:	Description:
%DATE%	Signature format date. See VarDATE
%GMTIME%	Date/time. See VarGMTIME
%GMTIME{...}%	Formatted date/time. See VarGMTIME
%NOP%	A no-operation macro 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 topic is created. See notes below.
%STARTSECTION{type="expandvariables"}% ... %ENDSECTION{type="expandvariables"}%	All Foswiki macros enclosed in this section type are expanded when a new topic based on the template topic is created. Otherwise only the macros listed in this table are expanded.
%SERVERTIME%	Date/time. See VarSERVERTIME
%SERVERTIME{...}%	Formatted date/time. See VarSERVERTIME
%USERNAME%	Login username of user who is instantiating the new topic, e.g. admin (On some systems this will be the same as the WikiName).
%URLPARAM{"name"}%	Value of a named URL or HTTP POST parameter
%WIKINAME%	WikiName of user who is creating the new topic, e.g. AdminUser
%WIKIUSERNAME%	User name of user who is creating the new topic, e.g. Main.AdminUser

Macro notes:

%STARTSECTION{type="templateonly"}%
...
%ENDSECTION{type="templateonly"}%

markers are used to embed text that you do not want expanded when a new topic based on the template topic is created. For example, you might want to write in the template topic:

%STARTSECTION{type="templateonly"}%
This template topic can only be changed by:
   * Set ALLOWTOPICCHANGE = Main.AdminGroup
%ENDSECTION{type="templateonly"}%

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

%NOP% can be used to prevent expansion of macros that would otherwise be expanded during topic creation e.g. escape %SERVERTIME% with %SER%NOP%VERTIME%.

All other macros are unchanged, e.g. are carried over "as is" into the new topic, unless they are contained within a %STARTSECTION{type="expandvariables"}% section.

Specifying a form

When you create a new topic based on a template topic, 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 automatically 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 parameter to the edit script to specify the name of a form to attach.

See CommandAndCGIScripts for information about this, and all the other parameters to edit.

Automatically generated topic names

For some applications it is useful to be able to automatically generate unique topicnames, 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)

Example link to create a new topic:

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

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 HTML source of the form:

<form name="new" action="%SCRIPTURLPATH{edit}%/%SANDBOXWEB%/" method="post">
New example topic: <input type="text" name="topic" class="foswikiInputField" value="ExampleTopicAUTOINC0001" size="30" />&nbsp;<input type="submit" class="foswikiSubmit" value="Create" />
<input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
<input type="hidden" name="topicparent" value="%TOPIC%" />
<input type="hidden" name="onlywikiname" value="on" />
<input type="hidden" name="onlynewtopic" value="on" />
</form>

Using absolute vs relative URLs in templates

When you use Macros such as %PUBURL% and %PUBURLPATH% in template topics 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 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.