TOC-macros Rewritten (+ a lot of new fuctionality) - Part 2

[pmario]

Rewritten toc-* Macros

Part 1: Proposal: TOC-macros Rewrite using IF, Functions and Procedures (+new fuctionality) - #34 by TW_Tones

CTRL-click Chevron Expands / Folds Tree Branches

• CTRL-clicking on a chevron should expand the whole tree
• CTRL-click again will close the whole tree again

Advantage: If everything is expanded, a “normal” click only fold the “current” branch

New Node Fields

New tiddler fields allow the new macros to have fine-grained control over toc branches on a “per node” / “per branch” level.

• toc-filter
  • Expects a titlelist or a filter
  • If a toc node contains a field named: toc-filter, that filter will replace the standard filter that normally creates the “child list” of that node.
  • nodes added with toc-filter have a CSS class="toc-item-filter"
  • If you want to list nodes with the current tag you should add [tag<currentTidder>!has[draft.of]] if you do not want to list draft-tiddlers
  • If there is no toc-filter, the default filter is: [all[shadows+tiddlers]tag<tag>!has[draft.of]$(sort)$] where the last element is a text-substitution of the sort parameter of the toc macro. (This $(sort)$ is only there for backwards compatibility and should not be used anymore.)

• toc-include
  • Expects a titlelist or a filter.
  • Tiddlers will be added to the existing accumulated list.
  • node added with toc-include have a CSS class="toc-item-include"

• toc-hide
  • If set to yes, the node will be removed from the child list
  • toc-hide takes precedence over all other fields.
  • Expects a titlelist or a filter
  • If set to a filter-run eg: :and[prefix[todo]] … all accumulated tiddlers prefixed todo will be removed
  • Be aware: Without the :and filter-run-prefix, the filter [prefix[todo]] is equivalent to [all[tiddlers]prefix[todo]]
  • parents with a toc-hide field have a CSS class="toc-item-hide"
  • toc-hide nodes are internally evaluated in the same way as the exclude parameter of the toc macro

• toc-itemTemplate
  • Expects a template tiddler-title
  • If itemTemplate is set, it uses the content of the template tiddler to display a toc node
    • If itemTemplate is used captionField (see info below) is set to text

• toc-tooltip
  • Defaults to the tiddler title
  • The content of the toc-tooltip field will be used as the tooltip
  • The field expects a string, which will not be wikified

• target
  • Since v5.1.23 use target-field if present in tiddler

If you need “special” behaviour, you will need to create your own itemTemplate, which can be specified as a field on a per tiddler basies, or globally as a macro parameter.

All titlelists of filters added to the new fields are internally evaluated using [subfilter[tf.toc-*]]

The field names used are defined with global variables. So for expert users, they can be overwritten like this.

\procedure toc-hideField()    toc-hide
\procedure toc-includeField() toc-include
\procedure toc-filterField()  toc-filter

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

---

New Macro Parameters

• captionField (default: caption)

  • Expects a field-name. If set it uses this field instead of the caption-field
  • If the field is empty, or does not exists, it tries to use “caption” or falls back to the “tiddler-title”

• tagField

  • Uses any “tag-like” field instead of the “tags” field to create the “tag-like” tree
  • tagField takes precedence over parentField

• parentField

  • Instead of using tags, the toc tree is built using “parent” fields.
  • There is no default, but usually it will be “parent”
  • This function uses the same filter behaviour as the tocP plugin

• itemTemplate

  • Expects a: template tiddler-title
  • by default toc macros use the toc-defaultItemTemplate procedure, which is specific to toc-macros
  • If itemTemplate is set, it uses the content of the template tiddler to display a toc node
    • If itemTemplate is used captionField is set to text
  • Important: If the toc-itemTemplate field is set in the current node it will take precedence over the macro parameter

The new fields should work with every toc-* macro.

---

Test Styles are part of the JSON test-suite linked below ;)

.toc-item-filter> a,
.toc-item-filter> .tc-toc-caption {
  color: darkviolet;
}

.toc-item-filter> button > svg {
  fill: darkviolet;
}

