This page is part of a static HTML representation of the TiddlyWiki at https://tiddlywiki.com/

LinkWidget

 30th July 2024 at 6:50am

The link widget generates links to tiddlers. (Use the HTML <a> element to generate external links).

Content and Attributes

The content of the link widget is rendered within the <a> tag representing the link. If the content is empty then the title of the target tiddler is rendered as the default, for example:

  • <$link/> is equivalent to <$link to=<<currentTiddler>>><$view field="title"/></$link>
  • <$link to="HelloThere"/> is equivalent to <$link to="HelloThere">HelloThere</$link>
AttributeDescription
toThe title of the target tiddler for the link (defaults to the current tiddler)
aria-labelOptional accessibility label
tooltipOptional tooltip WikiText
tabindexOptional numeric tabindex
draggable"yes" to enable the link to be draggable (defaults to "yes")
tagOptional tag to override the default "a" element
classOptional CSS classes in addition to the default classes (see below)
overrideClassIntroduced in v5.1.16 Optional CSS classes instead of the default classes
data-*New in v5.3.2 Optional data attributes to be assigned to the HTML element
style.*New in v5.3.2 Optional CSS properties to be assigned to the HTML element

The draggable functionality is equivalent to using the DraggableWidget with the tiddler attribute set to the link target.

The default value of the tooltip attribute is supplied by the tv-wikilink-tooltip variable.

This means that you can control the text of a link tooltip in several ways:

<$link to="HelloThere" tooltip="Custom tooltip">Link 1</$link>

<$link to="HelloThere" tooltip="Another tooltip">{{$:/core/icon}}</$link>

<$set name="tv-wikilink-tooltip" value="I'm a link to {{!!title}}">
<$link to="HelloThere">Link 2</$link>
</$set>

Renders as:

Link 1

Link 2

Note that the tooltip is rendered with the current tiddler set to the target of the link.

A useful convention is to set the tooltip like this:

\define tv-wikilink-tooltip()
<$transclude field="tooltip"><$transclude field="title"/></$transclude>
\end

This causes the tooltip to be the tooltip field of the target tiddler. If the field isn't present, then the title is used instead.

CSS Classes

The link widget automatically determines and applies the following classes to links:

  • tc-tiddlylink - applied to all links
  • tc-tiddlylink-external - applied to external, non-tiddler links
  • tc-tiddlylink-internal - applied to tiddler links
  • tc-tiddlylink-missing - applied to tiddler links where the target tiddler doesn't exist
  • tc-tiddlylink-resolves - applied to tiddler links when the target tiddler does exist
  • tc-tiddlylink-shadow - applied to tiddler links when the target is a shadow tiddler
    • tc-tiddlylink-shadow tc-tiddlylink-resolves - applied to overwritten shadow tiddlers

Use the class attribute to specify additional css classes, or overrideClass to apply only that but not the above defaults, e.g. when used in a LinkCatcherWidget:

*<$link class="example">Here</$link> the `example` class is added.
*<$link overrideClass="example">Here</$link> only the `example` class applies.
*<$link overrideClass="">Here</$link> no class is set.

That renders as:

  • Here the example class is added.
  • Here only the example class applies.
  • Here no class is set.

href generation

The following process is used to generate the href attribute of the generated HTML <a> element:

  1. If tv-get-export-link is defined it is invoked to convert the target tiddler title to the href value
  2. Introduced in v5.1.15 If tv-filter-export-link is defined it is interpreted as a filter that converts the target tiddler title to the href value
  3. If tv-wikilink-template is defined it is treated as a specialised macro body that can perform limited conversion of the target tiddler title to the href value
  4. Otherwise, the target tiddler title is URI encoded to create the href

Configuration variables