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

caption: toc
created: 20140919155729620
modified: 20140919155735567
tags: Macros
title: TableOfContentsMacro
type: text/vnd.tiddlywiki

The table of contents macro produces a hierarchical tree of tiddlers based on their tags.

The top level entries of the table of contents are defined by a root tag. The subentries under each of those entries are tagged with the title of the entry. Entries can be ordered using the `list` field of the tag tiddler as described in [[Tagging]].

The text for each entry is taken from the ''caption'' field if it is present, otherwise the ''title'' is used.

Entries are rendered as a link to the corresponding tiddler unless the tiddler has the value ''no'' in the field ''toc-link''. In the examples below, the entry SecondThree is set up in this way to not appear as a link.

There are several variants of the macro:

* `<<toc>>` produces a simple hierarchical tree of links
* `<<toc-expandable>>` produces an expandable tree of links
* `<<toc-selective-expandable>>` produces an expandable tree of links where the expand/contract buttons are only shown for entries that possess child nodes

The macros all generate HTML ordered lists. The `<ol>` elements are given the class `tc-toc`, with the expandable variant also having the class `tc-toc-expandable` and the selective expandable variant also having the class `tc-toc-selective-expandable`.

! Parameters

|!Position |!Name |!Description |!Default |
|1st |tag |The root tag that identifies the top level of the hierarchy | |
|2nd |sort |Optional sorting subfilter (eg `sort[title]`) | |

The ''tag'' and ''sort'' parameters are combined to make a filter expression of the form:

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

! Examples

In these examples, the top level entries of the table of contents examples are defined by the root tag ''Contents''. The subentries under each of those entries are tagged with the title of the parent entry, here ''First'', ''Second'', ''Third'', and ''Fourth''. One level deeper only ''~SecondThree'' has subentries.

Here is the tag structure shown with clickable tag pills:

{{Contents||$:/core/ui/TagTemplate}}
*{{First||$:/core/ui/TagTemplate}}
*{{Second||$:/core/ui/TagTemplate}}
**{{SecondThree||$:/core/ui/TagTemplate}}
*{{Third||$:/core/ui/TagTemplate}}
*{{Fourtth||$:/core/ui/TagTemplate}}

<<tabs "[tag[table-of-contents-example]]" "TableOfContentsMacro Simple Example">>
More mangling of reference docs 2014-09-10 23:06:19 +00:00			`caption: toc`
Lots of documentation cleanup 2014-09-19 16:18:25 +00:00			`created: 20140919155729620`
			`modified: 20140919155735567`
			`tags: Macros`
			`title: TableOfContentsMacro`
			`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
			`The table of contents macro produces a hierarchical tree of tiddlers based on their tags.`

Lots of documentation cleanup 2014-09-19 16:18:25 +00:00			The top level entries of the table of contents are defined by a root tag. The subentries under each of those entries are tagged with the title of the entry. Entries can be ordered using the `list` field of the tag tiddler as described in [[Tagging]].
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
			`The text for each entry is taken from the ''caption'' field if it is present, otherwise the ''title'' is used.`

			`Entries are rendered as a link to the corresponding tiddler unless the tiddler has the value ''no'' in the field ''toc-link''. In the examples below, the entry SecondThree is set up in this way to not appear as a link.`
More table of content macro docs 2014-08-18 20:44:31 +00:00
First pass at table of contents macros Introduce macros for automatically generating table of contents 2014-08-18 19:52:36 +00:00			`There are several variants of the macro:`

			* `<<toc>>` produces a simple hierarchical tree of links
			* `<<toc-expandable>>` produces an expandable tree of links
Add selective expandable table of contents macro And improve the layout of the examples 2014-08-19 11:30:22 +00:00			* `<<toc-selective-expandable>>` produces an expandable tree of links where the expand/contract buttons are only shown for entries that possess child nodes
First pass at table of contents macros Introduce macros for automatically generating table of contents 2014-08-18 19:52:36 +00:00
Add classes to the toc macro output 2014-08-31 13:05:43 +00:00			The macros all generate HTML ordered lists. The `<ol>` elements are given the class `tc-toc`, with the expandable variant also having the class `tc-toc-expandable` and the selective expandable variant also having the class `tc-toc-selective-expandable`.

First pass at table of contents macros Introduce macros for automatically generating table of contents 2014-08-18 19:52:36 +00:00			`! Parameters`

			`\|!Position \|!Name \|!Description \|!Default \|`
More table of content macro docs 2014-08-18 20:44:31 +00:00			`\|1st \|tag \|The root tag that identifies the top level of the hierarchy \| \|`
Add a sort parameter to the TOC macro As requested by @giffmex 2014-08-20 21:48:07 +00:00			\|2nd \|sort \|Optional sorting subfilter (eg `sort[title]`) \| \|

			`The ''tag'' and ''sort'' parameters are combined to make a filter expression of the form:`

			```
			`[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
			`! Examples`
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
Docs adjustments 2014-09-27 10:56:36 +00:00			`In these examples, the top level entries of the table of contents examples are defined by the root tag ''Contents''. The subentries under each of those entries are tagged with the title of the parent entry, here ''First'', ''Second'', ''Third'', and ''Fourth''. One level deeper only ''~SecondThree'' has subentries.`

			`Here is the tag structure shown with clickable tag pills:`
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
			`{{Contents\|\|$:/core/ui/TagTemplate}}`
			`*{{First\|\|$:/core/ui/TagTemplate}}`
			`*{{Second\|\|$:/core/ui/TagTemplate}}`
			`**{{SecondThree\|\|$:/core/ui/TagTemplate}}`
			`*{{Third\|\|$:/core/ui/TagTemplate}}`
			`*{{Fourtth\|\|$:/core/ui/TagTemplate}}`
First pass at table of contents macros Introduce macros for automatically generating table of contents 2014-08-18 19:52:36 +00:00
Add selective expandable table of contents macro And improve the layout of the examples 2014-08-19 11:30:22 +00:00			`<<tabs "[tag[table-of-contents-example]]" "TableOfContentsMacro Simple Example">>`