title: $:/core/macros/toc
tags: $:/tags/Macro

\whitespace trim

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

<!-- v5.2.4 add "Custom Icons" -->
\procedure toc-open-icon() $:/core/images/down-arrow
\procedure toc-closed-icon() $:/core/images/right-arrow

<!-- helper functions for li class definitions -->
\function tf.toc-itemClassFilter() [<selectedTiddler>get[text]match<currentTiddler>then[toc-item-selected]else[toc-item]]
\function tf.toc-includedClass() [subfilter<tf.toc-include>match<currentTiddler>then[toc-item-include]]
\function tf.toc-filteredClass() [subfilter<tf.toc-filter>match<currentTiddler>then[toc-item-filter]]
\function tf.toc-hideClass() [<tf.toc-hide>!is[blank]then[toc-item-hide]]
<!-- join the CSS definitions from above -->
\function tf.toc-itemClass() [<tf.toc-itemClassFilter>] [<tf.toc-includeClass>] [<tf.toc-filterClass>] [<tf.toc-hideClass>] +[join[ ]]

<!-- the following 3 functions need to use <currentTiddler> -->
\function tf.toc-getHideText() [<currentTiddler>get[toc-hide]]
\function tf.toc-hideIsYes() [<currentTiddler>format:titlelist[]]

<!-- Special case, if toc-hide field is "yes", we need a currentTiddler *titlelist* -- otherwise return the content as text -->
\function tf.toc-hide() [<tf.toc-getHideText>match[yes]then<tf.toc-hideIsYes>] :else[<tf.toc-getHideText>]

<!-- tf.toc-include and tf.toc-filter need to use <tag> -->
\function tf.toc-include() [<tag>get[toc-include]]
\function tf.toc-filter() [<tag>get[toc-filter]]

<!-- define unique path based state title -->
\function tf.toc-newPath() [<path>addsuffix[/]addsuffix<tag>]

\procedure toc-body(tag,sort:"",itemClassFilter,exclude,path)
<ol class="tc-toc">
	<!-- text substitution is needed for backwards compatibility -->
	<$list filter=` [subfilter<tf.toc-filter>]
					:else[all[shadows+tiddlers]tag<tag>!has[draft.of]$(sort)$]
					[subfilter<tf.toc-include>] -[<tag>] -[subfilter<exclude>]`>
		<%if [<currentTiddler>] -[subfilter<tf.toc-hide>] %>
			<$let item=<<currentTiddler>> __path=<<tf.toc-newPath>> >
				<!-- adding tf.toc-hide, excludes blocked elements from all visible sub-nodes -->
				<$set name="__excluded" filter="[subfilter<exclude>] [<tag>] [subfilter<tf.toc-hide>]">
					<li class=<<tf.toc-itemClass>>>
						<% if [all[current]toc-link[no]] %>
							<<toc-caption>>
						<% else %>
							<!-- v5.1.23 use target-field if present in tiddler -->
							<$link to={{{ [<currentTiddler>get[target]else<currentTiddler>] }}}>
								<<toc-caption>>
							</$link>
						<% endif %>
						<$macrocall
							$name="toc-body"
							tag=<<item>> sort=<<sort>> itemClassFilter=<<itemClassFilter>> exclude=<<__excluded>> path=<<__path>>
						/>
					</li>
				</$set>
			</$let>
		<% endif %>
	</$list>
</ol>
\end

<!-- =======================================
Simple toc macro which shows the full tree
This macro is _not_ used by other toc-macros
============================================ -->
\procedure toc(tag,sort:"",itemClassFilter:"",exclude)
<$macrocall $name="toc-body" tag=<<tag>> sort=<<sort>> itemClassFilter=<<itemClassFilter>> exclude=<<exclude>>/>
\end

<!--
	If a toc-itme shows a link. Clicking the caption will open the tiddler
	If toc-item is linked, the toc-caption is managed in the parent procedure
	If a toc-item should not show a link, the toc-caption is part of the button. So it can be clicked to open / close the branch
-->
\procedure toc-item(isUnlinked:"")
<% if [<toc-state>get[text]else[close]match[close]] %>
	<$button setTitle=<<toc-state>> setTo="open" class="tc-btn-invisible tc-popup-keep" tooltip=<<toc-state>>>
		<$transclude tiddler=<<toc-closed-icon>> />
		<% if [<isUnlinked>match[yes]] %>
			<<toc-caption>>
		<% endif %>
	</$button>