.toc-item-include  > a,
.toc-item-include > .tc-toc-caption
{
  color: green;
}

.toc-item-include > button > svg {
  fill: green;
}

.toc-item-hide> a,
.toc-item-hide > .tc-toc-caption
{
  color: red;
}

.toc-item-hide> button > svg {
  fill: red;
}

---

Requested (but not implemented yet) features from Part-1:

• Use a $:/config/toc/currentTidder configuration to allow “per node” parameter change, whithout “touching” a user-created toc
  • This will allow plugin authors, or admins to modify toc-behaviour without the need to edit user-content.
• (If I forgot something – let me know, below)

---

Temporary Preview Link

Wip-TOC-Rewrite - Powered by tiddlyhost.com

Outdated Preview

## Latest Preview

https://tiddlywiki5-git-fork-pmario-toc-v53x-10443d-jermolenes-projects.vercel.app/

Test Data

The JSON attachment contains some test-* tiddlers that I use for testing atm. They are chaotic, but contain a bit of info and some links

• blue links are standard
• green links are toc-included
• dark violet is toc-filtered

Update 2024.05.13

There is a new version now: https://tiddlywiki5-git-fork-pmario-toc-v53x-10443d-jermolenes-projects.vercel.app/

• Users can add a toc-tooltip field to a tiddler, which will be shown on mouse hover
  • Default if no field is set, will show the title.
• Using captionField:"caption" should work now, if caption is not defined. So it falls back to title
• Using captionField:"test" should fall back to caption and then to title if no “test” or “caption” fields are defined
• \procedure toc-defaultItemTemplate() now uses a “filter cascade” to select the different fields to show.
• There is a data-fieldClass=`field-$(field)$` now, which can be used for styling. The $(field)$ will be replaced with the field-name that is shown. So eg: field-caption or field-title and so on. We need data-fieldClass because field names can use other character sets than Latin, which is not allowed for the “class” attribute.

Update 2024.05.14

There is a tf.toc-getTooltip function now, that you can easily overwrite, when you create a toc.

Eg: The following example will use the description-field if it is present. It falls back to currentTiddler if description is not defined.

\function tf.toc-getTooltip() [<currentTiddler>get[description]!is[blank]] :else[<currentTiddler>]

<div class="tc-table-of-contents">
<<toc tag:"JContents" parentField:"parent" >>
</div>

[TW_Tones]

@pmario I just stumbled on another feature that has being asked for an number of times in the past within TOC’s.

That an external link within a tiddler in a TOC result in opening the link, not the tiddler in it.

• First I thought such tiddlers could have a field like toc-external-url but I think I have a better idea.

Allow any tiddler to provide the fieldname toc-list-item, the contents of which will replace the deafult list items for that tiddler only, ie this will be transcluded instead?

• External link items could then use something like;

<a href={{!!external-address}} target=<<currentTiddler>> ><$text text=<<caption-or-title>>/> {{$:/core/images/link}}</a>

• Or transclude another as the list item template.

This would solve the above issue but also permit a range of other features to be implemented in individual tiddlers participating in the TOC.

• Provide a button instead, that also triggers actions
• Set a config option or toggle something
• Simply highlight specific titles differently.

It may also be the opportunity to provide a new list-item template just for TOC items such as not $:/core/ui/ListItemTemplate but $:/core/macros/toc/ListItemTemplate.

• Providing additional hackability out of the box and reusability in the other TOC macros.
• Eg modify $:/core/macros/toc/ListItemTemplate to display on any tiddler less than a week old;

• Others may want to add tooltips, popups etc…

[pmario]

Important: None of the following features is public yet

I did already add some more features. There are some new macro parameters now.

• captionField … Instead of the caption, show any other field if it exists. Fallback to title as usual

The captionField parameter is independent from the following 2 fields.

• tagField … Instead of the “tags” field an other “tag-like” field can be used. or
• parentField … Instead of the tag field use the “parent” field … So yes it’s like my tocP macro.

There is a new parameter: “itemTemplate”, which allows us to use a custom template instead of the default toc-captionField procedure.

But I also found out, that the listItemTemplate should probably be defined on a “per tiddler” basis.

