TiddlyWiki5/editions/tw5.com/tiddlers/macros/TableOfContentsMacro.tid

created: 20140919155729620
modified: 20201017134038305
tags: Macros [[Core Macros]]
title: Table-of-Contents Macros
type: text/vnd.tiddlywiki

~TiddlyWiki provides several macros for generating a tree of tiddler links by analysing [[tags|Tagging]]:

;<<.var toc>>
: A simple tree
;<<.var toc-expandable>>
: A tree in which all the branches can be expanded and collapsed
;<<.var toc-selective-expandable>>
: A tree in which the non-empty branches can be expanded and collapsed
;<<.var toc-tabbed-internal-nav>> and <<.var toc-tabbed-external-nav>>
: A two-panel browser:
:* on the left, a selectively expandable tree that behaves like a set of vertical tabs
:* on the right, the content of whichever tiddler the user selects in the tree

The difference between the last two has to do with what happens when the user clicks a link in the right-hand panel:

;<<.var toc-tabbed-internal-nav>>
: The target tiddler appears in the right-hand panel, replacing the tiddler that contained the link
;<<.var toc-tabbed-external-nav>>
: The target tiddler appears in the normal way (which depends on the user's configured storyview)

!! Structure

The top level of the tree consists of the tiddlers that carry a particular tag, known as the <<.def "root tag">>. Tiddlers tagged with any of those make up the next level down, and so on.

At each level, the tiddlers can be [[ordered|Order of Tagged Tiddlers]] by means of the <<.field list>> field of the parent tag tiddler. They can also be ordered by the macro's <<.param sort>> parameter.

The tree displays the <<.field caption>> field of a tiddler if it has one, or the tiddler's title otherwise.

Each tiddler in the tree is normally displayed as a link. To suppress this, give the tiddler a <<.field toc-link>> field with the the value <<.value no>>. In the [[examples|Table-of-Contents Macros (Examples)]], the SecondThree tiddler is set up like this. Clicking such a tiddler in the tree causes its branch to expand or collapse.

<<.from-version "5.1.23">> By default, the links open the tiddlers making up the table of contents. Alternatively, if the tiddler contains a <<.field target>> field then its contents will be used as the target of the link.

The table of contents is generated as an HTML ordered list. The `<ol>` elements always have the class `tc-toc`. Expandable trees have the additional class `tc-toc-expandable`. Selectively expandable trees (including those in the two-panel browser) have `tc-toc-selective-expandable`.

To make a table of contents appear in the sidebar, see [[How to add a new tab to the sidebar]].

!! Parameters

;tag
: The root tag that identifies the top level of the tree
;sort
: An optional extra [[filter step|Filter Step]], e.g. `sort[title]`

These two parameters are combined into a single [[filter expression|Filter Expression]] like this:

> `[tag[$tag$]$sort$]`

<<.var toc-tabbed-internal-nav>> and <<.var toc-tabbed-external-nav>> take additional parameters:

;selectedTiddler
: The title of the [[state tiddler|StateMechanism]] for noting the currently selected tiddler, defaulting to `$:/temp/toc/selectedTiddler`. It is recommended that this be a [[system tiddler|SystemTiddlers]]
;unselectedText
: The text to display when no tiddler is selected in the tree
;missingText
: The text to display if the selected tiddler doesn't exist
;template
: Optionally, the title of a tiddler to use as a [[template|TemplateTiddlers]] for transcluding the selected tiddler into the right-hand panel

[[Examples|Table-of-Contents Macros (Examples)]]
Lots of documentation cleanup 2014-09-19 16:18:25 +00:00			`created: 20140919155729620`
Extend TOC macros to allow custom link targets 2020-10-17 12:44:15 +00:00			`modified: 20201017134038305`
Overhaul the macro and variable documentation #1519 2015-02-24 16:41:16 +00:00			`tags: Macros [[Core Macros]]`
			`title: Table-of-Contents Macros`
Lots of documentation cleanup 2014-09-19 16:18:25 +00:00			`type: text/vnd.tiddlywiki`
First pass at table of contents macros Introduce macros for automatically generating table of contents 2014-08-18 19:52:36 +00:00
Overhaul the macro and variable documentation #1519 2015-02-24 16:41:16 +00:00			`~TiddlyWiki provides several macros for generating a tree of tiddler links by analysing [[tags\|Tagging]]:`
First pass at table of contents macros Introduce macros for automatically generating table of contents 2014-08-18 19:52:36 +00:00
Overhaul the macro and variable documentation #1519 2015-02-24 16:41:16 +00:00			`;<<.var toc>>`
			`: A simple tree`
			`;<<.var toc-expandable>>`
			`: A tree in which all the branches can be expanded and collapsed`
			`;<<.var toc-selective-expandable>>`
			`: A tree in which the non-empty branches can be expanded and collapsed`
			`;<<.var toc-tabbed-internal-nav>> and <<.var toc-tabbed-external-nav>>`
			`: A two-panel browser:`
			`:* on the left, a selectively expandable tree that behaves like a set of vertical tabs`
			`:* on the right, the content of whichever tiddler the user selects in the tree`
Extend toc macro so that links can be disabled This allows table of contents to contain heading entries that do not function as links, like the one in the sidebar. 2014-09-05 08:49:10 +00:00
Overhaul the macro and variable documentation #1519 2015-02-24 16:41:16 +00:00			`The difference between the last two has to do with what happens when the user clicks a link in the right-hand panel:`
Extend toc macro so that links can be disabled This allows table of contents to contain heading entries that do not function as links, like the one in the sidebar. 2014-09-05 08:49:10 +00:00
Overhaul the macro and variable documentation #1519 2015-02-24 16:41:16 +00:00			`;<<.var toc-tabbed-internal-nav>>`
			`: The target tiddler appears in the right-hand panel, replacing the tiddler that contained the link`
			`;<<.var toc-tabbed-external-nav>>`
			`: The target tiddler appears in the normal way (which depends on the user's configured storyview)`
More table of content macro docs 2014-08-18 20:44:31 +00:00
Overhaul the macro and variable documentation #1519 2015-02-24 16:41:16 +00:00			`!! Structure`
First pass at table of contents macros Introduce macros for automatically generating table of contents 2014-08-18 19:52:36 +00:00
Overhaul the macro and variable documentation #1519 2015-02-24 16:41:16 +00:00			`The top level of the tree consists of the tiddlers that carry a particular tag, known as the <<.def "root tag">>. Tiddlers tagged with any of those make up the next level down, and so on.`
First pass at table of contents macros Introduce macros for automatically generating table of contents 2014-08-18 19:52:36 +00:00
Overhaul the macro and variable documentation #1519 2015-02-24 16:41:16 +00:00			`At each level, the tiddlers can be [[ordered\|Order of Tagged Tiddlers]] by means of the <<.field list>> field of the parent tag tiddler. They can also be ordered by the macro's <<.param sort>> parameter.`
Add classes to the toc macro output 2014-08-31 13:05:43 +00:00
Overhaul the macro and variable documentation #1519 2015-02-24 16:41:16 +00:00			`The tree displays the <<.field caption>> field of a tiddler if it has one, or the tiddler's title otherwise.`
First pass at table of contents macros Introduce macros for automatically generating table of contents 2014-08-18 19:52:36 +00:00
Overhaul the macro and variable documentation #1519 2015-02-24 16:41:16 +00:00			`Each tiddler in the tree is normally displayed as a link. To suppress this, give the tiddler a <<.field toc-link>> field with the the value <<.value no>>. In the [[examples\|Table-of-Contents Macros (Examples)]], the SecondThree tiddler is set up like this. Clicking such a tiddler in the tree causes its branch to expand or collapse.`
Add a sort parameter to the TOC macro As requested by @giffmex 2014-08-20 21:48:07 +00:00
Extend TOC macros to allow custom link targets 2020-10-17 12:44:15 +00:00			`<<.from-version "5.1.23">> By default, the links open the tiddlers making up the table of contents. Alternatively, if the tiddler contains a <<.field target>> field then its contents will be used as the target of the link.`

Overhaul the macro and variable documentation #1519 2015-02-24 16:41:16 +00:00			The table of contents is generated as an HTML ordered list. The `<ol>` elements always have the class `tc-toc`. Expandable trees have the additional class `tc-toc-expandable`. Selectively expandable trees (including those in the two-panel browser) have `tc-toc-selective-expandable`.
Add a sort parameter to the TOC macro As requested by @giffmex 2014-08-20 21:48:07 +00:00
Overhaul the macro and variable documentation #1519 2015-02-24 16:41:16 +00:00			`To make a table of contents appear in the sidebar, see [[How to add a new tab to the sidebar]].`
First pass at table of contents macros Introduce macros for automatically generating table of contents 2014-08-18 19:52:36 +00:00
Overhaul the macro and variable documentation #1519 2015-02-24 16:41:16 +00:00			`!! Parameters`
Update TableOfContentsMacro.tid Seen the many questions in the group, the TableOfContentsMacro is a hot item but a bit difficult to understand. I thought a graphical representation with the real tags for the examples might help. 2014-09-25 08:23:03 +00:00
Overhaul the macro and variable documentation #1519 2015-02-24 16:41:16 +00:00			`;tag`
			`: The root tag that identifies the top level of the tree`
			`;sort`
			: An optional extra [[filter step\|Filter Step]], e.g. `sort[title]`
Docs adjustments 2014-09-27 10:56:36 +00:00
Overhaul the macro and variable documentation #1519 2015-02-24 16:41:16 +00:00			`These two parameters are combined into a single [[filter expression\|Filter Expression]] like this:`
Update TableOfContentsMacro.tid Seen the many questions in the group, the TableOfContentsMacro is a hot item but a bit difficult to understand. I thought a graphical representation with the real tags for the examples might help. 2014-09-25 08:23:03 +00:00
Overhaul the macro and variable documentation #1519 2015-02-24 16:41:16 +00:00			> `[tag[$tag$]$sort$]`
First pass at table of contents macros Introduce macros for automatically generating table of contents 2014-08-18 19:52:36 +00:00
Overhaul the macro and variable documentation #1519 2015-02-24 16:41:16 +00:00			`<<.var toc-tabbed-internal-nav>> and <<.var toc-tabbed-external-nav>> take additional parameters:`
Transcluding information re Sidebar Menus Transcluding information from newly proposed tiddler "How to Add A Menu to the Sidebar". This should help users discover ways in which to use the TOC macro. 2014-11-17 17:21:10 +00:00
Overhaul the macro and variable documentation #1519 2015-02-24 16:41:16 +00:00			`;selectedTiddler`
			: The title of the [[state tiddler\|StateMechanism]] for noting the currently selected tiddler, defaulting to `$:/temp/toc/selectedTiddler`. It is recommended that this be a [[system tiddler\|SystemTiddlers]]
			`;unselectedText`
			`: The text to display when no tiddler is selected in the tree`
			`;missingText`
			`: The text to display if the selected tiddler doesn't exist`
			`;template`
			`: Optionally, the title of a tiddler to use as a [[template\|TemplateTiddlers]] for transcluding the selected tiddler into the right-hand panel`

			`[[Examples\|Table-of-Contents Macros (Examples)]]`