TopicTitlePlugin

%$SHORTDESCRIPTION%

Description

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:

WikiWord

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.

TopicName

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.

TopicTitle

This is a free-form title string that is used as a link text of the WikiWord pointing to the topic.

Wikification

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.

WebName

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

WebTitle

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="/Knowledge/Departments/IT/WebHome">IT Knowledgebase</a>

Storage of the TopicTitle

The TopicTitle is stored in one of these places:

1. eitehr in a formfield of a DataForm named "TopicTitle<lang>"
2. or in a formfield "TopicTitle",
3. or in a preference setting TOPICTITLE_<lang>
4. or in a preference setting TOPICTITLE.

(lang: upper case language code, eg. EN or DE)

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/safe"	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

%$INSTALL_INSTRUCTIONS%

Dependencies

%$DEPENDENCIES%

Change History

05 Mar 2022	add "safe" encoding mode
01 Apr 2020	added support for multilingual topic titles
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