mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-11-16 06:44:50 +00:00
106f121133
* toc make exclude a proper macro parameter using subfilter instead of enlist * add exclude parameter to TOC documentation tiddler * add exclude parameter to toc-tabbed-xx macros * add from-version to exclude parameter
105 lines
5.0 KiB
Plaintext
105 lines
5.0 KiB
Plaintext
created: 20140919155729620
|
|
modified: 20230427125500432
|
|
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
|
|
|
|
; exclude <<.from-version "5.3.0">>
|
|
: This optional parameter can be used to exclude tiddlers from the TOC list. It allows a [[Title List]] or a <<.olink subfilter>>. Eg: `exclude:"HelloThere [[Title with spaces]]"` or `exclude:"[has[excludeTOC]]"`. Where the former will exclude two tiddlers and the later would exclude every tiddler that has a field <<.field excludeTOC>> independent of its value.<br>''Be aware'' that eg: `[prefix[H]]` is a shortcut for `[all[tiddlers]prefix[H]]`, which can have a performance impact, if used carelessly. So use $:/AdvancedSearch -> ''Filters'' tab to test the <<.param exclude>> parameter
|
|
|
|
!! Custom Icons
|
|
|
|
<<.from-version "5.2.4">>
|
|
|
|
To change the icons used by the Table-of-Contents macros, redefine the macros `toc-open-icon` and `toc-closed-icon`. This setting works for all toc-macro variants.
|
|
|
|
!!! Default Settings
|
|
|
|
* <<.var toc-open-icon>>: `\define toc-open-icon() $:/core/images/down-arrow`
|
|
|
|
* <<.var toc-closed-icon>>: `\define toc-closed-icon() $:/core/images/right-arrow`
|
|
|
|
!!! Custom Definitions
|
|
|
|
The default settings can be overwritten in your code using the define-pragma or the let-widget. The <<.wlink LetWidget>> widget can be used, if you have multiple table of contents macros in one tiddler, that need different icons.
|
|
|
|
''Define new icons using a pragma''
|
|
|
|
```
|
|
\define toc-open-icon() $:/core/images/fold-button
|
|
\define toc-closed-icon() $:/core/images/folder
|
|
...
|
|
```
|
|
|
|
''Define new icons using the let-widget''
|
|
|
|
```
|
|
<$let toc-open-icon="$:/core/images/fold-button" toc-closed-icon="$:/core/images/folder">
|
|
...
|
|
</$let>
|
|
```
|
|
|
|
!! Examples
|
|
|
|
Learn more at [[Examples|Table-of-Contents Macros (Examples)]] |