TopicTitlePlugin

Free-form title for topics

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="/bin/view/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
translate="on/off"	boolean switch to enable/disable translation of the title, either using Foswiki's internal i18n system or MultiLingualPlugin if installed	off
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

Creating a WikiWord from a random text string

Sometimes you need to create a proper WikiWord given a free-form text string like the topic title. For example this is the case when creating a new topic based on a given topic title. You then need the "wikified" version if the topic title to be used as the topic name.

Syntax:

%WIKIWORD{"..."}%

"..." or text="..."

random string, may contain formating tokens such as $percnt and $dollar etc

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

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab → "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

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

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
Text::Unidecode	>=1.30	Required

Change History

02 Dec 2024	adedd WIKIWORD macro
10 Oct 2024	added translate parameter
17 Jan 2024	added perl api to set a topic title
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