Searching with ZoomSearch

What's covered?

This topic covers the use of ZoomSearch, a search tool from Wrensoft. It is used on this site and can also be used in conjunction with a RoboHelp project. The instructions here specifically cover setting things up to work in RoboHelp projects but you should be able to adapt them for use with other HTML editing tools.

Note that these instructions only apply to webhelp outputs. ZoomSearch will not work with compiled HTML help in CHM format.

Introduction

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

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.

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:

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

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:

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.

ZoomSearch Tab

Comments

General

The first thing you will see is the level of on screen support. Also note the Help button that takes you to good context sensitive help. In addition there is a more comprehensive PDF file on the Wrensoft site.

Accept the defaults for now.

Search Page Again the fields are all fairly obvious. Accept the defaults for now.
Scan Options

This lists all the file types that will be scanned. You will probably want to delete all except HTM and perhaps HTML.

Note that plugins are available to also search PDF and DOC files. They are easy to set up and work well. I use them on a company intranet and they work very well but they are outside the scope of this topic.

Skip Options

This lists all the folders and files that will not be scanned and the words that will not be indexed.

This tab requires some consideration. You need to exclude the internal folders and files that RoboHelp creates otherwise your users will be able to access them with ugly results.

  • \wh excludes many of the internal folders but you must take care to ensure that none of your other folders start with wh.
  • If you know that none of your folders and files have the string wh in them, then you could also add that. I found files that started with the following and defined them individually. whc, whf, whg, whi, whn, whp, whs and wht.
  • You need to excude your startpage which is one reaon I always use index.htm for that. Adding index to the string will also exclude the index_csh and index_rhc files that RoboHelp creates.
  • You also need to exclude any redirect pages you may have. If you use my merged webhelp method you will want to exclude the parent.htm redirect page for example.

For now, set up those exclusions. Examine the results of your first search later and make further changes if required.

Note also the ability to define words not to be included in the search. If a user searches on one of those words, they will be told it has been excluded from the search.

Indexing Options Accept the defaults for now.
Results Layout Accept the defaults for now. You can only modify the template after creating your first index file so look at that later.
Categories I haven't used this part of ZoomSearch but the word from someone who has was "doddle"!
Synonyms This can be useful where, for example, you use the term Warehouse in your help but know your customers may use Depot or some similar term.
Limits

The maximum number of files that ZoomSearch will index varies with the version.

  • Free version - 50.
  • Standard version - 100
  • Pro version - 200,000. (The default in the Pro version is 1000 but you can change that.)
  • Enterprise version - 1,000,000
Authentication For most help projects this will not be required. Use if the help is on a publicly accessible site and you want to index the files on the server rather than a local copy.
FTP

Do remember you must run the index every time you create a new output. It is not done automatically when you generate the help.

You can configure ZoomSearch to upload the files after indexing or you can upload them manually.

Languages If these fields don't mean anything to you, leave them alone! You will know if they are relevant.
Status Log This defines what you want to see displayed when the indexer runs. Accept the defaults for now.
Advanced Accept the defaults for now.

 

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!

 

Project and Search Type

Method 1

Method 2

Single Project - Single search.
*
Single Project - Search options.
*
Merged WebHelp - No search options.
*
*
Merged WebHelp - Search options given but the options do not include specific child projects.
*
*
Merged WebHelp - Search options including specific child projects.
*

 

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.

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

Date

Changes to this page

11 Jan 2007 New topic.