TOC macro for a forest, not a tree

[Scott_Sauyet]

I’m wondering if there is prior art for something very much like a TOC widget, but which starts with a filter (just a title-list for my use) rather than an initial tag.

This version is exactly what I would like to see:

Example Table of Contents: Tabbed Internal

but instead of passing tag="TableOfContents" I would like to pass something like filter="HelloThere Learning [[Working with TiddlyWiki]] ... About" I’m happy enough using the default tagging mechanism for my hierarchy, I just want to start one level down.

My input list will be dynamic, so I cannot simply add a tag to the tiddlers.

Has anyone done this? I know these macros are complex. If it’s not already done, do you have any pointers for how to I might go about enhancing them?

I have looked at @EricShulman’s TiddlyTools/TOC and @pmario’s TOC-macros Rewrite. Both have excellent new features, but I don’t see this in their documentation.

[EricShulman]

Perhaps you can think of the TOC tag value as a “meta-root”, much like the root system for Pando (tree) - Wikipedia, which appears to be a forest of individual Quaking Aspen trees, but is actually a single massive organism that shares a common root system.

To view a specific subset of individual trees, you could use the TOC macro’s exclude=... parameter to dynamically “prune” the list to just include the desired subtrees.

For example, if you don’t want specified subtrees (e.g., exclude “HelloThere”, “Learning”, and “Working with TiddlyWiki”), you could write:

exclude="HelloThere Learning [[Working with TiddlyWiki]]"

or, more generally:

exclude={{{ HelloThere Learning [[Working with TiddlyWiki]] +[format:titlelist[]join[ ]] }}}

and, if you only want specified subtrees, you could write:

exclude={{{ [tag[TableOfContents]] -HelloThere -Learning -[[Working with TiddlyWiki]] +[format:titlelist[]join[ ]] }}}

which excludes ALL trees with the common root, and then removes the desired tree from that list.

Of course, you can use any suitable filter syntax to arrive at the desired exclude list, using something like this:

exclude={{{ [tag[MyRootTag]] -[subfilter<TreesIWant>] +[format:titlelist[]join[ ]] }}}

One significant advantage of this approach is that it doesn’t require any modification to the existing TWCore $:/core/macros/toc code, and is also compatible with my TiddlyTools/TOC as well as @pmario’s TOC-macros Rewrite.

-e

[CodaCoder]

@Scott_Sauyet

“HelloThere Learning [[Working with TiddlyWiki]] … About”

Quick hack, working with what’s there in $:/core/macros/toc…

