Can Hierarchical Navigation Benefit TW Documentation?

[mwiktowy]

Well … here is a mockup using the tabs macro FWIW:

<style>
div.breadcrumbs [role=switch] {
  padding: 3px 10px 3px 20px;
  margin-left: 10px;
  display: inline-block;
  height: 30px;
  position: relative;
  background: #ffe476 !important;
  text-decoration: none;
  line-height: 28px;

}
div.breadcrumbs [role=switch]:after {
  content: "";
  position: absolute;
  left: 0;
  bottom: 0;
  width: 0;
  height: 0;
  border-left: 15px solid white;
  border-top: 15px solid transparent;
  border-bottom: 15px solid transparent;
}
div.breadcrumbs [role=switch]:before {
  content: "";
  position: absolute;
  right: -15px;
  bottom: 0;
  width: 0;
  height: 0;
  border-left: 15px solid #ffe476;
  border-top: 15px solid transparent;
  border-bottom: 15px solid transparent;
}

div.breadcrumbs .tc-tab-buttons button{
 border-left: none;
 border-top: none;
 border-right: none;
 border-bottom: none;
}

.tc-tab-buttons button.tc-tab-selected{
  background: #eeeeee !important;
}

.tc-tab-buttons button.tc-tab-selected:before{
  border-left: 15px solid #eeeeee;
}
</style>

<<tabs "[[Filters]] [[Filter Syntax]] [[Filter Expression]] [[Filter Filter Run Prefix]]" class:"breadcrumbs">>

Breadcrumbs Tabs.json (1.3 KB)

The tab selection actions or the template/buttonTemplate parameters might allow manipulation of the tabs filter to build up the breadcrumb trail however you want.

Fodder for thought.
/Mike

[pmario]

Hi Mike,
A very interesting approach. Thx for sharing.

[Scott_Sauyet]

@pmario

Explanation of the image below

• “b” contains the macro, and is tagged “a” → So “a” will be next
• “a” is tagged “b” and “x” … “b” has been visited already → So “x” is next
• “x” does not exist … it will be shown → “c” (stop-tag) is shown … even if “x” does not exist
  • I think it makes sense to show the stop-tiddler as the highest level, since it is requested in the macro call.
  • I think the algorithm should “fail gracefully”

Does that make sense?

It sounds like it makes some sense. It’s not clear to me if this is meant to be opt-in. Will this only appear if you have a certain tag, or a particular value in some field?

Although I really want something like this for reference documentation, I don’t know that it makes sense on the entire tiddlywiki.com. Even in reference documentation, though, I am afraid of trying to impose a hierarchy on a fundamentally non-hierarchical wiki. In your solution, what happens when there are multiple paths to the TableOfContents?

But there are parts which would really benefit from breadcrumbs. I absolutely love the bit done with the railroad diagrams; but that’s going to applicable only to documentation of syntax.

I don’t know the answer, and I’d love to see how your code might help. But I’m afraid I’m not particularly optimistic.

[pmario]

@Scott_Sauyet

Although I really want something like this for reference documentation, I don’t know that it makes sense on the entire tiddlywiki.com.

It’s not intended to be used everywhere.

@Scott_Sauyet

Even in reference documentation, though, I am afraid of trying to impose a hierarchy on a fundamentally non-hierarchical wiki.

We do have the table of contents TOC, which clearly is a hierarchy. … Just because TW can be non-linear, it does not mean that there is no structure. It’s the users decision how structured and hierarchical a wiki is. …

I think for the railroad diagrams used to describe the filter syntax, it’s essential to know “where” the info belongs to. I think to understand filters it’s important to know the context. … and breadcrumbs may make that context visible.

@Scott_Sauyet

In your solution, what happens when there are multiple paths to the TableOfContents?

One will be chosen. Since tags are sorted alphabetically by default, the first one that has not been visited will be used. That’s it.

There are 3 macros atm.

1. One that uses tags to “travel” up the hierarchy as described above using sort[]
2. One that uses a user defined field name eg: parent, so it can be used by my TOCp plugin
3. One that uses the list-field to create breadcrumbs … I’m not sure if that is useful, but it may be

No. 2 can also use the tags field, but it does not sort. So the users are able to define the “path” by defining the tags accordingly.

[Scott_Sauyet]

@pmario

We do have the table of contents TOC, which clearly is a hierarchy. … Just because TW can be non-linear, it does not mean that there is no structure. It’s the users decision how structured and hierarchical a wiki is. …

Right. My greatest concern here is not how others might use such macros, but how we might use them on TW-com in order to improve it as a documentation source. For other places, this could be extremely useful.

