Breadcrumb trail contents

[DanAustin]

From the Flare help:

If a breadcrumbs proxy is included in a master page, the output will display a "trail of breadcrumbs" comprised of the table of contents (TOC) entries above the current topic in the TOC hierarchy.

I'm not sure if I'm doing something wrong or if I just don't understand correctly. I have a project where some topics exist just once but show up in more than one place in the TOC, because those topics are relevant to more than one subject. No issue there, because that works fine. My problem is that the breadcrumb trail shows these topics' location in the file structure, NOT in the TOC structure. From what I've read about it, the breadcrumb trail should show the TOC position, which is what I need it to do. Is this something I've done wrong, or do I just not understand it correctly? Any ideas? I'm working in Flare v4, if that matters.

Dan

[LTinker68]

This comes up a lot. I think I need to submit a KB article about it.

What's happening is that the topic is showing the breadcrumb position at the first instance of the topic in the TOC, not the relative position of each instance of the same topic in its various locations in the TOC. When you need to do is put the content of the topic into a snippet. Then create a topic for every spot in the TOC where you want that content to be included. In each topic, you insert the snippet. That way, if you want to change the content, you only change it in one spot -- the snippet. You then add each topic to the TOC once. When TopicA is loaded in BookA, the breadcrumb will show as BookA > TopicA. When TopicC is loaded in BookC which is under BookB, then the breadcrumb will look like BookB > BookC >TopicC. So it's one snippet file to many topic files, depending on how many times you want the content to be repeated in the TOC.

I also recommend that in all but one of the topics you turn off the include in search option in the Topic Properties screen. Otherwise, when the user does a search, he/she will get all those topics returned because they all contain the same content. So leave the search capability on one of the topics but disable it on all others.

[DanAustin]

I understand the reasoning and will give that a try. It seems a like a workaround which should work for now, but it seems to me that the Flare help is wrong, in that the breadcrumb trail doesn't work the way the help says it does. It's probably not a major issue for most, but I hope the Flare developers will take a look at this issue.

Thanks again for your help, Lisa

Dan

[Paul Griffiths]

This question comes up so frequently on this forum that you have to wonder if the Flare Help needs updating to make it clearer, but I really can't see what the developers could do about it. The breadcrumb trail is generated at build time, not dynamically as you use the help. If you think about it, the topic can't "know" how you navigated to it!

[DanAustin]