\define toc-body-X(subfilter,sort:"",itemClassFilter,exclude,path)
\whitespace trim
<ol class="tc-toc">
  <$list filter="""[all[shadows+tiddlers]subfilter<__subfilter__>!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>">
              <<toc-caption>>
            </$list>
            <$macrocall $name="toc-body" tag=<<item>> sort=<<__sort__>> itemClassFilter=<<__itemClassFilter__>> exclude=<<excluded>> path=<<path>>/>
          </li>
        </$set>
      </$set>
    </$let>
  </$list>
</ol>
\end

<<toc-body-X "HelloThere Learning [[Working with TiddlyWiki]] About">>

Output:

Key part:

\define toc-body-X(subfilter,sort:"",itemClassFilter,exclude,path)

[pmario]

@Scott_Sauyet

I have looked at @EricShulman’s TiddlyTools/TOC and @pmario’s TOC-macros Rewrite. Both have excellent new features, but I don’t see this in their documentation.

Thanks for the reminder. I definitely need to work on the rewritten TOC-macro documentation. Luckily the new features needed, for the TestCase tiddlers, have been merged already. But the documentation will start to come to live with TW v5.3.6

---

The preliminary docs can be found at: TOC-macros Rewritten (+ a lot of new fuctionality) - Part 2
Preview can be found at: https://wip-toc-rewrite.tiddlyhost.com

It would look like this:

Create a tiddler eg: asdf

title: asdf
toc-filter: HelloThere Learning [[Working with TiddlyWiki]]

That's the starting tiddler
Field `toc-filter`: {{!!toc-filter}}

To use the configuration asdf as follows.

toc simple as a reference

<div class="tc-table-of-contents">
<<toc tag:"asdf" >>
</div>

toc-tabbed-…

<$macrocall
	$name="toc-tabbed-internal-nav"
	tag="asdf"
	selectedTiddler="$:/temp/toc/selectedTiddler"
	unselectedText="<p>Select a topic in the table of contents. Click the arrow to expand a topic.</p>"
	missingText="<p>Missing tiddler.</p>"
/>

I did find a bug in the current toc-tabbed-* implementation, if the “missing text” should be shown – That does not work.

Edit: Updated. Should work now.

[Scott_Sauyet]

I think my example was misleading.

My multi-rooted forest (or Aspen grove) is not specifically the first level of an otherwise single-rooted tree. It’s more arbitrary than that. It would be more like if I wanted to give it these tiddlers: [[Discover TiddlyWiki]] [[Filter Run Prefix]] [[Community Editions]] [[How to apply custom styles]].

You can see this in a wiki I mentioned recently, now getting close to complete, I need to add my analysis of more of the ballot questions, and I’m trying to get a few others to supply their thoughts too.

This issue has to do with the tiddlers for the ballot questions. For example if you examine Ballot Question 2, you will find (alongside placeholders for the analysis and recommendations) a list of the Charter sections with changes related to this question. In this case, it’s just Section 203A, which makes it easy enough to deal with. But Ballot Question 16 has over three dozen, at all different levels. I would much rather note the three highest-level nodes, 1012, 1013, and 1014, and be able to display the UI given by the current Tabbed Internal.

Tomorrow, I will play with all the techniques supplied, but only the one from @CodaCoder looks at first glance like it will handle my requirements. I think both Eric’s and Mario’s techniques will require more customization than I want to offer.

But thank you all, and I should be back on this tomorrow. I’ll let you know how it goes.

[TW_Tones]

@Scott_Sauyet from your example of the filter you give containing titles, you are effectively naming multiple toc root tiddlers. It is trivial to create a new tag to act as the alternative root tag, then tag each of you titles with that tag and provide that new root tag to the toc macro.

• If the titles you provide are also in another toc, the new root tag will be iterated in those tocs, some designers would like this others may not.
• The standard toc macro will avoid infinite loops
• Mario’s new toc macros may I expect allow you to exclude iterating the new root tag in your main toc if desired.

In your terminology the new root tiddler tag could be referred to as a forest tag just as the current Table of contents is. That is the root tiddler is in effect a forest tag

[Springer]

@TW_Tones

It is trivial to create a new tag to act as the alternative root tag, then tag each of you titles with that tag and provide that new root tag to the toc macro.

It’s true that it’s easy to create a new tag, and a utility such as Commander could apply a tag to whatever filtered set of tiddlers I might want to highlight on a given occasion…

However, like @Scott_Sauyet I would advocate for being able to use any arbitrary filter (even dynamically, say through an edit-text widget or checkboxes!) in connection with tabbed TOC interface.

Reason: Sometimes the tiddler constellation I want to show in a TOC interface (almost always tabbed toc, in my case) doesn’t correspond to anything that is appropriately a single tag (with or without exclude, though the exclude parameter is certainly helpful!). Making a tag, and then deleting it when it’s no longer needed — just in order to get a custom TOC interface — is awkward and perhaps confusing to the end-user (unless I use the system name-space for the tag or hide the tag, etc.).

[Scott_Sauyet]

@TW_Tones

It is trivial to create a new tag to act as the alternative root tag, then tag each of you titles with that tag and provide that new root tag to the toc macro.

In the very specifics of this wiki, I would get away with that. There are only 16 tiddlers for which I’d want to show such a view. I could tag each of the relevant tiddlers with a subset of those 16 tiddlers.

But I can easily see this growing. I’m offering to allow other people to include their own analysis, and my tidy categories might not apply to their analysis. So I really would like a dynamic approach: list the roots you want and have them all combined into one TOC-like interface. The response from @Springer shows that I’m not alone in desiring this.

One other advantage: I have a number of wikis where I want to sort all the entries within my sidebar expandable TOC with sortan… except for the top of the tree, where I want to exercise more editorial control. If the top was just a simple list of tiddlers, or any filter that specified the order, this would work as I hope. I’m quite sure @pmario’s changes allow a more flexible version of the same idea. And I’d love to see those adopted. But util then, this is a simpler change, as @CodaCoder already demonstrated.

@Springer

Sometimes the tiddler constellation I want to show in a TOC interface (almost always tabbed toc, in my case) doesn’t correspond to anything that is appropriately a single tag

Yes, this. This exactly!

[TW_Tones]

@Scott_Sauyet I support any enhancement of features especially with hierarchical and other organisational models so I am not arguing against your proposed changes, I have not reviewed your details. Changes may be introduced with @pmario’s current enhancements.

• The only question may be are we overloading the current macros?

If I understand your need correctly there are other fairly simple ways to implement your required features especially with @pmario changes, I was involved in his work and have a history discussing TOC issues.

• I will try and have a detailed requirements/code review because there may be other limitations we can overcome at the same time as incorporating your changes

Perhaps to wet your appetite what about a forest macro and/or widget that leverages the existing TOC macros?

Personally I would also be interested in a network macro to navigate non hierarchical networks including with metrics for shortest path and other useful features.