But notice that there is a difference in the hierarchy expressed by breadcrumbs and that expressed by a TOC. In a TOC, we are giving an overview of where everything can be found. It doesn’t matter that Features > Drag and Drop and Features > Importing Tiddlers both include DragAndDropMechanism. It simply can be found in both places. Breadcrumbs describe where a particular tiddler resides. If our breadcrumbs show Features > Importing Tiddlers > DragAndDropMechanism, then we don’t report what might be the more important Features > Drag and Drop > DragAndDropMechanism. I faced a similar issue in my Wizard Nav Plugin, but I was expecting it to be a rare enough case that I simply accepted the ugliness of two such footers. I don’t think we can do that in a more generic mechanism.

@pmario

No. 2 can also use the tags field, but it does not sort. So the users are able to define the “path” by defining the tags accordingly.

That sounds like the best of all worlds!

[pmario]

The latest version of the docs with the breadcrumbs macros is live now: Start with Filter and Filter Syntax

The macros are developed with the tiddlywiki-com default CSS settings.

The macros are now named. .breadcrumbs and .breadcrumbsField … Do not miss the -dot- at the beginning

temporary docs

\define .breadcrumbs(start, stop, exclude, label, field, sort)

stop … (required) tiddler title to stop … Needs to be a tiddler, otherwise there is an error message

start … (optional) tiddler title to start with. defaults to currentTiddler
exclude … (optional) tiddler list of titles to be excluded. eg: title [[title with spaces]]
label … (optional) label to be shown in front of the breadcrumbs nav
sort … (optional) defaults to yes. In TW tags are usually sorted

\define .breadcrumbsField(start, exclude, label, field:"list")

start … (optional) tiddler title which contains the “list” field. defaults to currentTiddler
exclude … (optional) tiddler list of titles to be excluded. eg: title [[title with spaces]]
label … (optional) label to be shown in front of the breadcrumbs nav
field … (optional) defaults to “list”. Field name that contains a title-list that should be shown as breadcrumbs

The “field” verions can be used to create “out of order” breadcrumbs as shown in Filter Operators

More info

see: Can Hirarchical Breadcrumbs Benefit TW Documentation - #21 by pmario

ToDo

• [x] Optimize CSS for small screens (I know what I want, but I didn’t have the time yet, no suggestions needed atm)
• [x] Dynamically calculate hardcoded pixel values
• [ ] Check existing colour palettes … most of them don’t play well with the macro atm

Help needed

Many existing color palettes do not contain valid settings for the <<colour message-background>>; which is used for the breadcrumb background.

The railroad-plugin CSS uses those palette values too.

So the railroad-plugin and breadcrumbs macros will need improved palettes to work well with all palettes.

You can use the Palette Manager Edition to globally improve existing palettes. The edition contains the palette-manager-plugin-beta that can be imported into your wiki.

The INTRO for the palette-manager edition can be found at:

Palette Manager -- Feature Complete preview

Intro Video Please Like and Subscribe! [Palette Manager - Preview - feature complete] Function Overview Cloned palettes have an origin field now, that allows us to have an “undo-button” per color changed New Undo button if a color is different to the shadow palette There is a new “Search input” to filter based on colour names There is a new “Focus button” that sets the filter input to the first element of the colour names eg: alert to focus on the alert notification element I…

have fun!
Mario

[Yaisog]

Interestingly, I just noticed that MDN now has something similar:

I’m not sure if this has always been there or I just noticed it because of this related discussion, though.

[pmario]

@Scott_Sauyet

But, as noted above, they are no panacea; there are multiple possible hierarchies, and we can’t have six different sets of breadcrumbs without getting far too confusing.

We can have 6 different hierarchies. I like to call them: Stories. … I do have a story-editor, which allows to create as many stories as you like. … But the UI is bugged atm.

---

Just brainstorming

The visual representation of different story branches using breadcrumbs visualisation could look as follows.

The whole “story” would be visible from start to end.
If a branch is possible it will be shown too … from the branch point till the end.
… and so on

 ________    _____________   __________________   _____________   _____________
\  Start \  \ Main Branch \  \ Decision making \  \ Branch A   \  \ End        \
/________/  /_____________/  /_________________/  /____________/  /____________/
                                                  _____________  _____________________  ___________
                                                  \ Branch B  *\ \ Branch can be      \ \ End      \
                                                  /____________/ /_independent_from_A_/ /__________/
Where the actual tiddler is marked with a *

The actively viewed tiddler will be visually different. In the ASCII art represented by the * …

Higher level branches can be “collapsed” … to increase readability. eg:

________      _____________   _____________
\ Start \ ... \ Branch A   \  \ End        \
/_______/     /____________/  /____________/
              _____________  _____________________  ___________
              \ Branch B  *\ \ Branch can be      \ \ End      \
              /____________/ /_independent_from_A_/ /__________/

If Branch B is active and Branch A has the same "level" ... the Main Branch can be collapsed

[Scott_Sauyet]

@pmario

@Scott_Sauyet

