Searching with ZoomSearch

What's covered?

This tutorial covers the use of ZoomSearch, a search tool from Wrensoft. It has been rewritten for ZoomSearch 6 but still covers earlier versions.

Note that these instructions only apply to WebHelp. The method should work with FlashHelp but I have not tested it. ZoomSearch will not work with compiled HTML help in CHM format.

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

Don't be put off by the length of this tutorial. It covers a number of options and you will only need to set up whichever one you choose. You will therefore skip some of the content. Also you will not need to change all the ZoomSearch screens shown, you just need to be aware of them.

Introduction

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

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 the following features, then you should consider ZoomSearch.

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 and 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) and phrase searches. (Phrase searches are not available if you are using the javascript method described in this tutorial - don't confuse that with multiple word searches which can be used.)

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.

Demo and Downloads

Click here to see ZoomSearch work within RoboHelp. What you will see is a setup that offers multiple search options. In a single search setup, when you click the search button, you would go straight to the page that you see when you click Full Search on the Search Options page.

You may see the redirect page as you are viewing from a webserver rather than an intranet. Putting this demo on the server is the first time I have seen it. You will see I have added the simple "Please wait, search loading" message that appears briefly. The chances are you will not see it in your live system.

Click here to download a working set up (1.3mb) for a single project with a single search.

Click here to download a working set up (1.3mb) for a single project with search options.

Click here to download a working set up (5mb) for merged help.

The downloads contain the source project(s), the generate and publish folders plus the ZoomSearch configuration files.

Step 1 - Changing the source project(s)

In this step you set up your source project(s).

The steps needed will vary according to whether you are dealing with one project or a merge and whether you are offering one search or a number of searches.

I strongly recommend that first time around, you work with a dummy project and use the 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 the first time. If you get it wrong, you can simply trash the copy and start again.

Search Type

Action
Single search
  1. In Project Manager go to Project Files and create a folder with the name search_files.

  1. Highlight the search_files folder and and create a topic with the filename search.html. Note the full four character HTML extension, that is important. The file is required so that you can create a toolbar button that will open the Search page in the output.
  2. Create a conditional build tag called ZoomSearch and apply it to this topic. It is important that this topic is not generated or published.
  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 you created in Step 2.

If you are working with merged help, these steps will be performed in the parent project.
Search options - Single project
  1. In Project Manager go to Project Files and create a folder with the name search_options.
  2. Highlight the search_options folder and and create a topic with the filename search_options.htm. The options will be added later but the file is required now so that you can create a toolbar button that will open this page in the output. Leave the default text in this topic for now.
  3. In the same folder, create topics with logical names for each of the searches you require, such as full_search.htm, search_a.htm, search_b.htm etc. Remove the heading and change the text to Please wait, search loading.


  4. Open the Skin Editor and create a new button. Call it ZoomSearch and use whatever text and images you want. On the Advanced tab, link to the search_options page you created in Step 2.

  5. Now go back to the Search Options topic and create links to the files created in Step 3.
  6. The remaining step will be to add redirect metatags to the files created in step 3. That is covered later.

Now test progress. Just generate the help making sure that in page two of the wizard you deselect the default search button and select the one you created in Step 4. View the generated help and click the Search button. You should see the options and when you click each one, you will see the Please wait, search loading message you created. Nothing more will happen at this stage.
Search options - Merged help

Using my method of merging

  1. In the child_1 project, go to Project Manager > Project Files, create a folder called search_files and create a topic with the filename search_options.htm.

  2. In the same folder, create topics with logical names for each of the searches you require, such as full_search.htm, child1_search.htm, child1_search.htm etc. Remove the heading and change the text to Please wait, search loading.


  3. Open the parent project and create a topic called search_options_redirect.htm. Remove the heading and change the text to Please wait, search loading.


  4. Change to HTML view and add a redirect metatag. It will link to the search_options topic so it will look like this -
    <meta http-equiv="refresh" content="0;URL=./mergedProjects/child_1/search_files/search_options.htm" />

  5. Open the Skin Editor and create a new button. Call it ZoomSearch and use whatever text and images you want. On the Advanced tab, link to the search_options_redirect.htm topic.

  6. Now go back to the Search Options topic and create links to the files created in Step 2.
  7. The remaining step will be to add redirect metatags to the files created in step 2. That is covered later.

Now test progress. Generate the parent making sure that in page two of the wizard you deselect the default search button and select the one you created in Step 5. Also generate just the child 1 project. View the generated help and click the Search button. You should see the options and when you click each one, you will see the Please wait, search loading message you created. Nothing more will happen at this stage.

Other methods of merging

You probably have content in the parent project. If that is the case:

  1. Follow steps 1 and 2 but in the parent project.

  2. Skip steps 3 and 4.

  3. Follow step 5 but link to search_options.htm.

  4. Follow steps 6 and 7.

Test as in Search options - Single project above.

Step 2 - Adding folders to the published help

In this step you set up the folder(s) in your webhelp output(s).

If you already publish your help

Skip to Adding the folder(s)

If you do not already publish

Not everyone working with webhelp publishes the output but to use ZoomSearch, it does make the workflow easier.

What's the difference between generating and publishing?

The idea of publishing is to get the output onto a server from which users can access it. Sometimes this is done by the developers and you just hand them the files from the folder to which you generate. If that is the way you work, then you can publish to your local drive and hand over those files instead, it will make no difference to your developers. Here's what you need to do. If you are working with merged help, you need to repeat steps 2 to 6 in each project.

  1. Create a folder on your hard disk to which you can publish. Call it something like published_help.
  2. Open your project and open theWebHelp layout in the same way that you would to generate the help.
  3. Go to the last page of the wizard so that you can set up the publishing details.
  4. Click New, select File Transfer, give the destination a name such as published_help and then browse to that folder.
  5. Click OK and Finish so that RoboHelp generates your help.
  6. When it has finished, click Publish.
  7. If you look inside the published_help folder, you will see a duplicate of the generated help. It is a duplicate right now but that will change later.

Adding the folder(s)

In the same way that you added a folder in the source project(s), you need to do the same in the published_help folder as this is where ZoomSearch will create the files it requires. This can be done while setting up the ZoomSearch configuration(s) but you might find it easier to do this now using Windows Explorer.

Search Type

Published Help Folders
Single search

Add a sub-folder called search_files to the folder to which you published the help.

In a merged help setup, this will be done under the output from the parent so you will also see the mergedProjects folder.
Search options - Single project
  1. Add a sub-folder called search_files to the folder to which you published the help.
  2. Below that, create folders with the same names as the files you created in the source project. It is to those folders you will be directing the ZoomSearch files later in the process.
Search options - Merged help

Using my method of merging with Search All and Search Child options

  1. Go to the published_help folder that contains the output for the parent and child projects.
  2. Locate the child_1 folder and create two sub_folders, full_search and child_1_search.
  3. Locate the other child projects and create a folder in each, child_2_search, child_3_search and so on.

Merged Projects - Other searches

If you are creating other searches that cross over different projects, you will have to decide on the best structure as it depends on your setup. You might want to keep all the searches in one folder that has a sub-folder for each search. If you have any searches that are specific to a project, then I recommend the results are saved within that project. This is useful if that output will also be used in isolation.

Step 3 - Setting Up ZoomSearch

This section describes Version 6 of ZoomSearch. If you are using Version 5 or earlier, click here for this step.

In this step, you will set up 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.

If you have used ZoomSearch before, you will see a big change in ZoomSearch 6. The GUI has been completely redone and it is a huge improvement.

The first thing you need to do is create a configuration file so that all your settings are saved for future use. Go to File > Save As to save the opening default configuration file with your preferred filename. You can call it what you like, I suggest you use the RoboHelp project name. If you are going to need more than one, set up the first one and save it, then use that as the foundation for the others.

Now I will take you through the various ZoomSearch screens with just the information you need to set things up. 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 Wrensoft's site has excellent support and documentation that you can refer to later for more detailed information.

Start Options

1- Offline Mode

This is the mode we will use.

2- Start Directory

Getting these details right typically causes new users more problems than anything else. See More about Start Options for information.

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

In short:

  • The Javascript method is something you can set up yourself. Wrensoft suggest a limit of 10,000 topics for Version 6 which should be more than adequate for most RoboHelp users. You will have to test against your own outputs using the different browsers.. Note that phrase searching is not available using the javascript method, your options will be all words or any words. Also note that anything you see on the Wrensoft site about slow performance is relative to the other options. I don't think you will find performance is an issue.

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

Visit Wrensoft's site to learn about the other options if you need them.

4 - Start Indexing

Not yet! We need to set up the rest of the configuration before you click that button.

Scan Options

This lists all the file types that will be scanned. The default list is much longer. I have deleted everything except HTM and 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.

If you do want to install them, I recommend using the all plugins option available on Wrensoft's site.

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.
  • You need to exclude your startpage which is one reason 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.
  • For now, set up the exclusions I have shown.

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.

Spider Options

Leave the defaults. We are not using this method.

Search Page

Accept the defaults for now. You can return to this page later to fine tune things.

Results Layout

 

Accept the defaults for now. You can only modify the template after creating your first index file so we will look at that later.

Indexing Options

This defines what gets indexed. Accept the defaults for now.

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

The Start Options define the folder where ZoomSearch will output its files. If you can access that folder by file transfer (that is, you can see it in Windows Explorer), then select "Do not upload search" and leave the other fields.

If you want to FTP the files after the indexing is done, then enter the details here.

Languages

If these fields don't mean anything to you, leave the defaults! You will know if they are relevant.

Stemming enables entering fish to find fishes and fishing but stemming is not available with the javascript method described in this tutorial.

Weightings

This page enables you to change the weighting given to the location of the search words so that they get ranked higher or lower in the search results.

For now leave the defaults.

Filtering

You can use filtering so that pages must contain a specific word to be included or they will be excluded if they contain a specific word.

Leave this for now.

Categories

I haven't used this part of ZoomSearch but the word from someone who has was "doddle"! The downloadable ZoomSearch 6 User's Guide explains how Categories work. Broadly, the search can be based on s string in the topic path / filename, the file type or a meta tag inserted into a file to declare its category.

Sitemaps

This is not available for the Javascript method.

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.

Recommended

Leave this for now. The tip explains what this page does. It can be a useful feature but we don't need it at this point.

Custom Meta Fields

This enables a user to search for pages where not only is the search term found but it also falls within a range.

For example: A search requirement could be Cars but only those with diesel engines. Inserting these tags in relevant topics would include them. Those with petrol engines would not be included.

<meta name="CARS" content="1">

<meta name="FUEL" content="Diesel">

Leave this paga blank for now.

Index Log

Accept the defaults for now.

Advanced

Accept the defaults for now.

 

Having set up the pages with your options, click Save. You don't want to lose those settings. 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.

More about Start Options

The Start Options include the Start Directory, Base URL and Output Directory. For ease of explanation, I have shown them below in the order Start Directory, Output Directory and Base URL. That way I can tell you where the first two will be and then explain the relative path between them.

  1. The start directory is normally the location of the published output. Browse to the location so that ZoomSearch enters the full correct path. In the examples below, I have only shown the end of the path.
  2. The output directory is where the indexing results are to be saved. Browse to the location so that ZoomSearch enters the full correct path. In the examples below, I have only shown the end of the path.
  3. The base url will be the relative path between the two.

When setting up these paths, browse to the Start Directory and Ouput Directory so that ZoomSearch enters the full correct path. In the examples below, I have only shown the end of the path.

Search Type

Published Help Folders
Single search

Start Directory

The start directory is the folder in which ZoomSearch will start its searching. In this tutorial, that is published_help.

Output Directory

The output directory is where you want the ZoomSearch files to be located. In this tutorial, that is search_files.

Base URL

The relative path between those two is ../
Search options - Single project

Start Directory

The start directory is the folder in which ZoomSearch will start its searching. In this tutorial, that is published_help for the full search. For other searches it could be:

  1. published_help where the ZoomSearch configuration excludes certain folders and content.

  2. a lower level folder.

Output Directory

The output directory will be one of the directories you created within search_options.

Base URL

Where the start directory is published_help, the relative path between the start directory and the output directory is ../../

Where the start directory is a lower level directory, the relative path will start ../../ and then show the path from there to the required folder. For example ../../folder_one (Not shown here).
Search options - Merged help

Using my method of merging with Search All and Search Child option

Start Directory

The start directory is the folder in which ZoomSearch will start its searching. In this tutorial:

  • For the full search that is published_help .
  • For the child projects, it will be the directory below mergedProjects for that child.

Output Directory

The output directory will be

  • mergedProjects\child_1\search_files\full_search for the full search configuration
  • mergedProjects\child_1\search_files\child_1_search for the child_1 project.
  • mergedProjects\child_nn\search_files and so on for other child projects where nn is the number of the child.

Base URL

For the searches in the child_1 project, the relative path between the start directory and the output directory is ../../

For all other child projects the relative path will be ../

Merged Projects - Other searches

Follow the principles above. Sorry but it depends on where you search starts and where the results will be stored. Without knowing that, I cannot say what your relative path will be.

Step 4 - Creating the Search Databases

Here we create the search database(s).

On the ZoomSearch Start Options page, make sure you have opened the correct configuration file, click Start Indexing and sit back, not for long though unless you have a really heavyweight target!

Examining the Results

Go to the log tab and tick just the Indexing box. 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.

Multiple Search Options

You need to run each configuration file and make sure the output has gone to the intended location. Then test each option is only returning what you planned.

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.

Step 5 - Setting up the Search Options Page

If you only have a single search, skip this step.

Otherwise, you now need to go back to the source projects and add redirect meta tags to all the redirect topics your created. Those are the ones with Please wait, search loading in them. The redirect is shown below with a green border.

When the links on the Search Options page are clicked, this topic starts to open but immediately sees the meta tag and opens the file specified there instead.

Single Project with Search Options

Merged Help

Configuring the Search Page

You can amend the appearance of the default page. In the search.html page that ZoomSearch creates, you will find some embedded styles. They are explained here.

http://www.wrensoft.com/zoom/support/css.html

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.

Donations

If you have found this tutorial useful and it has saved you a lot of time figuring it out for yourself, please consider making a small donation.

Topic Revisions

Date

Changes to this page
05 Sep 2009 Some additional features of ZoomSearch added. Minor formatting corrections.
01 Sep 2009 Minor corrections.
31 Aug 2009 Extra screenshots added and steps made clearer.
25 Aug 2009 Reworked to cover multiple search options workflow.
22 Aug 2009 Topic rewritten to cover ZoomSearch 6.
13 May 2009 Topic rewritten.
30 Aug 2008 Generating muliple ZoomSearch Configurations added.
11 Jan 2007 New topic.