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

Developers
,
#1

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.
  • 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)

Latest Preview

.https://tiddlywiki5-git-fork-pmario-toc-v53x-rewrite-jermolene.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

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

4 Likes
Proposal: TOC-macros Rewrite using IF, Functions and Procedures (+new fuctionality)
TOC sub-branch inverse sorting?
#2

@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;

image

  • Others may want to add tooltips, popups etc…
#3

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.

1 Like
#4

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?

#5

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!

1 Like
#6

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.

#7

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

4 Likes