But, as noted above, they are no panacea; there are multiple possible hierarchies, and we can’t have six different sets of breadcrumbs without getting far too confusing.

We can have 6 different hierarchies. I like to call them: Stories.

I’ve called them “pathways” and “tutorials” in my WizardNav Plugin. But I like “stories” a lot.

@pmario

The visual representation of different story branches using breadcrumbs visualisation could look as follows…

That is a very useful depiction of parts of a complex wiki. But I think it’s not capturing what people really use breadcrumbs for on the modern web. They do not represent the location on a linear journey through a fixed set of nodes, but rather a hierarchy leading to the current node.

In a sense, they are a simplified, partial table of contents. A TOC shows the hierarchy from the root to every node. Breadcrumbs show the hierarchy from the root to the current node, allowing you to easily jump back to any level above the current node. Links to content below the current node are not shown as breadcrumbs. They are handled in different way internal to the current node.

So, while I think what you’re looking at might well be worth exploring, I don’t think of it as having much to do with how we’d use breadcrumbs.

---

As to your actual work. How would you expect things to display if nodes are in very different spots in different stories? That is, if one story is A -> B -> C -> D -> E -> F, another is A -> W -> X -> Y -> Z -> B and a third is A -> Y -> F -> B -> C -> W, how do you place the various elements? Sometimes B is ahead of F, sometimes behind it, and sometimes F doesn’t show. It’s easy enough if you display one story at a time, but with multiple ones, it seems to me to become very tricky.

[TW_Tones]

Breadcrumbs will be from a root to a node only in highly structured environments, I have use large mainframe systems that use this. They usually demand you follow the structured path to get the job done, and as a result the path or story is equivalent to breadcrumbs.

• TiddlyWiki however allows multiple structures even non linear ones
• The metaphor of breadcrumbs does come from Hansel and Gretel and represents a trail you have traveled and allows you to return from where you came.
  • Although it is commonly misused

I do like the idea of stories represented like @pmario illustrated but I see, in some cases, the potential for too much information to handle easily and by default on tiddlers.

• I realised a few months ago that this information, both the existing structure, and where we have traveled, can be represented with traffic signs as a metaphor, especial since most of us understand them. Add to that our increasing familiarity with GPS mapping etc…
• There is also an innate human skill I refer to as “Trail memory” I have mentioned before that we can leverage.

I feel confident that we can find a way to represent the relationshipps between tiddlers in all these different ways of organising them such as a heirchy, list, trail/story, breadcrumbs (Or path) and perhaps journeys and itineries (like a traveling holiday plan)

@Scott_Sauyet

how do you place the various elements?

• My notes above highlight that the answer to this depends which navigational model you are using, and all are possible in TiddlyWiki.
• Off line I have developed a possible solution which endeavours to accommodate all of these, but it may be a while before I publish a full solution if I work on it on my own.
  • If designed well it will also assist when building such relationships, authoring journeys, etc…

Post script

• True breadcrumbs belong outside the story
• Hierarchical positions of a tiddler, belong in the tiddlers, in the hierarchy
• Stories or journies you are taking can be both directly related to the current tiddlers and to a meta-tiddler

[pmario]

@TW_Tones

Post script

• Hierarchical positions of a tiddler, belong in the tiddlers, in the hierarchy

That’s the usecase, that I mainly wanted to discuss with this thread and that I want to try to improve with a work in progress PR at GH.

If users are new to a topic I think it’s important to provide the hierarchical context a tiddler is in. Once users are familiar with the whole system, this information will be less inportant for the understanding, but it can be a “quality of live” improvement, because it provides a nice and fast way for “linked navigation”

That’s also a main goal of the PR mentioned above.

---

@TW_Tones

Post script

• True breadcrumbs belong outside the story

IMO this could be browser history, which can be activated in the TW ControlPanel → Settings tab.

1. If the Navigation Address Bar is activated as shown in the screenshot … and
2. Update history is activated …

The browser history 3) could make sense. … but it does not, since the info stored there is not good enough atm.

4. The browser back and forward buttons work … That’s a good thing. … But IMO most users don’t know about those settings.

IMO these features especially 2) should be improved and more prominently document.

@TW_Tones

Post script

• Stories or journies you are taking can be both directly related to the current tiddlers and to a meta-tiddler

That’s right. IMO a story-tiddler can contain meta text, eg: a summary and one or more configurations that allow it to “tell a story”.

• The initial story could be the summary itself, which links eg. 3 more links to give us an overview
• A more detailed story could provide a view about the full picture" with all the details

Those 2 “stories” could be created by the author. … Creating stories “in between” those 2 extremes should be easy to create by the user.

IMO that would be a valuable goal.

… just some more thoughts

[pmario]

@Scott_Sauyet