<% elseif [<toc-state>get[text]match[open]] %>
	<$button setTitle=<<toc-state>> setTo="close" class="tc-btn-invisible tc-popup-keep" tooltip=<<toc-state>>>
		<$transclude tiddler=<<toc-open-icon>> />
		<% if [<isUnlinked>match[yes]] %>
			<<toc-caption>>
		<% endif %>
	</$button>
<% endif %>
\end

\function tf.toc-stateTitle() [[$:/state/toc]] [<path>] "/" [<currentTiddler>] +[join[]]

\procedure toc-linked-expandable-body(tag,sort:"",itemClassFilter,exclude,path)
<$qualify name="toc-state" title=<<tf.toc-stateTitle>> >
	<li class=<<tf.toc-itemClass>>>
		<!-- v5.1.23 use target-field if present in tiddler -->
		<$link to={{{ [<currentTiddler>get[target]else<currentTiddler>] }}}>
			<<toc-item>>
			<<toc-caption>>
		</$link>
		<!-- TODO auto expand -->
		<% if [<toc-state>get[text]match[open]] %>
			<$macrocall
				$name="toc-expandable"
				tag=<<currentTiddler>> sort=<<sort>> itemClassFilter=<<itemClassFilter>> exclude=<<exclude>> path=<<path>>
			/>
		<% endif %>
	</li>
</$qualify>
\end

\procedure toc-unlinked-expandable-body(tag,sort:"",itemClassFilter,exclude,path)
<$qualify name="toc-state" title=<<tf.toc-stateTitle>>>
	<li class=<<tf.toc-itemClass>>>
		<<toc-item isUnlinked:"yes">>
		<!-- TODO auto expand -->
		<% if [<toc-state>get[text]match[open]] %>
			<$macrocall
				$name="toc-expandable"
				tag=<<currentTiddler>> sort=<<sort>> itemClassFilter=<<itemClassFilter>> exclude=<<exclude>> path=<<path>>
			/>
		<% endif %>
	</li>
</$qualify>
\end

<!-- ==========================================================
Shows an expandable toc. Item always have an open/close chevron
=============================================================== -->
\procedure toc-expandable(tag,sort:"",itemClassFilter:"",exclude,path)
<ol class="tc-toc toc-expandable">
	<!-- text substitution is needed for backwards compatibility -->
	<$list filter=` [subfilter<tf.toc-filter>]
					:else[all[shadows+tiddlers]tag<tag>!has[draft.of]$(sort)$]
					[subfilter<tf.toc-include>] -[<tag>] -[subfilter<exclude>]`>
		<%if [<currentTiddler>] -[subfilter<tf.toc-hide>] %>
			<$let __path=<<tf.toc-newPath>>>
				<$set name="__excluded" filter="[subfilter<exclude>] [<tag>] [subfilter<tf.toc-hide>]">
					<% if [all[current]toc-link[no]] %>
						<$macrocall
							$name="toc-unlinked-expandable-body"
							tag=<<tag>> sort=<<sort>> itemClassFilter=<<itemClassFilter>> exclude=<<__excluded>> path=<<__path>>
						/>
					<% else %>
						<$macrocall
							$name="toc-linked-expandable-body"
							tag=<<tag>> sort=<<sort>> itemClassFilter=<<itemClassFilter>> exclude=<<__excluded>> path=<<__path>>
						/>
					<% endif %>
				</$set>
			</$let>
		<% endif %>
	</$list>
</ol>
\end

\function tf.toc-curTidInclude() [<currentTiddler>get[toc-include]]

\procedure toc-linked-selective-expandable-body(tag,sort:"",itemClassFilter,exclude,path)
<$qualify name="toc-state" title=<<tf.toc-stateTitle>>>
	<li class=<<tf.toc-itemClass>>>
		<!-- v5.1.23 use target-field if present in tiddler -->
		<$link to={{{ [<currentTiddler>get[target]else<currentTiddler>] }}}>
			<!-- The subfilter<exclude> needs to be the last filter run -->
			<% if [all[current]tagging[]] [subfilter<tf.toc-curTidInclude>] -[subfilter<exclude>] +[limit[1]] %>
				<<toc-item>>
			<% else %>
				<$button class='tc-btn-invisible'>
					{{$:/core/images/blank}}
				</$button>
			<% endif %>
			<<toc-caption>>
		</$link>
		<!-- TODO auto expand -->
		<% if [<toc-state>get[text]match[open]] %>
			<$macrocall
				$name="toc-selective-expandable"
				tag=<<currentTiddler>> sort=<<sort>> itemClassFilter=<<itemClassFilter>> exclude=<<exclude>> path=<<path>>
			/>
		<% endif %>
	</li>
</$qualify>
\end

