Work In Progress - Toc v5.3.x rewrite

[pmario]

This PR was created to create a Vercel Preview

All TOC-macros Rewritten

The toc-macro now use toc-include, toc-filter and toc-hide fields as discussed at Talk:

Initial discussion at Talk (Part1)

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.

• toc-include
  • Expects a titlelist of 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

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)

---

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

JSON file can be found at: https://talk.tiddlywiki.org/t/toc-macros-rewritten-a-lot-of-new-fuctionality-part-2/9071?u=pmario

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
tiddlywiki5	✅ Ready (Inspect)	Visit Preview	Jul 23, 2024 5:06pm

[pmario]

To look at Files Changed at GitHub. Use the diff "split" setting to see what's going on

[pmario]

The existing "Table-of-Contents Macros" tiddler got an overhaul, to make it more consistent and easier to understand