[TW_Tones]

You have being busy, great work.

I was thinking this way;

List item template;

• Create a default one related to all toc macros modifying this applies to all
  • Except if overridden
  • Move code from the macro definitions to a default list item reducing the code for all macros as list item is reusable.
    • The default list item could be customised itself to add conditions, currentTiddler query and styling etc… but then below use a custom list item.
• Option to set on any tiddler to override eg list-item
  • Keep in mind a generic list-item field could be used by other list and transclusions out there, in part because the nature of an individual tiddler would tend to imply the same template however it is listed
  • However except for coding the toc macros it will not be used unless coded and specified.
• In future extend this to a no touch list item eg $:/config/list-items/ //tiddlername//
• In future we may be able to add list item override to tabs and elsewhere. Eg a specific tab has a background color under certain conditions.

Note:
Otherwise to implement this there are now other ways available such an using a custom widget to redefine the link widget (using genesis).

• Pros and cons I am sure.

I do wonder if all these features could be pumped into smart-toc macros leaving the current toc macros better written. But still have the smart-toc macros included in the core?

[pmario]

I did just update the OP with some docs about the new field and new macro parameters. The Latest Preview link is in the OP.

The code got some info about the naming conventions used, which should make code reading easier.

<!--
Naming rules / pattern
- functions: tf.toc-variableName, "tf." -> function prefix reservered for TW, "toc-" -> global macro prefix, "variableName"
- procedures eg: toc-procedureName,
- macro parameters: path, itemTemplate
- derived macro parameters: _path, _itemTemplate -> derived variables start with an underscore
-->

Since macros do not “convert” parameters into __oldParams__ anymore, it’s needed that programmers do that, to avoid confusion with <$macrocall parameter definitions.

I wanted to use to leading underscores for derived parameters eg: __itemTemplate, but the VSCode TW syntax highlighter thinks it needs to “underline” the code, which makes it unreadable. So I use a single leading underscore instead eg: _itemTemplate

---

I’ll try to create some docs / examples for the new possibilities.

have fun!

[TW_Tones]

@pmario

_itemTemplate

I recently did the same, co-incidentally and started to prefix template tiddlers with _ and even playing with this as an additional system prefix or namespace. Here is my playground https://namespaces.tiddlyhost.com/

I thought I would just take the opportunity to let you know I would be reviewing this toc rewrite more, however I am “off to the bush” now, with minimal internet access, and then climbing/walking a mountain or two, this weekend.

• I may not be as active until sunday eve/Monday.

Thanks @pmario for having an “open design mind” and including features as we go. Much appreciated, enjoy your weekend.

[pmario]

Just published a new version. Latest version is linked in the OP. OP docs is up to date

CTRL-click Chevron Expands / Folds Tree Branches

• CTRL-clicking on a chevron should expand the whole tree
• CTRL-click again will close the whole tree again

Advantage: If everything is expanded, a “normal” click only fold the “current” branch and leaves “sub-branches” alone

The JSON attachment contains some test-* tiddlers that I use for testing atm. They are chaotic, but contain a bit of info and some links

• blue links are standard
• green links are toc-included
• dark violet is toc-filtered

toc-macros-new-test-tiddlers.json (28.0 KB)

have fun!
-mario

[TW_Tones]

I just revisited this topic @pmario due to link you shared and it is very exciting. I have not yet tested comprehensively but will soon.

How likely is it to be in the next release and can I help any other way?

[pmario]

The preview edition contains a lot of test tiddlers but the documentation examples are still missing.

According to the comment from Jeremy at GH Work In Progress - Toc v5.3.x rewrite by pmario · Pull Request #7961 · Jermolene/TiddlyWiki5 · GitHub the code docs also needs some work.

In the code I did add comments, where they are needed to maintain the code. There should be no user docs. It’s developer docs only.

[TW_Tones]

@pmario

There should be no user docs

Not sure what you mean here, do you mean adding the content at the top of this thread and the GitHub change Work In Progress - Toc v5.3.x rewrite by pmario · Pull Request #7961 · Jermolene/TiddlyWiki5 · GitHub is sufficient to add below the current TOC Table-of-Contents Macros - tiddler?

