Searching with ZoomSearch

Introduction

The way that RoboHelp's search function works suits many users but others are looking for something more. The most common requests are:

• 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.

Some time ago I saw a post on the RoboHelp forums extolling the virtues of ZoomSearch 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 - Create Your Help

Create your help in the normal way, be that a single webhelp project or merged webhelp. You will need to both generate and publish your output later. When you generate the help, RoboHelp clears the output folders and generates new folders and topics whereas when you publish it simply updates some or all of your topics. We need to add some folders to the RoboHelp output that we do not want trashed each time we create a new output, hence working on the published output.

In the demo projects, I have set those stages up as:

• Stage 1 - Create Help
• Stage 2 - Generate Help
• Stage 3 - Publish Help
• Stage 4 - Generate Search.

This topic focuses on Stage 4.

Two things to do with your help before proceeding further.

1. Open the project(s) and in Project Manager go to HTML Files (Topics) and create a folder which we will call search_files.
   You don't need to generate or publish at this stage unless you do not normally publish. In some environments the generated folders and files are handed over to the developers. If that is how you work, I recommend you also publish to your hard disk and hand those folders and files over when the process is complete. If that does apply to you, then you need to publish an output before proceeding when you use this method on your projects, it is already set up in the demo.
2. In the published output, create the same folder using Windows Explorer. Make sure it is in the same relative location to the root and has the same case.

Step 2 - Create Your Search Database

Now we can open ZoomSearch. The size of the demos is such that you can use the free version from www.wrensoft.com. That gives you the chance to prove to yourself that it really is as straightforward as I describe.

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.

What

• The start directory is the location of the published output. For the purposes of this topic, that will be a folder on the hard disk.
• The output directory is where the indexing results are to be saved. For the purposes of this topic, use Windows Explorer to create a folder off the root of your published output, we will call that search_files.
• The base url will be the relative path between the two, using the above folders that will be ../

How

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 but for RoboHelp you need only consider PHP, CGI or Javascript.

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 create a ZoomSearch configuration file 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 and follow the comments 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 3 - 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. The table should help you decide which method to use. Where merged webhelp is used you need to consider the options very carefully. For example, 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!

• If your options include RoboHelp outputs outside the merge, note that it does not open the help using the method startpage.htm#path/target.htm.
• Method 1 can be used with merged webhelp provided you only provide a search of all topics including the child projects OR the options do not include an options to search just a child project. If your options in merged webhelp are to include a search of specific child projects, you should use Method 2.

Method 1

1. Highlight the search_files folder and import the search.html page that has been created 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. 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

This method assumes your structure is the one I describe in Merging WebHelp. If you have a different structure you will have to adapt these steps. Try the steps using the downloadable demo to understand the concept first. At this stage I need to point out that so far you have only created one search database. The steps include creating the additional databases.

Stage 1

1. Go to the Child 1 project and create a topic called Search Options. 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 we need to change the way the search of all topics is configured and then set up the searches of the child projects.

1. In the published help for Child 1 you created a folder called search_files. Under that create two folders, all and child1. Delete any earlier search files.
2. Open the ZoomSearch configuration file that was created earlier and change the output folder so that it now goes to search_files/all in the published folder structure. Change the relative path (add ../).
3. Open the Child 1 project and add the all and child1 folders to search_files.
4. Highlight the search_files/all folder and import the search.html page that has been created in your output.
5. 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.
6. Go to the Search Options page in Child 1 and create a link to the search.html file that you add in Step 4.
7. Generate and publish Child 1.
8. 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).

Topic Revisions