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="/foswiki/Knowledge/Departments/IT/WebHome">IT Knowledgebase</a>
Storage of the TopicTitle
The TopicTitle is stored in one of these places:
- eitehr in a formfield of a DataForm named "TopicTitle<lang>"
- or in a formfield "TopicTitle",
- or in a preference setting
TOPICTITLE_<lang>
- 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 |
hideautoinc="on/off" |
boolean to suppress a return value in case the TopicName matches ...AUTOINC or ...XXXXXXXXXX |
off |
rev="..." |
revision of the topic |
latest revision |
"..." or topic="..." |
name of the topic to read the title of |
current topic |
default="..." |
default string to return in case the topic does not have a TopicTitle |
TopicName |
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
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
None
Change History
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 |