usability1Add my vote for this tag create new tag
, view all tags

Proposed: Automatic link label based on first heading in topic

You get nice link labels if you pull the first heading from the linked topic and use it as the link label text. This proposed feature allows you to do that automatically. It is enabled with preferences settings, e.g. it can be set flexibly site-wide, per web or per topic.

  • Set NICELINKLABEL = on or Actual link label with optional $topic, $web and $heading

If the setting is set to on on SomeTopic (or site-wide or web-level), a [[SomeTopic]] link will show the First heading text of SomeTopic as the link label. The topic name will be used if there is no heading.

Note: The setting of the linked topic is used, not the setting where the link is located

If the setting is set to an Actual link label, the Actual link label will be shown. Optional tokens $topic, $web are expanded to topic name and web name, respectively. Optional token $heading is expanded to the first heading in the topic, or $topic if there is none.

Note: Only [[SomeTopic]] links are processed with the nice link label, normal WikiWord links render as usual.

The following setting makes [[SomeTopic]] link render as with current TWiki versions:

  • Set NICELINKLABEL = $topic

This is consistent with the proposed PageTitleVariable feature.

-- Contributors: PeterThoeny


The goal is to make this feature non-intrusive and easy to remember. Any other idea for syntax?

This is a small feature that probably should go into the core, not Plugin.

Possibly add same tokens the ToolTipTopicInfoOnWikiWordLinks setting understands, e.g. $summary to show the topic summary, $date for the last change date, $rev for the revision, $username for the login name of the last editor, $wikiname for the WikiName, $wikiusername for Main.WikiName, $topic for the topic name, and $web for web. That way you could construct a label like [[FooBar][$heading ($date by $wikiusername)]]

Implementation detail: Possibly add a topic info cache to speed up rendering, could be done together with caching of ToolTipTopicInfoOnWikiWordLinks.

-- PeterThoeny - 23 Jul 2004

A quick hack is a "small feature" yes, but cacheing topic info is not a quick hack, especially when you consider that these sorts of caches are getting more widespread; VarCachePlugin creates a cache, DBCachePlugin creates a cache (which already contains most of this info), and now you want this to cache as well. Doesn't that suggest that a strategic, designed approach to cacheing is preferable to another quick hack?

Now, question: why not use DBCachePlugin for the cache? It's already there, and writing something brand new sounds a bit pointless. Given that it's already there, and already cross-called by other plugin, why not do this as a plugin and leverage existing code? Why overload the core with yet more?

