Simple TOC level parameter (#9612)

* Add toc level parameter

* Update TOC documentation

* Add toc level release note

* Update releasenote number and GH links

* Update releasenote number and GH links

Author: pmario

core/wiki/macros/toc.tid

@@ -15,18 +15,45 @@ tags: $:/tags/Macro
 </span>
 \end
 
-\define toc-body(tag,sort:"",itemClassFilter,exclude,path)
+\define toc-level-indicator()
+\whitespace trim
+<%if [<__level__>compare:number:gt[0]]%>
+  <%if [<currentTiddler>tagging[]] %>
+    <span class="tc-tiny-gap-left">{{$:/core/images/new-button}}</span>
+  <%else%>
+    <span class="tc-tiny-gap-left">{{$:/core/images/blank}}</span>
+  <%endif%>
+<% endif %>
+\end
+
+\define toc-body(tag,sort:"",itemClassFilter,exclude,path,level)
 \whitespace trim
 <ol class="tc-toc">
   <$list filter="""[all[shadows+tiddlers]tag<__tag__>!has[draft.of]$sort$] -[<__tag__>] -[subfilter<__exclude__>]""">
     <$let item=<<currentTiddler>> path={{{ [<__path__>addsuffix[/]addsuffix<__tag__>] }}}>
       <$set name="excluded" filter="[subfilter<__exclude__>] [<__tag__>]">
         <$set name="toc-item-class" filter=<<__itemClassFilter__>> emptyValue="toc-item-selected" value="toc-item">
           <li class=<<toc-item-class>>>
-            <$list filter="[all[current]toc-link[no]]" emptyMessage="<$link to={{{ [<currentTiddler>get[target]else<currentTiddler>] }}}><<toc-caption>></$link>">
+            <$list filter="[all[current]toc-link[no]]" >
+              <$list-empty>
+                <!-- link to target-field or currentTiddler -->
+                <$link to={{{ [<currentTiddler>get[target]else<currentTiddler>] }}}>
+                  <<toc-level-indicator>>
+                  <<toc-caption>>
+                </$link>
+              </$list-empty>
+              <!-- toc-link = no -->
+              <<toc-level-indicator>>
               <<toc-caption>>
             </$list>
-            <$macrocall $name="toc-body" tag=<<item>> sort=<<__sort__>> itemClassFilter=<<__itemClassFilter__>> exclude=<<excluded>> path=<<path>>/>
+            <$let _level={{{ [<__level__>subtract[1]] }}}>
+              <%if [<_level>compare:number:gt[0]]%>
+                <$macrocall $name="toc-body" tag=<<item>> sort=<<__sort__>> itemClassFilter=<<__itemClassFilter__>> exclude=<<excluded>> path=<<path>> level=<<_level>>/>
+              <%elseif [<_level>match[-1]]%>
+                <!-- show full toc, no level defined -->
+                <$macrocall $name="toc-body" tag=<<item>> sort=<<__sort__>> itemClassFilter=<<__itemClassFilter__>> exclude=<<excluded>> path=<<path>>/>
+              <%endif%>
+            </$let>
           </li>
         </$set>
       </$set>
@@ -35,10 +62,10 @@ tags: $:/tags/Macro
 </ol>
 \end
 
-\define toc(tag,sort:"",itemClassFilter:"", exclude)
+\define toc(tag,sort:"",itemClassFilter:"",exclude,level)
 \whitespace trim
 <$let __tag__={{{ [<__tag__>is[blank]then<currentTiddler>else<__tag__>] }}} >
-  <$macrocall $name="toc-body"  tag=<<__tag__>> sort=<<__sort__>> itemClassFilter=<<__itemClassFilter__>> exclude=<<__exclude__>>/>
+  <$macrocall $name="toc-body"  tag=<<__tag__>> sort=<<__sort__>> itemClassFilter=<<__itemClassFilter__>> exclude=<<__exclude__>> level=<<__level__>>/>
 </$let>
 \end
 

editions/tw5.com/tiddlers/demonstrations/TableOfContentsMacro Simple Example.tid

@@ -1,11 +1,43 @@
-created: 20150221201838000
-modified: 20150221203742000
-title: Example Table of Contents: Simple
 caption: Simple
-tags: table-of-contents-example
+created: 20150221201838000
+modified: 20260124125915331
 order: 1
+tags: table-of-contents-example
+title: Example Table of Contents: Simple
+type: text/vnd.tiddlywiki
 
 <$macrocall $name=".example" n="1"
 eg="""<div class="tc-table-of-contents">
 <<toc "Contents">>
 </div>"""/>
+
+---
+
+<<.tip"""If you use several parameters in a macro call, it is advised to use ''named parameters'' for all of them""">>
+
+<$macrocall $name=".example" n="2"
+eg="""<div class="tc-table-of-contents">
+<<toc tag:"Contents" level:"1">>
+</div>"""/>
+
+<$macrocall $name=".example" n="3"
+eg="""<div class="tc-table-of-contents">
+<<toc tag:"Contents" level:"2">>
+</div>"""/>
+
+<$macrocall $name=".example" n="4"
+eg="""<div class="tc-table-of-contents">
+<<toc tag:"Contents" level:"4">>
+</div>"""/>
+
+* If you want to ''change'' or ''remove'' the indicator, you can locally overwrite the `toc-level-indicator` macro. 
+* It is globally defined at: $:/core/macros/toc tiddler. Eg:
+
+<$macrocall $name=".example" n="5"
+eg="""\define toc-level-indicator()
+<!-- remove the indicator --> 
+\end
+
+<div class="tc-table-of-contents">
+<<toc tag:"Contents" level:"1">>
+</div>"""/>

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

@@ -1,5 +1,5 @@
 created: 20140919155729620
-modified: 20240624102502089
+modified: 20260124130054271
 tags: Macros [[Core Macros]]
 title: Table-of-Contents Macros
 type: text/vnd.tiddlywiki
@@ -74,6 +74,9 @@ These two parameters are combined into a single [[filter expression|Filter Expre
 ; 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
 
+; level <<.from-version "5.4.0">>
+: This optional parameter can be used to define how many toc levels are shown by the toc-macro. By default all levels are shown. 
+
 !! Custom Icons
 
 <<.from-version "5.2.4">>

editions/tw5.com/tiddlers/releasenotes/5.4.0/#9612-toc-level.tid

@@ -0,0 +1,14 @@
+change-category: usability
+change-type: enhancement
+created: 20260124121646761
+description: The simple toc macro now supports a level parameter
+github-contributors: pmario
+github-links: https://github.com/TiddlyWiki/TiddlyWiki5/pull/9612
+modified: 20260124131646761
+release: 5.4.0
+tags: $:/tags/ChangeNote
+title: $:/changenotes/5.4.0/#9612
+type: text/vnd.tiddlywiki
+
+* The [[toc-macro|Table-of-Contents Macros]] now supports a ''level'' parameter, that allows us to limit the [[toc-levels|Table-of-Contents Macros (Examples)]], that are listed. 
+* If the level parameter is active, levels, which have children will show a level indicator at the front. By default it uses the core "+" icon