Adding a Help button that "links" to a doc navigation topic

[Rona Kwestel]

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:

Code: Select all

Content
  CommonContent
  ProjectA
    ProjectA.htm
  ProjectB
    ProjectB.htm
  DocNavigation.htm
Project
  Targets
    OnlineOutput
      projectA
      projectB

When projectA is built, for example, the output folder contains the following:

Code: Select all

CommonContent/
ProjectA/
Data/
Resources/
Skins/
Default.htm
Search.htm
... (a few other files)

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, ...:

Code: Select all

https://company.com/documentation/<targetName>/
https://qa.company.com/documentation/<targetName>/
file:///drive:/any/random/path/to/<targetName>/

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.

[Rona Kwestel]

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.

[Rona Kwestel]

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:

Code: Select all

function showHelp()
{
    // get the file path and split it on the '/' characters into an array
    var pathArray = location.pathname.split('/');

    // pop off the file name at the end of the array, leaving just the path folders to that file
    pathArray.pop();

    // rejoin the path folders with '/' characters, and add a trailing one on the end
    var absolutePath = pathArray.join('/') + '/';

    // get the relative path back to the "root" folder of the help system, which is embedded as an attribute in the html tag on every page
    var relativePath = document.getElementsByTagName("html")[0].getAttribute("data-mc-path-to-help-system");

    // the path to the desired file is absolutePath + relativePath + file name
    var filePath = absolutePath + relativePath + "DocNavigation.htm"

    // reset the current URL to the combination of the origin (protocol + hostname + port) and the file path 
    location.href = location.origin + filePath;
}

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.

[Rona Kwestel]

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:

Code: Select all

<!-- Force inclusion of the DocNavigation topic in the output since it's not linked 
from anywhere else, so it can be found via the custom Help button in the toolbar -->
<p style="display: none"><a href="../../DocNavigation.htm" /></p>

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!

[kateschneider]

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!

[Rona Kwestel]

Oh, cool, glad it helped someone besides me!

[adoherty5]

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.

[Rona Kwestel]

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

[jimgilliam]

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

[sds]

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!

[Rona Kwestel]

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.