How to use a template to create a Custom Table of Contents Link

Tips & Tricks
#1

There are several default Table of Contents Macros

  • toc … A simple tree
  • toc-expandable … A tree in which all the branches can be expanded and collapsed
  • toc-selective-expandable … A tree in which the non-empty branches can be expanded and collapsed
  • toc-tabbed-internal-nav … The target tiddler appears in the right-hand panel, replacing the tiddler that contained the link
  • toc-tabbed-external-nav … The target tiddler appears in the normal way (which depends on the user’s configured storyview)

The code can be found at: https://tiddlywiki.com/#%24%3A%2Fcore%2Fmacros%2Ftoc

At the top of the code there is a macro definition which defines how the toc links are created. The macro is named toc-caption.

\define toc-caption()
\whitespace trim
<span class="tc-toc-caption tc-tiny-gap-left">
<$set name="tv-wikilinks" value="no">
  <$transclude field="caption">
    <$view field="title"/>
  </$transclude>
</$set>
</span>
\end

Explanation of code above

  • The first SPAN is used to define the general style and the gap between the icons and the link
  • The set-widget is used to define the TW wikilink behaviour
  • <$transclude field="caption"> … If there is a caption-field in the tiddler it will be used to create the link
    • This behaviour of the transclude-widget is described in the docs.

      The TranscludeWidget treats any contained content as a fallback if the target of the transclusion is not defined (ie a missing tiddler or a missing field).

  • <$view field="title"/> … if there is no caption field, the title-field will be shown. This element is only used, if the caption-filed in the line above is missing

So if the link-style should be modified the following steps are needed:

Create 3 tiddlers eg:

  • toc-caption
  • toc-caption-template
  • extra-field-styles
title: toc-caption
tags: $:/tags/Macro
code-body: yes

\define toc-caption()
\whitespace trim
<span class="tc-toc-caption tc-tiny-gap-left">
  <$set name="tv-wikilinks" value="no">
    <$tiddler tiddler=<<currentTiddler>> >
      <$transclude tiddler="toc-caption-template"/>
    </$tiddler>
  </$set>
</span>
\end

Explanation of code above

  • Important: The macro above, will overwrite the behaviour of the core toc-macros, without the need to modify the core
  • \whitespace trim is used to make the code human readable, but removes the indentation while parsing, because browser can do weird things with redundant whitespace
  • The first SPAN defines the classes which are defined in the Vanilla - Base stylesheet.
  • The next 2 lines are the equivalent of {{||toc-caption-template}} using widgets.

The toc-caption-template tiddler will define the “new” link in the TOC macros

  • The first \define extraField() erstellt will define the extra field that is shown
  • \define toc-default-caption() will shown, if there is no extra-field in the tiddler to link to
  • The list-widget will show the extra field, the caption if there is one or the title as a fallback

This should give us a compatible way to modify the link, without the need to modify the core macros.

title: toc-caption-template
code-body: yes

\whitespace trim

\define extraField() erstellt

\define toc-default-caption()
\whitespace trim
<$transclude field="caption">
    <$view field="title"/>
</$transclude>
\end

<$list filter="[all[current]has<extraField>]" variable=ignore emptyMessage=<<toc-default-caption>> >
<<toc-default-caption>>
<span class="extra-field tc-big-gap-left" ><$transclude field=<<extraField>>/></span> 
</$list>

Explanation of the code above

  • \define extraField() erstellt … defines the field name that should be added to the link
  • \define toc-default-caption() … creates the default link
  • <$list filter="[all[current]has<extraField>]" … checks if a tiddler has the extra-field
    • If yes: show the body of the list-widget
    • if no: show the emptyMessage
  • the list-widget body shows the default-link and the extra field.

The stylesheet definition

title: extra-field-styles
tags: $:/tags/Stylesheet

.extra-field {
  font-size: 0.7em;
  color: orange;
}

have fun!
Mario

PS: The code to test it toc-add-custom-field-to-link.json (1.5 KB) … You can use tiddlywiki.com for testing

PPS: Open https://tiddlywiki.com/#Table-of-Contents%20Macros%20(Examples) to play with it. Tiddler “aaa” is tagged: Fourth … So it should show up there.

PPPS: Know Problem: The “Simple” example doesn’t work as expected. … Need to investigate

5 Likes
Tiddler Link (underline) too "long"
#2

@pmario: I really like your explanations of some of the core features. These are excellent first steps for future wikitext programmers. :+1:
Thanks for taking the time!

Have a nice day
Yaisog

4 Likes