MadCap Software Forums

I would like to have a "Help" button in our toolbar that users can click on to bring up a general topic on how to navigate the documentation, but this is proving to be a vexing problem.

I've added a new button to the TopicToolBar skin, and I've set the button's Event->Click field to call a showHelp() function defined in the Toolbar page's Custom JavaScript, but due to the nature of our multiple targets, all of which have a slightly different path to the top level of the built output (where the Default.htm file is found), and the occasional deployment as a zipped output folder that starts with a file URL, I can't seem to find the right JavaScript to get the function to "link" to the doc navigation topic at the top of the file hierarchy (at the same level as Default.htm) of our HTML5 output.

For a bit of background, here is the basic structure of the project:
When projectA is built, for example, the output folder contains the following:
And depending on how we "deploy" this output, the path to the default.htm page of the doc can be any of the following, where <targetName> can be projectA, projectB, ...: In addition to figuring out how to navigate to the right URL for the DocNavigation.htm page, I also need to figure out how to force Flare to include DocNavigation.htm in the output since it isn't linked from anywhere except (theoretically) the toolbar Help button. I'd rather it not be visible in the TOC or linked from any particular file, otherwise, there's no point in having the button.

I've searched the forum, the MadCap Flare help, and the MadCap Flare KB, but nothing is providing me with quite the right solution. Getting/setting any of the standard location.href.* attributes doesn't take me to the right level of the built URL and I don't want to have to do a whole parsing exercise, as the URLs have no common component that I can search for.

I can't use relative paths since this button would be clickable on any page and has no way of knowing how deep you are in the topic hierarchy. I tried various versions of the solutions found here: viewtopic.php?f=9&t=17145 and here: http://kb.madcapsoftware.com/mobile/Bas ... nTopic.htm to no avail. There is an implied possible solution here, but nobody ever responded to the query: viewtopic.php?f=9&t=21826.

I know this should be possible to do in some way because Flare itself does it with the Search function. Regardless of where the built files are located (server, local file system), and regardless of which page you're on in the hierarchy, if you click on the Search button to search for a text string, it knows exactly where to find that Search.htm page. Similarly, clicking on the logo in the top nav header takes you to the "home" page of the output, but it seems to be using Flare magic that is not exposed to the mortal user.

And if it matters, I'm on Flare 2017 r3. Haven't worked up the nerve to upgrade to 2018; having performance issues as it is, and not sure that 2018 won't make them worse.

I think I managed to figure this out for myself, though I'm still open to suggestions/corrections if anyone has alternate solutions.

First, it seemed evident that in order for any given Flare output file to "know" where the root folder is with respect to itself, without caring about the non-static "base URL", that file would have to record how deep in the hierarchy it is at build time.

Second, I did a bit of searching around in Flare's code to see what it's doing to find the Search.htm file (a file in the "root" folder that can be found at runtime from any depth in the hierarchy). I tried doing a file content search on the string "Search.htm" in the C:\Program Files\MadCap Software\MadCap Flare 13\ folder, and while I never found that exact string within any files, it did reveal some files of interest, namely .\Flare.app\Resources\WebHelp2\Desktop\Scripts\MadCapHelpSystems.js and .\Flare.app\Resources\WebHelp\Content\SkinSupport\MadCapUtilities.js. Looking through these files, it became clear that Flare is definitely doing a whole lot of path/URL computing using the DOM elements and attributes.

This led me to see what kind of attributes it sets on the output htm files, and sure enough, there is an attribute on the html tag named data-mc-path-to-help-system that contains the relative path back up to the "root" of the help system, e.g. "../", "../../", ... based on the depth of the given file. That right there is the key to the solution. From any page, I can figure out how many levels back up to go to get to the root folder of the output.

So, in order to reconstruct the full path to my DocNavigation.htm file (at the same level as the Search.htm file), I need to execute the following JavaScript function when a user clicks on the help button:
That just leaves the other problem, which is how to force Flare to include DocNavigation.htm in the output since it isn't linked from anywhere except (indirectly) from the toolbar Help button. If nothing else, I'm thinking I could add an href to it on the master page and set the display on that element to none. A bit of a hack, but it should work.

Just coming back here to confirm that adding the following line (right after the <MadCap:topicToolbarProxy />, though it could really go anywhere since it's invisible) to my master page did the trick:
The last task was to find an icon that matches the rest of the out-of-the-box toolbar buttons well enough. Graphically speaking, we're not winning any awards, but the button works!

THANK YOU for this! I spent a very long time today trying different things to make my custom button work, but your javascript is what finally did the trick. Thanks for posting this here!

Oh, cool, glad it helped someone besides me!

Thank you for this! So what do you add to the button's "Event" Click field to make this work?

Nevermind - figured it out. In case it helps others, you just add showHelp() in the Click field.

Oh, I had that part right in the original post. Glad you figured it out.

Rona, I'm just now seeing your post because I was researching the "data-mc-path-to-help-system" attribute. I get a lot out of your posts (like this thread).

Could you have used a regular expression to solve this issue? I'm researching ways expressions could maybe help solve some of my issues and desires!

Jim

Was just browsing this index and came across this post. This is exactly something I could use. The people who use our output aren't all tech savvy and I've been trying to come up with ideas on how to help them find things easier in the output. I have a custom search results page with a little blurb at the top with a link to a topic I designed for how to search the output. But I REALLY like the idea of a button in the toolbar on every topic. Thanks for posting your process with this!

Thanks, Jim. I had forgotten about this post. I would imagine there's a clever regex way to yield the correct URL, but while I love the concept and power of regular expressions, I find them maddening to produce or mentally parse, so I'm content with my more step-wise approach of picking off the URL pieces I need and stitching them back together. In any case, the critical piece of the puzzle was that special attribute, and in whatever method you employ, it takes you where you need to go.

sds, glad you found it helpful. Search is something I haven't really spent as much time on as I should, so thanks for the reminder.