Display CSH link for current topic

June 25, 2015 by Dave 2 Comments

I’ve written a script that will display a CSH link for the current topic, for HTML5 help outputs.

If you use CSH (aliases) in your Flare project, then it’s useful to be able to share links to your help that include the CSH ID, rather than the path and topic filename (as that might change).

For example, you’d want to share a link like:
yoursite.com/help.htm#cshid=hello

Rather than:
yoursite.com/content/folder/anotherfolder/hello_topic.htm

The script checks to see if the current topic is included in your alias file. If the topic is in the alias file, then it displays a short CSH link to that topic – for you to copy and use as you wish.

Try it out

To try this out yourself, first create a master page that contains this HTML:

<p id="page-link">Page link: <a href="#">CSH link will go here</a>
  <script type="text/javascript" src="lookup.js"></script>
</p>

Then create a file called lookup.js (in the same place as your master page), and copy and paste the following code.

$(document).ready(function()
   {
      /* hide link, unless we find a match */
      $("#page-link").css("display", "none");
      
      /* find help path */
      var helpPath = $("html").data("mc-path-to-help-system");   
      /* find help filename */   
      var helpFile = $("html").data("mc-help-system-file-name");
      /* substitute xml extension with htm */   
      var helpFile = helpFile.replace(".xml", ".htm");
      /* complete help URL */
      var helpURL = helpPath + helpFile;
      
      /* alias file URL */
      var aliasURL = helpPath + "Data/Alias.xml";

      $.ajax({
         type: "GET",
         url: aliasURL,
         dataType: "xml",
         success: function(xml) {

            
            /* get current topic filename, then decode it to remove characters like %20 */
            var currentFilename = location.pathname.substring(location.pathname.lastIndexOf('/') + 1);
            var currentFilename = decodeURIComponent(currentFilename);
            
            /* find every Map in the alias file */
            $(xml).find("Map").each(function()
            {
               /* get current Link (topic path) and Name (CSH ID) from Alias file */
               var currentLink = $(this).attr("Link");
               var currentName = $(this).attr("Name");
         
               /* check if current filename is contained in curent link */
               if ( currentLink.indexOf(currentFilename) != -1 )
               {
                  /* build CSH link */
                  var CSHlink = helpURL + "#cshid=" + currentName;
                  /* set href of link */
                  $("#page-link>a").attr("href", CSHlink);
                  /* set text in link to absolute path */
                  $("#page-link>a").text($("#page-link>a").prop("href")); 
                  /* display link */
                  $("#page-link").css("display", "block");
               }            
            });
         }
      });
      
});

And that’s it.

If the current topic is in the alias file, its CSH link will be displayed in the topic.