Searching with ZoomSearch

Introduction

When I wrote the first version of this article, the WebHelp search in RoboHelp was somewhat lacking. The most common requests for improvements were:

• Highlighted search results
• Ability for user to choose Any Words, All Words or a Phrase
• Natural language searches
• Categories
• Synonyms
• Google like results rather than just a list of topics
• Ranked results
• PDF and Word documents included in search
• Ability to include a search on an intranet or other information sources outside the project
• Ability to exclude topics and folders.

RoboHelp 8 has addressed those requirements and will meet the needs of many users. However, if cannot upgrade or you need any or all of these features, then you should consider ZoomSearch.

• Ability to have multiple search options so that users can search all the content or specific areas only
• Ability to include a search on an intranet or other information sources outside the project
• Ability to exclude folders (RoboHelp 8 can exclude topics)
• Ability to exclude specific parts of the text
• Boolean searches
• Categories
• Results in the topic pane rather than the TOC pane.

I first came across ZoomSearch when I saw a post on the RoboHelp forums extolling its virtues and a while later I needed a search tool for an intranet. Having looked once before at such search tools, I was immediately impressed by the ZoomSearch interface. It is largely intuitive, where it isn't there is online help, and behind it all is David Wren who I have found most helpful. You don't need a developer's mindset to use ZoomSearch.

What Does It Do?

Nearly all the above! The exception is true natural language searches but it does support basic boolean operations (AND, OR, NOT, Wild cards. Also exact phrases except as mentioned later).

One of the cool things you can do is have more than one search option. By adding a Search Options page, you can offer the user the ability to search the whole help output, any number of specific areas or an external intranet. Take a look at how it works first.

• Demo 1 shows a single search option working from a toolbar button.
• Demo 2 shows a toolbar button accessing a page that gives multiple search options.

Search on the word Child as to keep the demo compact, the topics contain few words. You can also see ZoomSearch working by using the Search menu on this site.

Step 1 - Changing the source project(s) and publishing

In this step you set up some folders in your source project(s). The folders needed will vary according to whether you are dealing with one project or a merge, they will also vary according to whether you want to offer one search or a number of searches. I have set out the details in the table below.

Also before you can do anything in ZoomSearch, you need a published output. That is not the same thing as a generated output.

• When RoboHelp generates the help, it clears the output folder and generates new folders and topics
• When you publish, it simply updates some or all of your topics but it does not delete the additional folders that you will need. That is why you must publish. In some environments the author only generates an output and then hands those files over to the developers. You can publish to your local drive and hand over those files instead, it will make no difference to your developers.

If you don't currently publish, simply create a folder on your hard disk to which you can publish and then in RoboHelp, open the WebHelp layout and go to the last page of the wizard where you can set up the publishing details.

I strongly recommend that first time around, you work with a dummy project and use the Single Project, Single Search setup. Once you have got that working, it really will be much simpler to set up the others.

When you are ready to work on your real project, do so with a copy first. If you get it wrong, you can simply trash the copy and start again. So with that in mind, these are some suggested configurations. You may need others and you will be able to work those out once you have worked on the simpler setups first.

These suggestions are based on the method of merging described elsewhere on my site. If you do not follow that structure, you will need to modify these instructions to suit your setup.

After creating these folders, generate and publish your help.

Step 2 - Adding folders to the published help

You need equivalent folders in the published help as this is where ZoomSearch will create the files it requires.

If the output is a merged webhelp setup, these instructions assume your structure is the one I describe elsewhere on my site. If you have a different structure you will have to adapt these steps.

Step 3 - Create the search database(s)

Now we can open ZoomSearch. The free version from www.wrensoft.com allows you to search up to fifty pages so work with a suitable size project while you are testing. That gives you the chance to prove to yourself that it really is as straightforward as I describe.

This section describes Version 5 of ZoomSearch. I will shortly be updating it to cover Version 6.

Opening ZoomSearch

When you open ZoomSearch you will see the first thing you need to do is define what is to be searched and how. Before you do that though I recommend you create a configuration file. ZoomSearch always opens to the default search configuration so select File | Save As and create a meaningful name. Now during this session of ZoomSearch any saves will be to your configuration.

The Offline Mode tab

1. The start directory is the location of the published output.
2. The output directory is where the indexing results are to be saved. For the purposes of this topic using a single project and a single search, use Windows Explorer to create a folder off the root of your published output, we will call that search_files.
3. The base url will be the relative path between the two. For the purposes of this topic using a single project and a single search, that will be ../

Each search option that you create will need its own configuration file and the details above will need to be amended for each option you offer.

Platform

Now you need to decide what how you are going to deploy ZoomSearch. For this topic I am going to use the javascript method but how do you decide what is right for you? If you visit Wrensoft's site, the differences are explained.

In short:

• The Javascript method is something you can set up yourself but it has limits that may be applicable. Wrensoft suggest a limit of 1,000 topics but I have used it with higher numbers and have seen others report it working satisfactorily up to 2.000/3,000 topics. You will have to test against your own outputs. Also note that phrase searching is not available using the javascript method, your options will be all words or any words.
• PHP and CGI need to be enabled on the server that will host the help and that is something your developers or IT people will have to set up. It is not difficult for them so don't let them put you off. A CD or DVD can be set up to run these methods and the same tools can be used within a folder to make it work as if it were on a PHP/CGI enabled server, although it is not quite as slick as the server being properly enabled.