Interesting point. (I did do a search on the forum before I posted but didn't find anything on this.) I don't know how the "synchronize TOC" function works, but it seems like it would somehow be related. Anyway, I might try a different approach to see how it works for my users, using concept links to these files rather than having them in the TOC, as they are minor topics anyway. It's good to know there's more than one way to build a help system.

Thanks again,

Dan

[greg_gruner]

My problem is this:
I want F1 to work from a particular tab in a window. This tab occurs in two different windows, and the code is a reusable widget, so the Help ID is the same. Therefore I can only have one help topic.
However, the topic occurs twice in the TOC, and I'm hitting this issue of the breadcrumb being taken from the first instance.
The only solution I can think of is to remove the breadcrumb from the topic, even though it occurs in the TOC. Is there a way to turn off the breadcrumb for just one topic?

[NorthEast]

My problem is this:
I want F1 to work from a particular tab in a window. This tab occurs in two different windows, and the code is a reusable widget, so the Help ID is the same. Therefore I can only have one help topic.
However, the topic occurs twice in the TOC, and I'm hitting this issue of the breadcrumb being taken from the first instance.
The only solution I can think of is to remove the breadcrumb from the topic, even though it occurs in the TOC. Is there a way to turn off the breadcrumb for just one topic?

The breadcrumb proxy is (usually) included in of the master page, but you could set an individual topic to use a different master page (to the default) that doesn't include the breadcrumbs.

Multiple master pages are covered in the help here: http://webhelp.madcapsoftware.com/flare9/Default.htm#Master_Pages/About_Master_Pages.htm

Ideally, if the widget is being used in two different locations and contexts, then I'd ask the developers to use a different help ID for each context where it's used.

[greg_gruner]

Hi Dave
thanks for that - I see how it could be done. I will, however, try and persuade the developers to use a different ID!
Greg

[Fred Jongeneel]

I'm not sure why this is not standard behaviour in Flare (or at least create an option for the generation of the web output).

We are working on a reference system where we are creating various trails through the TOC towards the same topic. We are doing this for quite a few topics and this workaround (thanks LTinker68!) means we have to create a snippet and individual topics for each TOC item instead of just one topic that we link to each TOC item. Apart from the extra work this will also complicate maintenance.

My expectation would be that depending on the TOC item the breadcrumb figures out which path to show, regardless which topic the TOC item is linked to (or as suggested above have at least an option to either select this vs the current way of breadcrumb generation). It does work when using a snippet within a topic so why not directly on a TOC item?

Am I too demanding or am I missing something here?

Fred

[NorthEast]

Breadcrumbs are generated at build time, so are fixed in the topic; therefore a topic cannot have multiple breadcrumb paths for different TOC locations.

It guess it does make some sort of sense that breadcrumbs don't work if a topic has multiple TOC locations. Say you had a topic in multiple TOC locations; if you arrive at that topic by a link from another topic, the search, index, etc. - then which of multiple possible breadcrumb paths should be displayed? You'd have to display all breadcrumb paths, as it'd be impossible to pick one.

[Dmuir]

I used this thread to understand breadcrumbs and come up with a pretty good solution ( I thought).

In our TOC, we decided to explicitly show topics in categories like Concept, Task, Reference. The headings in the TOC reflect these categories for each product we have. But the description for the content type appears only once in an intro topic. The "heading" for Concepts is linked to that one intro topic. If someone clicks on the Concepts link in the breadcrumb, we decided it was okay to link to the intro topic way up in the TOC (it links to the first appearance of the topic). But I would expect that if there are additional nested topics that the breadcrumb proxy would work to show the additional nesting... yet it doesn't. It always stops at the topic that exists just once in the content.

Example:

The structure in the TOC is thus:
Products > Product A > Concepts > Introduction to Product A
Products > Product A > Concepts > Introduction to Product A > History of Product A

The breadcrumb shows up as:
Products > Product A > Concepts > Introduction to Product A
Products > Product A > Concepts > History of Product A

I have to assume it is because Concepts exists only once in the actual topic files. But that means the breadcrumb generator isn't just unable to decide which path to use, but stops trying to figure that out as soon as it links to content in a different path. Also note that I use a different master page for the "information type heading" topics like Concepts, Tasks, and Reference... one without breadcrumbs at all -- is that the cause?

By the way, this arrangement in the TOC was arrived at via consultation with our executives and select customers. I am not claiming it is optimal or industry standard.

[devjoe]

I don't use breadcrumbs, but I found a solution to keep TOC sync working when a topic is used more than once in the TOC, and maybe this would work for your breadcrumbs too.
In your repeated topics like Concepts, put some bookmarks at the top of the topic and link each TOC entry to a different one. The TOC entries still work, and the way I was setting this up, each link to the topic within that section also used the same bookmark, and the TOC synced to the appropriate bookmark.

[ChoccieMuffin]

Rather than having a single topic in several places in the TOC, how about having as many topics as you need there to be but use a snippet inside each of the topics, so you're still only providing the words once, in the snippet?

[Dmuir]

I don't use breadcrumbs, but I found a solution to keep TOC sync working when a topic is used more than once in the TOC, and maybe this would work for your breadcrumbs too.
In your repeated topics like Concepts, put some bookmarks at the top of the topic and link each TOC entry to a different one. The TOC entries still work, and the way I was setting this up, each link to the topic within that section also used the same bookmark, and the TOC synced to the appropriate bookmark.

Well this worked perfectly for making breadcrumbs work as expected, locating the link in the right place in the TOC tree despite the fact that the topic existed only once in the content tree.

In my opinion, this solution is superior to the previous suggestion to create a multitude of topics with a common snippet in each. At least for me it is more intuitive to add a bookmark to the common file for each new place the topic appears in the TOC. When you have multiple common files as "heading explanations" and many of those kinds of headings, the maintenance should be easier for any particular common file which ALSO serves a purpose on its own.

I think it boils down to a six of one, a half-dozen of another type of choice. But anyone who can provide reasons for one approach being superior in the long term, I would love to hear it now so I don't dig myself into too deep a hole.

As for my initial question, you all can ignore it because my breadcrumb proxy definition in the CSS just needed a larger value in mc-breadcrumbs-count, which I stupidly had set to something low at one point (I think by default it is unlimited, right?).

[Feebeegeebee]

I don't use breadcrumbs, but I found a solution to keep TOC sync working when a topic is used more than once in the TOC, and maybe this would work for your breadcrumbs too.
In your repeated topics like Concepts, put some bookmarks at the top of the topic and link each TOC entry to a different one. The TOC entries still work, and the way I was setting this up, each link to the topic within that section also used the same bookmark, and the TOC synced to the appropriate bookmark.

Great idea. This has been annoying me for ages.
I will try this out on my biggest project which has so many TOC links to a number of topics, with the breadcrumb links appearing out of sync in most cases.
Thank you!
Feebeegeebee

[Dmuir]

The key drawback to the bookmarks solution is that it requires you to use a different master page for the repeated topics... one that does not have breadcrumbs on it. This is probably the number one problem for people who want breadcrumbs on every page.

[NorthEast]

The key drawback to the bookmarks solution is that it requires you to use a different master page for the repeated topics... one that does not have breadcrumbs on it. This is probably the number one problem for people who want breadcrumbs on every page.

The bookmarks solution above is just to get the TOC sync working when using a tripane skin.

It's a good workaround, but It doesn't solve the original problem/question - how do you get breadcrumbs to work for topics which are repeated in multiple places in the TOC?

Also note that the bookmark fix is just for tripane skin, it won't work for the menu proxy in a top nav design (which has exactly the same issue as breadcrumbs).

[devjoe]

You can't get separate breadcrumbs without making separate topics, because the breadcrumbs are written into the topics during the build. They aren't a dynamic thing based on how the topic is loaded.

[doc_guy]

I have to assume it is because Concepts exists only once in the actual topic files. But that means the breadcrumb generator isn't just unable to decide which path to use, but stops trying to figure that out as soon as it links to content in a different path. Also note that I use a different master page for the "information type heading" topics like Concepts, Tasks, and Reference... one without breadcrumbs at all -- is that the cause?

I actually think this is happening because there is a setting in the breadcrumb proxy that limits the number of levels in the breadcrumbs. You can control this in the stylesheet. In the Advanced stylesheet editor, go to "MadCap | breadcrumbsProxy", expand the "Unclassified" section, and look for the "mc-breadcrumbs-count" item. Increase this to a higher number than you currently have, and rebuild your output, and I think you'll see more levels from your TOC.

-Paul

[Nita Beck]

...this is happening because there is a setting in the breadcrumb proxy that limits the number of levels in the breadcrumbs. You can control this in the stylesheet. In the Advanced stylesheet editor, go to "MadCap | breadcrumbsProxy", expand the "Unclassified" section, and look for the "mc-breadcrumbs-count" item. Increase this to a higher number than you currently have, and rebuild your output, and I think you'll see more levels from your TOC.

Paul, thank you for this particular nugget of advice. I've been puzzling for a while why one of my Help system's breadcrumb trial gives me only three levels when there are definitely more at times. But I hadn't taken the time to sort it out as I had more pressing updates to make. I've looked in my stylesheet and see that I haven't explicitly set the count, so it's inheriting it from the Flare stylesheet. I've now adjusted the count in my stylesheet and all is well. Thanks, pal!

[jstangeland]

"If a Breadcrumbs proxy is included in a master page, the output will display a "trail of breadcrumbs" composed of the table of contents (TOC) entries above the current topic in the TOC hierarchy."

I've come up against two surprising things for my topics that appear in multiple places in the HTML5 top-nav TOC:
* In some cases, the breadcrumb is defaulting to a TOC location that is _lower_ in the TOC. Could this be caused by _when_ the topic was added to each location in the TOC?
* For the second instance of the topic, it is not possible to navigate it using the keyboard; the selection skips the topic. This creates an accessibility issue.