As to your actual work. How would you expect things to display if nodes are in very different spots in different stories? That is, if one story is A -> B -> C -> D -> E -> F, another is A -> W -> X -> Y -> Z -> B and a third is A -> Y -> F -> B -> C -> W, how do you place the various elements?

That’s a challenge, which imo would be worth while to experiment with. I do not have a solution, but I’m very interested in presenting information in a context. … Even if the system itself is “non linear” … Or especially if the system is non linear.

[TW_Tones]

@pmario

That’s a challenge, which imo would be worth while to experiment with. I do not have a solution, but I’m very interested in presenting information in a context. … Even if the system itself is “non linear” … Or especially if the system is non linear.

I have given this some thought and recall having found a solution. I hope the recollection is correct. I will look for my notes. One memory I have is having an independant position stored for each story and a current story and to navigate away from the current story always returns to your original position in the current story unless you change story.

• think of the words temporary diversion
• using real world analogues helps

[TW_Tones]

There are other gaps in the documentation and its searchability as well. I recently developed a keywords solution that enhances searchability by promoting some results ahead of others, search tiddlywiki.com for common terms like " filters" and the expierence is poor and even more so if you want a system tiddler like control panel or tag manager.

• the only thing I need to solve is adding keywords without touching shadow tiddlers, although this would be uncommon except for technical self documentation.
• although my masquerade solution may be a good solution.
• the keywords could promote master tiddlers that expose a story or heirachy you could use to take a curated journey.

[pmario]

I think that’s a bit OT here.

@TW_Tones

There are other gaps in the documentation and its searchability as well.

I did post some ideas about “searchability” and “rated results” this topic: Can we make standard search a little smarter? - #12 by pmario

[CodaCoder]

Aside: Maybe this belongs on the other thread but that thread is already too lengthy (IMO) to foster clarity for reasoned discussion. So…

To be clear, we are not truly talking about breadcrumbs, but rather something like “predefined pathways through a chosen topic chosen from among many”.

Breadcrumbs, on the other hand, should show the path taken to arrive at a given point (with no preconceived idea as to its logical/hierarchical placement within the forest as whole).

I’d much prefer to not use the term “breadcrumbs” for the “wrong thing” because, should we decide later to offer something truly breadcrumb-like, the term will already have been misapplied leaving us struggling to find another.

Let’s please call them TRACKS (or something).

But that’s just displaying HISTORY, like the browser back-button!

I don’t believe it is to TiddlyWiki’s benefit (philosophically or otherwise) to rest on facilities provided by user agents. TiddlyWiki should (and does) “stand alone” and do its own thing.

Yes, but that would lead to a huge line of links that simply wouldn’t scale!

That’s an implementation detail easily solved when the design is being thrashed out.

But that’s not how breadcrumbs are used on the web. Nobody does it like that!

Typically, TiddlyWiki does not encapsulate a conventional website structure.

But this is only meant for documentation tiddlers.

Good point. But once it’s used there, like everything else in TiddlyWiki, it will be used and incorporated elsewhere. Again, it’s the term I’m proposing to change, not the mechanism.

@pmario Feel free to move this if you feel it necessary.

[pmario]

@CodaCoder

To be clear, we are not truly talking about breadcrumbs, but rather something like “predefined pathways through a chosen topic chosen from among many”.

Wikipedia says:

A breadcrumb or breadcrumb trail is a graphical control element used as a navigational aid in user interfaces and on web pages. It allows users to keep track and maintain awareness of their locations within programs, documents, or websites. The term is a reference to the trail of bread crumbs left by Hansel and Gretel in the German fairy tale of the same name.[1]

All your quotes miss references. So I think they are your interpretation, with which I disagree. …

Hansel and Gretel’s breadcrumbs lead from their home into the forest. … It’s the path they took to go there, that’s a fact.

The same thing is true for the eg: “Filter Step” tiddler. … If we go back the way as it is shown, we will end up at the home of the “Filter Syntax”, which is the “Filter”.

---

For new users the filter syntax is very complex and hard to understand. The existing documentation does nothing to help users to immediately see the context the different doc tiddlers are related to.

• These plugins try to help them with a visual context.
• The dynamically created structure may not be the only way to get the big picture. You are right, it is a curated one and I’m sure it is a good one.

[pmario]

@CodaCoder

Let’s please call them TRACKS (or something).

Is there an existing 3rd party plugin, that is also called breadcrumbs? … I do not know one. links.tiddlywiki.org does not show one.

We can name the plugins .trail … But I would like to hear others first.

[pmario]

@CodaCoder

But that’s not how breadcrumbs are used on the web. Nobody does it like that!

Mozilla does: <td>: The Table Data Cell element - HTML: HyperText Markup Language | MDN

[CodaCoder]

@pmario

Mozilla does:

Sorry, you misunderstand me. Those bold points are arguments against my point.