Configuration

Next you need to set up the rest of the details for the ZoomSearch configuration files, one for each search that you want. For now let's just think about creating a single search across the whole help project. We can cover multiple search options later.

1. After opening ZoomSearch, click on the Offline Tab and then select File | Save As.
2. Navigate to a folder where you can store your configuration files and give the file a meaningful name.
3. Now we can start configuring the search without risk of saving the changes to the default configuration. Click the Configure button to access the configuration screen. Don't be put off by the number of options. This article covers the ones you need to know about and they are described below.

Before you run the indexer, click Save. You don't want to lose those settings.

Then click Start Indexing and sit back, not for long though unless you have a really heavyweight target!

Examining the Results

Examine the statistics at the end of the log in the ZoomSearch screen. Do they seem about right?

Look at the files searched. Anything you do not want in the results? If there is, go back to the skip list and edit it, then run the indexer again.

Step 4 - Link The Search To Your Project

At this point we have our help output and within its folders we have the search data. Trouble is that at the moment, they are not talking to each other.

I will cover two ways of linking the search to your project.

• Method 1 is used if you are setting up a single search, be it across a single project or a merged setup.
• Method 2 is for any other set up.
  I have only described how to set up searches across all the projects and individual child projects. If you have other options, you will need to work out the details, the principals are the same.

If your options include RoboHelp outputs outside the merge, note that ZoomSearch does not open the help using the method startpage.htm#path/target.htm.

If this is your first time working with ZoomSearch, remember that I suggested you work with a single project and a single search so please use Method 1 at this stage.

Method 1

For use where the end user will be given just one search option.

1. In RoboHelp, highlight the search_files folder and import the search.html page that was created by ZoomSearch in your output in Step 3.
2. RoboHelp will import some of the javascript files as well. Delete those using Windows Explorer. All the files you require are already in the output.
3. Open the Skin Editor and create a new button. Call it ZoomSearch and use whatever text and images you want. On the Advanced tab, point to the search.html page that is in the project, not the one in the output.
4. Generate and publish your help. In the second page of the wizard make sure you deselect RoboHelp's own search and select your own ZoomSearch button.
5. Go to the published help and test.

Method 2

For use where the end user will be given multiple options.

If the output is a merged webhelp setup, these instructions assume your structure is the one I describe elsewhere on my site. If you have a different structure you will have to adapt these steps.

Stage 1

In this step you will set up and test the page to which your users will go to select which search option they want to use.

1. Go to the Child 1 project and create a topic called Search Options in the search_files folder. Just give the topic a title for now. We'll add the options later.
2. Generate and publish Child 1 so that the Search Options page exists in the output.
3. In the parent project create a topic called Search Redirect. Make it a blank page in the same way as for the parent except the redirect is going to the Search Options page. Remember, the relative path is the one between the Search Redirect and Search Options in the output. In the demo it is
   <meta HTTP-EQUIV=refresh CONTENT="0;URL=.\mergedProjects\child_1\search_files\search_options.htm">
4. In the skin for the parent, follow Step 3 for Method 1 except point to the search.redirect.htm page.
5. Now generate and publish the parent. In the second page of the wizard make sure you deselect RoboHelp's own search and select your own ZoomSearch button.
6. At this point we test before moving on. Go to the published help and open the start page for the whole merge. You should see your Search button. Click on it and make sure you are taken to the Search Options page. If not, check your work until it is fixed.

Stage 2

Now you can link the search data for the whole output.

1. In RoboHelp open child1 and highlight the search_files/all folder and import the search.html page that has been created in search_files/all in your output.
2. RoboHelp will import some of the javascript files as well. Delete those using Windows Explorer. All the files you require are already in the output.
3. Go to the Search Options page in Child 1 and create a link to the search.html file that you imported in Step 1.
4. Generate and publish Child 1.
5. Repeat the test in Stage 1 - Step 6 clicking on the link you created in Stage 2 - Step 6. This should open the same search as Method 1.

Stage 3

In Stage 3 we create all the additional search options that are required. For the child projects, I suggest you create and save separate ZoomSearch configurations.

• For child 1, direct the output to search_files/child1.
• For all other child projects, direct the output to a search_files folder created within that child.
• In each child project, import the specific search html page that you create in the output and point the Search Options page in Child 1 to those search.html pages.
• For searches outside the merge, follow the same general principles.

Important

Remember, because you are using a tool external to RoboHelp, the search data is not automatically updated when you generate and publish. You have to remember to update the search when you update your output(s).

If you have a search that covers all topics and you then only deliver some of the child projects the search will include topics that you have not delivered and the user will get a page not found option. Oops! The search data will need to be created again so that it does not include the details of the modules not delivered.

Generating Multiple ZoomSearch Configurations

If you need to generate a number of configurations, James Reinhard very kindly sent me a batch file that he developed in consultation with Wrensoft. Download this text file in which James has put all the information you need.

Topic Revisions