TemplateTopics < System

You are here: BACCHUS Wiki>System Web>ReferenceManual>TemplateTopics (revision 1) (raw view)
#TemplateTopics
---+ Template topics

_Template topics are topics that define the default text for new topics._

%TOC%

%STARTSECTION{"PowerUserGuide"}%
---++ Overview
There are four types of template topics:

| *Topic Name:* | *What it is:* |
| WebCreateNewTopicTemplate | Page shown when you click on a %ICON{newtopic}% *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. |
| &lt;MyCustomNamed&gt;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 %SYSTEMWEB% web
   1 <nop>WebTopicEditTemplate in the current web
   1 <nop>WebTopicEditTemplate in the %SYSTEMWEB% web

#TemplateTopicsVars
---++ 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:* |
| =%<nop>DATE%= | Signature format date. See VarDATE |
| =%<nop>GMTIME%= | Date/time. See VarGMTIME |
| =%<nop>GMTIME{...}%= | Formatted date/time. See VarGMTIME |
| =%<nop>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 =%<nop>URLPA%<nop>NOP%RAM{...}%= escaping URLPARAM |
| =%<nop>STARTSECTION{type="templateonly"}%%BR%...%BR%%<nop>ENDSECTION{type="templateonly"}%= | Text that gets removed when a new topic based on the template topic is created. See notes below. |
| =%<nop>STARTSECTION{type="expandvariables"}%%BR%...%BR%%<nop>ENDSECTION{type="expandvariables"}%= | All Foswiki macros in this section type are expanded when a new topic based on the template topic is created. Otherwise only the macros listed here are expanded. |
| =%<nop>SERVERTIME%= | Date/time. See VarSERVERTIME |
| =%<nop>SERVERTIME{...}%= | Formatted date/time. See VarSERVERTIME |
| =%<nop>USERNAME%= | Login name of user who is instantiating the new topic, e.g. %USERNAME% |
| =%<nop>URLPARAM{"name"}%= | Value of a named URL or HTTP POST parameter |
| =%<nop>WIKINAME%= | WikiName of user who is creating the new topic, e.g. <nop>%WIKINAME% |
| =%<nop>WIKIUSERNAME%= | User name of user who is creating the new topic, e.g. <nop>%WIKIUSERNAME% |

---+++ Macro notes:
<pre class="tml">%<nop>STARTSECTION{type="templateonly"}%%BR%...%BR%%<nop>ENDSECTION{type="templateonly"}%</pre> 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:
<pre class="tml">
%<nop>STARTSECTION{type="templateonly"}%
This template topic can only be changed by:
   * Set <nop>ALLOWTOPICCHANGE = <nop>%USERSWEB%.AdminGroup
%<nop>ENDSECTION{type="templateonly"}%
</pre>
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>NOP%= can be used to prevent expansion of [[macros]] that would otherwise be expanded during topic creation e.g. escape =%<nop>SERVERTIME%= with =%<nop>SER%<nop>NOP%VERTIME%=.

All other macros are unchanged, e.g. are carried over "as is" into the new topic, _unless they are contained within a %<nop>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=.

#AutomaticallyGeneratedTopicname
---++ 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&lt;n&gt;= to the topic name in the edit and save scripts, and it will be replaced with an auto-incremented number on topic save. =&lt;n&gt;= 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:%BR%
<verbatim class="tml">
[[%SCRIPTURLPATH{edit}%/%WEB%/BugIDAUTOINC00001?templatetopic=BugTemplate;topicparent=%TOPIC%;t=%SERVERTIME{"$day$hour$min$sec"}%][Create new item]]
</verbatim>

---++ Template topics in action

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

<form name="new" action="%SCRIPTURLPATH{edit}%/%SANDBOXWEB%/" method="post">
<div class="foswikiFormSteps">
<div class="foswikiFormStep foswikiLast">
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="%SYSTEMWEB%.ExampleTopicTemplate" />
<input type="hidden" name="topicparent" value="%TOPIC%" />
<input type="hidden" name="onlywikiname" value="on" />
<input type="hidden" name="onlynewtopic" value="on" />
</div>
</div>
</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:

<verbatim class="html">
<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="%SYSTEMWEB%.ExampleTopicTemplate" />
<input type="hidden" name="topicparent" value="%TOPIC%" />
<input type="hidden" name="onlywikiname" value="on" />
<input type="hidden" name="onlynewtopic" value="on" />
</form>
</verbatim>

<blockquote class="foswikiHelp"> *%X% 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:
<pre class="tml">
&lt;form name="new" action="%<nop>SCRIPTURLPATH{save}%/%SANDBOXWEB%/" method="post"&gt;
    ...
&lt;/form&gt;
</pre>

See CommandAndCGIScripts#edit for details of the parameters that the =edit= script understands.</blockquote>

<blockquote class="foswikiHelp">%T% You can use the =%<nop>WIKIUSERNAME%= and =%<nop>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: <br />
==-- %<nop>WIKIUSERNAME% - %<nop>DATE%== </blockquote>

---++ Using absolute vs relative URLs in templates

When you use [[Macros]] such as [[VarPUBURL][%<nop>PUBURL%]] and [[VarPUBURLPATH][%<nop>PUBURLPATH%]] in template topics you should be aware that using [[VarPUBURL][%<nop>PUBURL%]] instead of [[VarPUBURLPATH][%<nop>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 [[VarPUBURLPATH][%<nop>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.

%ENDSECTION{"PowerUserGuide"}%
<!-- %JQREQUIRE{"chili"}% -->
Topic revision: r1 - 18 Sep 2010, ProjectContributor
System
Copyright &© by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding BACCHUS Wiki? Send feedback