Free-form title for topics

Note that use of this plugin Foswiki >= 2.2.0 is not required. The purpose of this plugin is to backport the TopicTitle feature to earlier Foswiki versions.


This plugin implements a way to freely specify the title of a topic. The title is then used when rendering the link to the topic instead of just displaying the WikiWord that represents a topic. So let's recap the differences and the terminology:

A WikiWord consists of two or more words run together, also refered to as camel case capitalization. A WikiWord creates a hyperlink that points to a topic.
This is the name of a topic as it is displayed in the URL. In most cases this is a WikiWord, but this is not necessarily the case.
This is a free-form title string that is used as a link text of the WikiWord pointing to the topic.
This is the process of deriving a TopicName from a TopicTitle when creating, moving or renaming a topic. Wikification will create a proper WikiWord and optionally transliterate all non-ascci characters. See JQueryWikiWord.
This is the last part of the URL pointing to a topic of a web, just before the TopicName follows. The WebName of a nested web thus is specified by the part removing all parent WebNames as well as the TopicName of an URL. For example, given a fully quallified web-topic path such as: Knowledge.Departments.IT.WebHome, IT is the WebName
This is the TopicTitle of the WebHome of a web. It will be used when rendering the link text in a breadcrumb of a topic of that web, or whenever refering to the web, i.e. its WebHome. For example, given the topic Knowledge.Departments.IT.WebHome has got the TopicTitle "IT Knowledgebase", then the link [[Knowledge.Departments.IT.WebHome]] will render as <a href="/bin/view/Knowledge/Departments/IT/WebHome">IT Knowledgebase</a>

Storage of the TopicTitle

The TopicTitle is stored in one of two places:

  1. either in a formfield of a DataForm named "TopicTitle",
  2. or in a preference setting TOPICTITLE.

If a DataForm does not have a formfield "TopicTitle" or no DataForm at all will the TopicTitle be stored in the preference setting TOPICTITLE. You may change the name of the formfield being used as a TopicTitle using the TOPICTITLE_FIELD preference setting to this topic. For example, given you specified a DataForm "SystemForm" with a formfield "SystemName", the set TOPICTITLE_FIELD to "SystemName" to store the TopicTitle in there instead.

Note that in case that the TopicTitle is identical to its TopicName no TOPICTITLE prefrence will be set.

WARNING: When adding, changing or removing a DataForm holding a TopicTitle will it potentially be lost when editing and saving the topic.

Accessing the TopicTitle

There are multiple ways to read the TopicTitle:

  • %TOPICTITLE%: expands to the preference setting within a topic
  • %FORMFIELD{"TopicTitle"}%: read the formfield value
  • %QUERY{"'%TOPIC%'/preferences[name='TOPICTITLE'].value"}%: read the preference setting of a topic

depending on where the TopicTitle is stored. The most compatible way is to use %GETTOPICTITLE{...}%

Parameters Description Default
"..." or topic="..." name of the topic to read the title of current topic
rev="..." revision of the topic latest revision
default="..." default string to return in case the topic does not have a TopicTitle TopicName
hideautoinc="on/off" boolean to suppress a return value in case the TopicName matches ...AUTOINC or ...XXXXXXXXXX off
encode="quotes/url/entity" encode the result in the given way. See also VarENCODE  

Perl API

This plugin implements Foswiki::Func::getTopicTitle($web, $topic, $rev) for Foswiki versions before 2.2.0. You may also access the plugin's API directly using Foswiki::Plugins::TopicTitlePlugin::getTopicTitle(...).

This plugin sets the TopicTitleEnabled context flag that may be used in wiki applications depending on this feature. See IfStatements on how to read the context flags using the %IF makro.

Installation Instructions



cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install




Change History

14 Aug 2018 fixed renaming a topic changing subsequent topics being saved during the same request
28 May 2018 improved parsing of topic and web parameter
06 Apr 2018 initial version

PackageForm edit

Author Michael Daum
Version 1.02
Release 14 Aug 2018
Description Free-form title for topics
Repository https://github.com/foswiki/TopicTitlePlugin
Copyright 2018 Foswiki Contributors
License GPL (GNU General Public License)
Home https://foswiki.org/Extensions/TopicTitlePlugin
Support https://foswiki.org/Support/TopicTitlePlugin
Topic revision: r1 - 28 May 2018, ProjectContributor

Ideas, requests, problems regarding CFCL Wiki? Send feedback