BTW on syntax; given that the first part of the []]][ may contain any kind of link, and this will operate specifically on topics, and we already have several meta-data access methods (REVINFO, META and FIELD; there are probably others), wouldn't it be better to rationalise this to a common syntax? One way to do this would be to use a simple consistent syntax for a topic link to recover field values in the topic. So, say, while TheWeb.TheTopic creates a link, $TheWeb.TheTopic.parent could be used to recover the name of the parent of the topic, TheWeb.TheTopic.revdate the date of the topic, and so on.

Thus instead of constantly adding new tags (like %REVINFO) we would simply add new fields to the cache record for the topic. The same consistent syntax would be used to recover them.

Using this scheme, this topic would be as simple as a request to add firstHeading to the cache record. Then [[TheTopic][$TheTopic.firstHeading]] would do what you want above. And [[TheTopic][$TheTopic.firstHeading - $Topic.Username $Topic.Revision $TheTopic.RevisionDate]] the rest.

Note that the DBCachePlugin already provides most of the functionality to do this. I know that I could write a plugin to do it in a few hours. This approach is incredibly powerful; please don't ignore it!

-- CrawfordCurrie - 23 Jul 2004

I see three different topics here, text should be refactored accordingly.

  1. Simple syntax to show first heading as the link label (this topic here)
  2. Enhance TWikiML with object oriented syntax to get at the content. I like this idea; it has been discussed elsewhere in Codev (can't find it right now)
  3. Caching of topic info

This topic here is about 1, a simple syntax to produce nice looking link labels. This could be combined with 2 as you point out, [[TheTopic][$TheTopic.firstHeading]], or we could invent a new syntax just for the needs of 1.

Just brainstorming on 1. An alternative would be to invent a new link syntax like {{FooBar}}. This would be faster to type then [[FooBar][$FooBar.firstHeading]].

-- PeterThoeny - 25 Jul 2004

OK, we'll stay focused on 1. The problem with a new syntax is that you'd have to invent a new syntax for every field you might want to extract that way. But if you think this "special case" is going to be common enough that it deserves it's own syntax, then OK, but IMHO it will be rarely used. If you do want a special syntax for this one particular field then it should be somehow mnemonic of the relationship to headings. Since ---+ is used for headings, how about ---+FooBar? Much faster to type than using curly braces (for me, anyway).

-- CrawfordCurrie - 25 Jul 2004

Well, I hate the syntax, I hate the fact that it's a hack, and I hate the fact that this sort of creeping feature is exactly what has knackered the perfomance (see CairoPerformanceExperiments), but I'm being ignored so here's a patch for the {{Topic}} and {{Web.Topic}} link syntax against 1617.

-- CrawfordCurrie - 27 Jul 2004

Note that this is the tip of a new iceberg. The shortcut syntax I implemented here can be scrubbed once the "right way" has been implemented. See ContentAccessSyntax

-- CrawfordCurrie - 28 Jul 2004

(Now, this topic truly requires refactoring!)

I am interested in two topic properties:

  • Be able to generate a link with latest version appended, such as ...bin/view/Main/TheTopic/v1.35. Why? Because this will let us see the changed topics automatically when referenced in any topic, using browser capability (which tracks Seen links).
  • Be able to mark a revision as "Published", and this link will be used for rendering. Perhaps requires session plugin support or a different skin.
Both of these to be available as $xyz variables, for use in topic link Preferences.

-- VinodKulkarni - 29 Jul 2004

I revised above spec based on how DokuWiki works. It offers [[SomeTopic]] links that render as SomeTopic in case the page does not have a heading, and renders as First Heading in case there is one. This is very intuitive and easy to use.

See also related PageTitleVariable

-- PeterThoeny - 09 Feb 2006

On the one hand this automated process would save a lot of time. But on the other hand I am not sure if the result is desirable in all cases. Look at the first header of this topic: Proposed: Automatic link label based on first heading in topic would become the link to this topic.

-- ArthurClemens - 10 Feb 2006

Which is the whole point. For example, writing this in DokuWiki:

  * [[twiki:acl]]
  * [[twiki:author]]
  * [[twiki:blacklist]]
  * [[twiki:captcha]]
  * etc...
produces a nicely looking list shown at http://www.wikimatrix.org/wiki/TWiki:intro.

Are you concerned about the length of the link label? Would a new $heading(30) be useful to cap the maximum number of chars shown? Such as: Proposed: Automatic link label...

-- PeterThoeny - 10 Feb 2006

I am not directly against, and the link list certainly looks human without the camel case, but my concern is that you will loose the "topic name as identifier" that is natural to wikis.

If I choose to put on my personal page the heading "Arthur's personal page", all occurences of my name as author will become

-- Arthur's personal page

It is a solution for one case, but will raise other problems.

-- ArthurClemens - 10 Feb 2006

So for the Main web it looks like it is better to Set NICELINKLABEL = $topic.

Another possibility is not to touch the WikiWords, and to only process [[SomeTopic]] links with the automated labels.

  • I updated above spec to exclude normal WikiWord rendering. -- PTh

-- PeterThoeny - 10 Feb 2006

To process bracket notation links is a good middle ground that will not overhaul existing linkages.

-- ArthurClemens - 10 Feb 2006

Arthur makes a good point that applies to the bracket notation too - if we change the rendered link text, we're moving further away from what you see in edit mode is what you see prettified in view mode.

and in this case I might write sentence like

Main.MartinCleaver, Main.CrawfordCurrie, Main.ColasNahaboo and I met in [[Fontainebleau]].

and instead the rendered version might become

MartinCleaver, CrawfordCurrie, ColasNahaboo and I met in Fontainebleau is a forest city.

There is a difference between what may make sense as a title for a topic, and the name use to referto a topic.

I might bet that this is a desired case in list making Wiki's, but when you have a TWiki that is a documentation repository, you probably are rarely if ever going to what how you refer to a topic be dependant on this weeks working title.

-- SvenDowideit - 10 Feb 2006

Sven, I am not totally sure this is not an edge case. This will occur if bracket notation if used for topics that are not wiki words.

But as we are brainstorming: another middle ground proposal: add the heading to the wiki name:

MartinCleaver, CrawfordCurrie, ColasNahaboo and I met in Fontainebleau Fontainebleau is a forest city.

-- ArthurClemens - 10 Feb 2006

Better Example. "This text ist written by TobiasRoeser This is the Wiki Home page of Tobias Roeser"

-- TobiasRoeser - 10 Feb 2006

You need to discern the naming part and the page heading: either by font size or color or background color.

-- ArthurClemens - 10 Feb 2006

Hmm, taking topic name and header as link label (with different style) would defeat the purpose of nice looking links as seen in http://www.wikimatrix.org/wiki/TWiki:intro. Actually, if we implement as suggested it can be done either way by using the tokens $topic and $heading.

-- PeterThoeny - 11 Feb 2006

I think changing the meaning of the good old [[WikiName]] notation is going to confuse people. TWiki is already pretty geeky - which is why people are crying for WYSIWYG. This is an unpredictable feature. If you want to make something like this choose a notation like [[WikiName][%FIRSTHEADING%]].

Or [[WikiName][%FORMFIELD{"fieldname"}%]] or [[WikiName][%TOPICVAR{"varname"}%%]]

Changing the meaning of [[WikiName]] notation is not backwards compatible. In any existing TWiki with many topics you would have no other choice then turning the feature off. At least with my proposal the original syntax remains untouched.

There may be better syntax than what I proposed. I do not care too much about that. But keeping the basic syntax predictable, simple, easy to understand and compatible with existing topics is what is important to me.

-- KennethLavrsen - 11 Feb 2006

I agree that this change breaks existing links, which have often been carefully crafted to make sense in the page context. Kenneth's suggestion of a backward compatible approach is a good idea - updating large TWikis to cope without this compatibility would be a pain.

It would be much more useful to enable underscores or even spaces in internal TWiki links.

-- RichardDonkin - 12 Feb 2006

OK, I don't think we should touch the WikiName = page id - nature of wikis.

But we can think more generally about the display name of a topic. Sometimes it makes sense to base this on the first header, sometimes not and a form field would be better (for instance for displaying a person's name).

So a topic could have an alias. The alias is the way the topic is shown to the world. It would be optionally set to topics. User pages could have a form field "display name" that is based on first name and last name.

Other pages could have a form field "page title" that sets the topic's alias.

Some sites could want a general mechanism to base the alias on the first header.

The syntax could be [[^SomeTopic]] to show the topic's alias, and could render as Some topic.

Further specified in TopicDisplayName

-- ArthurClemens - 15 Feb 2006

Topic attachments
I Attachment History Action Size Date Who Comment
Unknown file formatpatch firstheading.patch r1 manage 1.6 K 2004-07-27 - 10:13 CrawfordCurrie  
Edit | Attach | Watch | Print version | History: r28 < r27 < r26 < r25 < r24 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r28 - 2006-07-09 - FranzJosefSilli
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.