[pmario]

@TW_Tones

do you mean adding the content at the top of this thread and the GitHub change

Jeremy was not happy with the comments in the middle of the code. From my point view, they only make sense, if you really dig into the code. I did add comments, where I did need them, so the code made sense for me after about 3 weeks of not coding.

[pmario]

The “start” of the user documentation is the OP here in the thread. It’s a wiki, so everyone can extend it.

A lot of the background about the new functionality can be found in part 1: Proposal: TOC-macros Rewrite using IF, Functions and Procedures (+new fuctionality)

[TW_Tones]

Mario.

The following occured to me, and I appreciate it must most likely remain out of scope, but given the inclusion of the parent field, I was wondering what if we were looking at bibliographical trees and there were two or more parents?

• Perhaps we could use two parent fields and two tocs like patralinial and matralinial.

I just wonder if now or later we can supprt this?

Given the value to many of recording family trees.

[pmario]

The OT has just been updated, with a cross-post from: Optimal TOC use for multiple topics? - #18 by pmario

[Justin_H]

a bit of a late question but, hoa difficult would it be to create a button in the toc tree that is just a ‘new-here’ button? maybe a plus icon to the right of hovered nodes and would tag the new tiddler with the hovered node?

juat curious, it’s one of those little features ive noticed was pretty handy in onenote.

[pmario]

My tocP-plugin does that so it should be relatively straight forward to add it to this macro too. I’ll have to have a closer look. But I’m not sure when.

[pmario]

@Justin_H – TaDaaa

There will a tv-toc-show-new-child variable now, that allows us to switch this feature on and off.
tocP – parent based TOCs will have a different icon.

The new version should be active soon.

[Justin_H]

Nice!

The toc macro is really getting a face-lift, and turning into something epic

Will we be able to apply css to it? Something along the lines of :hover {display:inline} and not hover is hidden?

Edit: I meant to come back to this but unfortunately things got quite hectic, but to follow up with my question, I poked around a bit and created a stylesheet that achieves what I was curious about!

I will say that giving the new-child buttons a css class would be a bit more practical but all things considered there is no issue with how it is set up, and I’m sure it is moreso a temporary setting!

But, that being said, here is the CSS needed to show the buttons only when the tiddlers are hover overed, to avoid any sort of visual clutter when navigating the TOCs ^^

li.toc-item .tc-tiddlylink.tc-tiddlylink-resolves .tc-small-gap-left button {
display: none;
}

li.toc-item .tc-tiddlylink.tc-tiddlylink-resolves:hover .tc-small-gap-left button {
display: inline-block;
}

And, just want to say again that I think these changes are an amazing improvement to an otherwise already vital part of TiddlyWiki.

Edit 2:

Having a bit of a difficult time trying to import the plugin to a blank tiddler for testing. Unfortunately I am unable to get it working correctly outside of the linked v5.3.6 link. Is there a dependency on features found in the pre-release?

Just asking to see if there is a way I can use it for my wiki, as I really like how the TOC in the linked TW has turned out.

[pmario]

I will say that giving the new-child buttons a css class would be a bit more practical but all things considered there is no issue with how it is set up, and I’m sure it is moreso a temporary setting!

I did just add 4 new classes

• tc-toc-new-child to the wrapper SPAN
• tc-toc-new-child-tag to the “new here” button - default
• tc-toc-new-child-parent to the “new child” button - tocP like
• tc-toc-new-child-tagLike to the “new here” button - tagLike

Having a bit of a difficult time trying to import the plugin to a blank tiddler for testing. Unfortunately I am unable to get it working correctly outside of the linked v5.3.6 link. Is there a dependency on features found in the pre-release?

There should be no extra dependency.

Be aware My latest changes do not automatically create previews at GitHub anymore. Since the TW project moved to the TiddlyWiki organisation the Vercel bot stopped working. Until we have a new preview build system I’ll create a TiddlyHost preview (soon)

Temporary Preview Link

Wip-TOC-Rewrite - Powered by tiddlyhost.com