\procedure toc-unlinked-selective-expandable-body(tag,sort:"",itemClassFilter,exclude,path)
<$qualify name="toc-state" title=<<tf.toc-stateTitle>> >
	<li class=<<tf.toc-itemClass>>>
		<% if [all[current]tagging[]] [subfilter<tf.toc-curTidInclude>] -[subfilter<exclude>] +[limit[1]] %>
			<<toc-item isUnlinked:"yes">>
		<% else %>
			<$button class="tc-btn-invisible">
				{{$:/core/images/blank}}
			</$button>
			<span class="toc-item-muted">
				<<toc-caption>>
			</span>
		<% endif %>
		<!-- TODO auto expand -->
		<% if [<toc-state>get[text]match[open]] %>
			<$macrocall
				$name="toc-selective-expandable"
				tag=<<currentTiddler>> sort=<<sort>> itemClassFilter=<<itemClassFilter>> exclude=<<exclude>> path=<<path>>
			/>
		<% endif %>
	</li>
</$qualify>
\end

<!-- =====================================================
Shows a selctive expandable toc. 
If an item has no children, there is no open/close chevron
========================================================== -->
\procedure toc-selective-expandable(tag,sort:"",itemClassFilter,exclude,path)
<ol class="tc-toc toc-selective-expandable">
	<!-- text substitution is needed for backwards compatibility -->
	<$list filter=` [subfilter<tf.toc-filter>]
					:else[all[shadows+tiddlers]tag<tag>!has[draft.of]$(sort)$]
					[subfilter<tf.toc-include>] -[<tag>] -[subfilter<exclude>]`>
		<%if [<currentTiddler>] -[subfilter<tf.toc-hide>] %>
			<$let __path=<<tf.toc-newPath>>>
				<$set name="__excluded" filter="[subfilter<exclude>] [<tag>] [subfilter<tf.toc-hide>]">
					<% if [all[current]toc-link[no]] %>
						<$macrocall
							$name="toc-unlinked-selective-expandable-body"
							tag=<<tag>> sort=<<sort>> itemClassFilter=<<itemClassFilter>> exclude=<<__excluded>> path=<<__path>>
						/>
					<% else %>
						<$macrocall
							$name="toc-linked-selective-expandable-body"
							tag=<<tag>> sort=<<sort>> itemClassFilter=<<itemClassFilter>> exclude=<<__excluded>> path=<<__path>>
						/>
					<% endif %>
				</$set>
			</$let>
		<% endif %>
	</$list>
</ol>
\end

<!-- ==============================================================
Shows a tabbed toc.
If a toc-item link is clicked it will open the tiddler in the story 
=================================================================== -->
\procedure toc-tabbed-external-nav(tag,sort:"",selectedTiddler:"$:/temp/toc/selectedTiddler",unselectedText,missingText,template:"",exclude)
<$tiddler tiddler={{{ [<selectedTiddler>get[text]] }}}>
	<div class="tc-tabbed-table-of-contents">
		<$linkcatcher to=<<selectedTiddler>>>
			<div class="tc-table-of-contents">
				<!-- v5.3.4 itemClassFilter has been replaced by tf.toc-itemClassFilter -->
				<$macrocall
					$name="toc-selective-expandable"
					tag=<<tag>>
					sort=<<sort>>
					itemClassFilter="[all[current]] -[<selectedTiddler>get[text]]"
					exclude=<<exclude>>
				/>
			</div>
		</$linkcatcher>
		<div class="tc-tabbed-table-of-contents-content">
			<$reveal stateTitle=<<selectedTiddler>> type="nomatch" text="">
				<$transclude mode="block" tiddler=<<template>>>
					<h1><<toc-caption>></h1>
					<$transclude mode="block">$missingText$</$transclude>
				</$transclude>
			</$reveal>
			<$reveal stateTitle=<<selectedTiddler>> type="match" text="">
				<<unselectedText>>
			</$reveal>
		</div>
	</div>
</$tiddler>
\end

<!-- ========================================================
Shows a tabbed toc. If a toc-item link is clicked 
it will open the tiddler in the view area of the same tiddler
============================================================= -->
\procedure toc-tabbed-internal-nav(tag,sort:"",selectedTiddler:"$:/temp/toc/selectedTiddler",unselectedText,missingText,template:"",exclude)
<$linkcatcher to=<<selectedTiddler>>>
	<$macrocall
		$name="toc-tabbed-external-nav"
		tag=<<tag>>
		sort=<<sort>>
		selectedTiddler=<<selectedTiddler>>
		unselectedText=<<unselectedText>>
		missingText=<<missingText>>
		template=<<template>>
		exclude=<<exclude>>
	/>
</$linkcatcher>
\end