Topic navigation issues due to multiple TOCs
Topic navigation issues due to multiple TOCs
Apologies if I am missing something obvious, but I currently have a master HTML target for my documentation portal which has a TOC that contains various other TOCs for different guides I produce. Some of the guides share a few of the same topics, but in each TOC, I have dragged the relevant topic to where I want it to be. Everything looks good, but if you click a topic that is used in more than one TOC/guide from the side menu, I am then navigated to that topic within the other guide. Is there a setting I am missing?
-
- Senior Propellus Maximus
- Posts: 2634
- Joined: Wed Apr 14, 2010 8:01 am
- Location: Surrey, UK
Re: Topic navigation issues due to multiple TOCs
Not completely sure I've understood what you're saying, but here's what I think you're doing and how you can fix it.
If you have ONE topic used in TWO or more places, when you've got a topic open the navigation in your Flare project can't work out which instance of the topic you're looking at so it gets confused. Rather than using the same topic twice, create unique topics for each instance and insert a SNIPPET that contains the content. That way you can have as many instances of the content as you like but each topic is unique.
1. Create a new topic for the second occurrence of the topic. It doesn't need to have any content at this stage, you'll populate it with content in a later step.
2. In your TOC, insert this new topic instead of the duplicated topic. (Repeat steps 1 and 2 for each instance of the same topic.)
3. From the original topic, create a snippet that contains the entire body of the topic and replace the body of the topic with the new snippet you've created. (I generally tend to leave the heading in the topic, but you can include the heading in the snippet if you wish.)
NOTE: When deciding where to save the snippet, you may want to save it in the source project if you use that project to build other outputs when it's in that project. If you do that, you may need to adjust your import file in the big project to make sure it also imports snippets.
4. In the new topic you've created, insert the snippet. (If the snippet didn't contain the topic heading, add it in the topic.)
5. Build your output and test.
I hope that gets you going, please shout if you need more help.
If you have ONE topic used in TWO or more places, when you've got a topic open the navigation in your Flare project can't work out which instance of the topic you're looking at so it gets confused. Rather than using the same topic twice, create unique topics for each instance and insert a SNIPPET that contains the content. That way you can have as many instances of the content as you like but each topic is unique.
1. Create a new topic for the second occurrence of the topic. It doesn't need to have any content at this stage, you'll populate it with content in a later step.
2. In your TOC, insert this new topic instead of the duplicated topic. (Repeat steps 1 and 2 for each instance of the same topic.)
3. From the original topic, create a snippet that contains the entire body of the topic and replace the body of the topic with the new snippet you've created. (I generally tend to leave the heading in the topic, but you can include the heading in the snippet if you wish.)
NOTE: When deciding where to save the snippet, you may want to save it in the source project if you use that project to build other outputs when it's in that project. If you do that, you may need to adjust your import file in the big project to make sure it also imports snippets.
4. In the new topic you've created, insert the snippet. (If the snippet didn't contain the topic heading, add it in the topic.)
5. Build your output and test.
I hope that gets you going, please shout if you need more help.
Started as a newbie with Flare 6.1, now using Flare 2023.
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
Re: Topic navigation issues due to multiple TOCs
Thank you for confirming. That makes sense and I can easily do that. I assumed that by dragging the topic into another TOC, that it would be treated as part of that TOC (which would allow me to avoid creating separate topics containing a snippet).
Re: Topic navigation issues due to multiple TOCs
If you're using Side Nav or Top Nav skins, there is a target setting Advanced - Synchronize navigation elements with TOC entries.
Using that setting means that if your topic is used in multiple TOCs, when you select the topic from the menu, it will highlight the topic in the correct TOC/menu position and show the right breadcrumb path.
Otherwise, if you don't use that setting, then the topic position shown in the menu and breadcrumbs will be fixed to one of the topic's TOC locations - which can look odd if you select a topic from the menu and it then jumps to a different location.
However, that setting will not fix the issue of what happens when you navigate to that topic via a link or from the search results, as you still get the problem where it will be fixed to show one of the topic's TOC positions, which might not be the one you want.
To fix that, you need to do as Choccie suggests, and create multiple topics and snippets.
Using that setting means that if your topic is used in multiple TOCs, when you select the topic from the menu, it will highlight the topic in the correct TOC/menu position and show the right breadcrumb path.
Otherwise, if you don't use that setting, then the topic position shown in the menu and breadcrumbs will be fixed to one of the topic's TOC locations - which can look odd if you select a topic from the menu and it then jumps to a different location.
However, that setting will not fix the issue of what happens when you navigate to that topic via a link or from the search results, as you still get the problem where it will be fixed to show one of the topic's TOC positions, which might not be the one you want.
To fix that, you need to do as Choccie suggests, and create multiple topics and snippets.
Re: Topic navigation issues due to multiple TOCs
Thanks so much, Dave. That setting saved me a lot of time!
-
- Propellus Maximus
- Posts: 1979
- Joined: Tue Nov 28, 2006 11:18 am
- Location: Crossroads of the West
- Contact:
Re: Topic navigation issues due to multiple TOCs
Dave Lee's answer is correct.
In the past, we went with the "create a snippet with the topic content, and the just create a new topic for each TOC and use the snippet there." I mean, that fixed the navigation issue, but it made authoring and updating content much more complex.
On the other hand, when we needed to use slightly different versions of a topic in two different guides, this solution WAS better because we could use Snippet Conditions to create different versions of the same snippet and have them appear correctly in the guide they were inserted into.
But if the topic is identical between TOCs, then just use the synchronize setting that Dave mentions. That will save you a lot of grief.
In the past, we went with the "create a snippet with the topic content, and the just create a new topic for each TOC and use the snippet there." I mean, that fixed the navigation issue, but it made authoring and updating content much more complex.
On the other hand, when we needed to use slightly different versions of a topic in two different guides, this solution WAS better because we could use Snippet Conditions to create different versions of the same snippet and have them appear correctly in the guide they were inserted into.
But if the topic is identical between TOCs, then just use the synchronize setting that Dave mentions. That will save you a lot of grief.
Re: Topic navigation issues due to multiple TOCs
Hi!
This thread really helped me out figuring multiple used topics and the setting Advanced - Synchronize navigation elements with TOC entries will work fine for the navigation elements.
Because we use the same section names in different categories I tried to use the section index topic as a shared topic.
Example:
Machine A (category)
- Compliance and Safety (section index)
-- Declaration of Conformity for Machine A (topic)
-- Safety Guide for Machine A (topic)
Machine B (category)
- Compliance and Safety (section index)
-- Declaration of Conformity for Machine B (topic)
-- Safety Guide for Machine B (topic)
The section index only consists of a heading and a mini TOC proxy which should show the two topics. So I wanted to use only one shared topic for that section index but the mini TOC proxy always shows the topics for machine A, regardless if I am in the category for Machine A or B. It seems like the mini TOC proxy is only generated once when building the project instead of building one for every category.
So I assume that the only solution would be to make section index topics for every category and use snippet texts for the headings instead, right?
Thank you so much!
This thread really helped me out figuring multiple used topics and the setting Advanced - Synchronize navigation elements with TOC entries will work fine for the navigation elements.
Because we use the same section names in different categories I tried to use the section index topic as a shared topic.
Example:
Machine A (category)
- Compliance and Safety (section index)
-- Declaration of Conformity for Machine A (topic)
-- Safety Guide for Machine A (topic)
Machine B (category)
- Compliance and Safety (section index)
-- Declaration of Conformity for Machine B (topic)
-- Safety Guide for Machine B (topic)
The section index only consists of a heading and a mini TOC proxy which should show the two topics. So I wanted to use only one shared topic for that section index but the mini TOC proxy always shows the topics for machine A, regardless if I am in the category for Machine A or B. It seems like the mini TOC proxy is only generated once when building the project instead of building one for every category.
So I assume that the only solution would be to make section index topics for every category and use snippet texts for the headings instead, right?
Thank you so much!
Re: Topic navigation issues due to multiple TOCs
What I found out: It shows the correct mini TOC when I navigate through the side navigation bar (the url parameter tocpath is used) but it does not works when I navigate through the mini TOCs in the topcis (because the url parameter tocpath is missing).
Re: Topic navigation issues due to multiple TOCs
never mind, the error was on our side. The tocpath parameter is also included in mini TOCs. But our category topics use manual linking instead of mini TOCs (because we want to have additional images and descriptions for every link) and we did not include the tocpath parameter there.