Allow users to overwrite TOC default icons (#6913)

* Allow users to overwrite TOC default icons

* Fix docs as requested

core/wiki/macros/toc.tid

@@ -1,6 +1,10 @@
 title: $:/core/macros/toc
 tags: $:/tags/Macro
 
+
+\define toc-open-icon() $:/core/images/down-arrow
+\define toc-closed-icon() $:/core/images/right-arrow
+
 \define toc-caption()
 \whitespace trim
 <span class="tc-toc-caption tc-tiny-gap-left">
@@ -45,12 +49,12 @@ tags: $:/tags/Macro
     <$link to={{{ [<currentTiddler>get[target]else<currentTiddler>] }}}>
       <$reveal type="nomatch" stateTitle=<<toc-state>> text="open">
         <$button setTitle=<<toc-state>> setTo="open" class="tc-btn-invisible tc-popup-keep">
-          {{$:/core/images/right-arrow}}
+          <$transclude tiddler=<<toc-closed-icon>> />
         </$button>
       </$reveal>
       <$reveal type="match" stateTitle=<<toc-state>> text="open">
         <$button setTitle=<<toc-state>> setTo="close" class="tc-btn-invisible tc-popup-keep">
-          {{$:/core/images/down-arrow}}
+          <$transclude tiddler=<<toc-open-icon>> />
         </$button>
       </$reveal>
       <<toc-caption>>
@@ -71,13 +75,13 @@ tags: $:/tags/Macro
     <li class=<<toc-item-class>>>
       <$reveal type="nomatch" stateTitle=<<toc-state>> text="open">
         <$button setTitle=<<toc-state>> setTo="open" class="tc-btn-invisible tc-popup-keep">
-          {{$:/core/images/right-arrow}}
+         <$transclude tiddler=<<toc-closed-icon>> />
           <<toc-caption>>
         </$button>
       </$reveal>
       <$reveal type="match" stateTitle=<<toc-state>> text="open">
         <$button setTitle=<<toc-state>> setTo="close" class="tc-btn-invisible tc-popup-keep">
-          {{$:/core/images/down-arrow}}
+          <$transclude tiddler=<<toc-open-icon>> />
           <<toc-caption>>
         </$button>
       </$reveal>
@@ -117,12 +121,12 @@ tags: $:/tags/Macro
           <$list filter="[all[current]tagging[]$sort$limit[1]]" variable="ignore" emptyMessage="<$button class='tc-btn-invisible'>{{$:/core/images/blank}}</$button>">
           <$reveal type="nomatch" stateTitle=<<toc-state>> text="open">
             <$button setTitle=<<toc-state>> setTo="open" class="tc-btn-invisible tc-popup-keep">
-              {{$:/core/images/right-arrow}}
+            <$transclude tiddler=<<toc-closed-icon>> />
             </$button>
           </$reveal>
           <$reveal type="match" stateTitle=<<toc-state>> text="open">
             <$button setTitle=<<toc-state>> setTo="close" class="tc-btn-invisible tc-popup-keep">
-              {{$:/core/images/down-arrow}}
+              <$transclude tiddler=<<toc-open-icon>> />
             </$button>
           </$reveal>
         </$list>
@@ -144,13 +148,13 @@ tags: $:/tags/Macro
       <$list filter="[all[current]tagging[]$sort$limit[1]]" variable="ignore" emptyMessage="<$button class='tc-btn-invisible'>{{$:/core/images/blank}}</$button> <$view field='caption'><$view field='title'/></$view>">
         <$reveal type="nomatch" stateTitle=<<toc-state>> text="open">
           <$button setTitle=<<toc-state>> setTo="open" class="tc-btn-invisible tc-popup-keep">
-            {{$:/core/images/right-arrow}}
+            <$transclude tiddler=<<toc-closed-icon>> />
             <<toc-caption>>
           </$button>
         </$reveal>
         <$reveal type="match" stateTitle=<<toc-state>> text="open">
           <$button setTitle=<<toc-state>> setTo="close" class="tc-btn-invisible tc-popup-keep">
-            {{$:/core/images/down-arrow}}
+            <$transclude tiddler=<<toc-open-icon>> />
             <<toc-caption>>
           </$button>
         </$reveal>

editions/tw5.com/tiddlers/demonstrations/TableOfContentsMacro Selective Expandable Example custom icons.tid

@@ -0,0 +1,16 @@
+caption: Selective (custom icons)
+created: 20220819080004663
+modified: 20220819081049054
+order: 5
+tags: table-of-contents-example
+title: Example Table of Contents: Selectively Expandable (custom icons)
+type: text/vnd.tiddlywiki
+
+<<.from-version "5.2.4">> It is possible to define the `toc-open-icon` and `toc-closed-icon` variable, to change the icons used by the toc macros. This setting works for all toc-macro variants
+
+<$macrocall $name=".example" n="1"
+eg="""<$let toc-open-icon="$:/core/images/fold-button" toc-closed-icon="$:/core/images/folder">
+<div class="tc-table-of-contents">
+<<toc-selective-expandable "Contents">>
+</div>
+</$let>"""/>

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

@@ -1,5 +1,5 @@
 created: 20140919155729620
-modified: 20201017134038305
+modified: 20220819093733569
 tags: Macros [[Core Macros]]
 title: Table-of-Contents Macros
 type: text/vnd.tiddlywiki
@@ -62,4 +62,38 @@ These two parameters are combined into a single [[filter expression|Filter Expre
 ;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)]]
+!! 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)]]