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 System.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 System.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 System.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 System.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

PackageForm edit

Author Michael Daum
Version %$VERSION%
Release %$RELEASE%
Description %$SHORTDESCRIPTION%
Repository https://github.com/foswiki/TopicTitlePlugin
Copyright 2018-2022 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
This site is powered by FoswikiCopyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback