WebHelp: Hyperlinks, Cross References, Other Linking

[beagley]

Sorry if this is Flare 101 knowledge, but I'm having trouble with links.

When I link between topics, clicking on them jumps out of WebHelp and just shows me that topic, like a new Web page. I lose my WebHelp frames.

So, how is it supposed to be done?

Maybe I should be changing the "Target Frame" of my Hyperlink to "Same Frame" or "Parent Frame"?

Or maybe I should be using Cross References instead of Hyperlinks?

I guess (in addition to my question), I have trouble understanding why I would use Cross References... are they just Hyperlinks that Flare helps you make pretty?

OH, also: When I click on links, I'd like it if the Table of Contents in WebHelp would jump to reflect the topic I am now viewing. Anyway to make it do that? (I notice it isn't working on the mini-TOCs which automatically generate at the bottom of intro topics that are assigned to folders containing more topics).

[LTinker68]

Maybe I should be changing the "Target Frame" of my Hyperlink to "Same Frame" or "Parent Frame"?

Is that happening in the output? You shouldn't need to select anything in the target field because the default option is to open in the same frame. Are you opening the help initially via CSH? There used to be a bug if you started with the ApplicationHelp project template where calling a file using CSH but opening it without the frames, then clicking the open in navigation link resulted in a new window. I thought that was fixed, though.

I guess (in addition to my question), I have trouble understanding why I would use Cross References... are they just Hyperlinks that Flare helps you make pretty?

Cross references give you a bit more flexibility. You can set up xrefs to say "see TopicTitle on page X" or "see the next page" or "on page X" and so on. You can also set it up so that the appearance of that xref varies depending on if you're outputting online (e.g., go to "Configuring the System") or print (e.g., see "Configuring the System" on page 39). And if you use auto-numbering, you can put a hyperlink in front of the auto-numbered paragraph and set the xref to load the auto-number value (e.g., "see Figure 20" or "repeat Step 5").

OH, also: When I click on links, I'd like it if the Table of Contents in WebHelp would jump to reflect the topic I am now viewing. Anyway to make it do that?

Yes. Open the skin file. On the Basic tab is an option to automatically synchronize the TOC. Note that if you insert a topic into the TOC in multiple locations, then the TOC will only jump to the first instance of that topic in the TOC. In other words, if you have TopicA in the TOC under BookA and BookB, and you click on TopicA under BookB, the TOC will jump to showing TopicA under BookA, not BookB. A workaround to this is to put the content of TopicA into a snippet, then create two topics and insert the snippet into those topics. Then one of the topics goes under BookA and one of the topics goes under BookB. When you click on the topic under BookA, the TOC syncs to that topic; when you click on the topic under BookB, it syncs to that topic.

(I notice it isn't working on the mini-TOCs which automatically generate at the bottom of intro topics that are assigned to folders containing more topics).

Not sure what you mean here. A topic containing a miniTOC proxy has to be a level above the topics you want to be listed in the miniTOC. So if BookA is linked to TopicA, and TopicA contains the miniTOC proxy, then all of the topics inside BookA will automatically appear in TopicA in the output. If the miniTOC proxy is in a topic at the same level as all the other topics, then it won't work.

[beagley]

Maybe I should be changing the "Target Frame" of my Hyperlink to "Same Frame" or "Parent Frame"?

Is that happening in the output? You shouldn't need to select anything in the target field because the default option is to open in the same frame. There used to be a bug... I thought that was fixed, though.

Yup, it's happening in my WebHelp output. I guess I'll go through and check that all the Target fields say "Same Frame". Some of them do NOT, and I guess that must be what's causing this behavior. What's really odd is that once I've clicked on one of those links, all the other links in my WebHelp (including the TOC!) have the same behavior! (i.e., once I've clicked on one of the links that takes me out of WebHelp, all subsequent clicks, even on WebHelp elements like the TOC, take me out of WebHelp... like somehow my browser or the WebHelp's cache suddenly switches it's default behavior.) I am running the latest version of Firefox and Flare.

I guess (in addition to my question), I have trouble understanding why I would use Cross References... are they just Hyperlinks that Flare helps you make pretty?

Cross references give you a bit more flexibility....

Thank you for your summary! This was helpful. I think I will continue to use mostly hyperlinks. I don't need anything fancy.

I really enjoy, BTW, the way that my Flare PDFs are smart enough to make the hyperlink jump to a spot farther down in the PDF (since the linked topic is included in the PDF) and the same link will jump to the topic in WebHelp. No work was needed to set this up, it just worked! Very, very cool.

OH, also: When I click on links, I'd like it if the Table of Contents in WebHelp would jump to reflect the topic I am now viewing. Anyway to make it do that?

Yes. Open the skin file. On the Basic tab is an option to automatically synchronize the TOC. Note that if you insert a topic into the TOC in multiple locations, then the TOC will only jump to the first instance of that topic in the TOC.

Lisa, thank you SO MUCH for this tip. I never would have thought to look in the Skin file (I forget that it is there, *grin*). TOC synchronization would make my WebHelp output MUCH easier to navigate! I'll keep an eye on that doubled-topic gotcha, but it shouldn't affect me much as I rarely list a topic twice in my WebHelp TOC.

Update: Okay, I checked the "Automatically Synchronic TOC" option in my skin and recompiled, but no luck. Does this work with WebHelp, or is it limited to other outputs? Now that I've been told about this feature, I reeeeeally want it...

(I notice it isn't working on the mini-TOCs which automatically generate at the bottom of intro topics that are assigned to folders containing more topics).

Not sure what you mean here. A topic containing a miniTOC proxy has to be a level above the topics you want to be listed in the miniTOC. So if BookA is linked to TopicA, and TopicA contains the miniTOC proxy, then all of the topics inside BookA will automatically appear in TopicA in the output. If the miniTOC proxy is in a topic at the same level as all the other topics, then it won't work.

Nope, they're at the higher level. Here's my situation in more detail:
I've got a book (perhaps within another book) that is linked to an intro topic, and that intro topic has the miniTOC that auto-magically shows me all the topics inside that book. That part works great. When I click on one of those TOC items (they are clickable), the topic frame in my WebHelp displays the new topic, but the main WebHelp TOC on the left doesn't change. The BOOK item is still highlighted, not the topic inside the book that I clicked on. Maybe the TOC synching option in the skin will fix this too... if I can figure out how to make that work.

[LTinker68]

Update: Okay, I checked the "Automatically Synchronic TOC" option in my skin and recompiled, but no luck. Does this work with WebHelp, or is it limited to other outputs? Now that I've been told about this feature, I reeeeeally want it...

It works with WebHelp and CHM output and I assume DotNetHelp output. Try deleting the output folder then rebuilding. Also, do you have just the one skin? If you have more than one, make sure you're making the change in the correct skin.

Nope, they're at the higher level. Here's my situation in more detail:
I've got a book (perhaps within another book) that is linked to an intro topic, and that intro topic has the miniTOC that auto-magically shows me all the topics inside that book. That part works great. When I click on one of those TOC items (they are clickable), the topic frame in my WebHelp displays the new topic, but the main WebHelp TOC on the left doesn't change. The BOOK item is still highlighted, not the topic inside the book that I clicked on. Maybe the TOC synching option in the skin will fix this too... if I can figure out how to make that work.

The auto-sync works for any type of link or xref or any other way you access a topic, so long as the option is enabled (make sure it's a check in the box and not the filled in box).