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:
- 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
- WebTopicEditTemplate in the current web
- 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. guest (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. WikiGuest |
%WIKIUSERNAME% |
User name of user who is creating the new topic, e.g. Main.WikiGuest |
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.
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:
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" /> <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>
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 you must use the "post" method. Example:
<form name="new" action="%SCRIPTURLPATH{save}%/Sandbox/" method="post">
...
</form>
See
CommandAndCGIScripts#edit for details of the parameters that the
edit
script understands.
You can use the
%WIKIUSERNAME%
and
%DATE%
macros in your template topics to include the signature of the person creating a new topic. The macros 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
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.