Improving WebHelp search results in RoboHelp

The full-text search in RoboHelp is an incredibly useful feature. However, scrolling through a list of alphabetized results can be daunting when you are looking for only the most relevant topic to your search keywords.

MadCap has solved this problem by adding a ranking system to the search results in Flare's browser-based help output. I imagine it won't be long before the RoboHelp team does the same.

In the meantime, what if you could alter how topic titles are presented in the WebHelp results pane, so that the best options are easier to find?

With a bit of work, you can.

RoboHelp uses a function called displayTopics in whfhost.js to display WebHelp search results. By adding a bit of JavaScript to this function after you generate your help, you can change how the search results appear.

For example...

In this example, the search sorts out any topics where the search keyword is part of the topic title. These are added to the Recommended section. As you can see, in most cases it will be much easier to find the desired topic quickly.

This modified version uses a JavaScript regular expression.

var rg = new RegExp(gsCW,"ig");

Results are compared to this expression and sorted appropriately before they are displayed.

This particular example assumes that topic titles are well chosen so that those appearing in the recommended list are the most relevant. However, it might not be suitable for projects that have more than several hundred topics. In such cases, even the Recommended list would require scrolling, and users might miss the second list that follows.

The point is, with a bit of scripting skill, you can modify the whfhost.js file and customize the search results. Just make sure your changes will actually benefit users. Also, take time to familiarize yourself with the code before making changes. (Don't worry, this file gets regenerated whenever you compile your help.)

If you need to brush up on your JavaScript skills, try W3Schools tutorials. They have an incredible archive of tutorials that are friendly to non-programmers, and definitely top the list of my favorite resources.

Are you happy with the search functionality just the way it is? No problem. At least you now know the purpose of whfhost.js.

To implement this technique in your own WebHelp system, open the whfhost.js file in your /!SSL!/WebHelp folder, and replace function displayTopics(){ } with the code below. Enjoy!


function displayTopics()
{

    var recHTML="";
    var sHTML="";
    var sLine="";


    var foundRecTopics = 0;
    var foundAnyTopics = 0;

    var rg = new RegExp(gsCW,"ig");

    var recHead="<dt><nobr><b>Recommended topics</b></nobr></dt>";
    var allHead="<br><dt><nobr><b>Other topics</b></nobr></dt>";


    for(var i=0;i<gaTI.length;i++){
        if(gaTI[i].sTopicTitle.search(rg)>-1){
            recHTML+="<dt><nobr><a href='"+gaTI[i].sTopicURL+"'>"+_textToHtml(gaTI[i].sTopicTitle)+"</a></nobr></dt>";
            foundRecTopics = 1;
        }
        else{
            foundAnyTopics=1;
            sLine+="<dt><nobr><a href='"+gaTI[i].sTopicURL+"'>"+_textToHtml(gaTI[i].sTopicTitle)+"</a></nobr></dt>";
            if(i>>4<<4==i){

                sHTML+=sLine;
                sLine="";
            }
        }
    }
    if(sLine.length>0)
        sHTML+=sLine;


    if (!foundRecTopics) {
        recHTML+="<dt><nobr>No topics found.</nobr></dt>";
    }

    if(!foundAnyTopics)
        sHTML+="<dt><nobr>No topics found.</nobr></dt>";
   
    sHTML="<dl>"+recHead+recHTML+allHead+sHTML+"</dl>";

    var resultDiv=getElement(gsResultDivID);
    if(resultDiv)
        resultDiv.innerHTML=sHTML;
}

Related posts: