Searching with Zoom 7

 

 

What's covered?

This tutorial covers the use of Zoom 7, a search tool from PassMark Software (previously Wrensoft). If you are using Version 5 or 6, please click here.

What's new in Zoom 7? See the Zoom Search Engine site.

Originally these instructions only applied to WebHelp and WebHelp Pro but there is a section explaining how to use Zoom with the Indigo responsive HTML5 layout. FlashHelp is not covered as it was little used and was withdrawn in RoboHelp 2017.

Zoom 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 work through the option you choose. You will therefore skip some of the content. Also you will not need to change all the Zoom screens shown, you just need to be aware of them.

April 2019 - Passmark have recently released Version 8. I have not tested that but based on past experience, this page should still be good for RoboHelp up to 2019 Classic. The new UI version of RoboHelp is a very different beast and I have not used it there. The general principles should be the same. That said, as I indicate below the search within RoboHelp has been improved a lot over the years so try that first.

Introduction

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

Over several versions, RoboHelp has addressed some of those requirements and will now meet the needs of many users. However, if cannot upgrade or you need any or all of the following features, then you should consider Zoom.

I first came across Zoom 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 Zoom 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 Zoom.

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 that 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 Zoom 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 a redirect page as you are viewing from a webserver rather than an intranet. You will see I have added a simple "Please wait, search loading" message that appears briefly. The chances are you will not see it in your live system.

Single Project Searches

Both projects below were created in RoboHelp 8. Just allow them to upgrade to any later version. The steps are the same regardless of version. The downloads contain the source project(s), the generate and publish folders plus the Zoom configuration files.

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.

Merged WebHelp Searches

Click here to download the RoboHelp 10 demo that can be upgraded to any later version.

Responsive Help

There is also a download set up for responsive help with additional instructions below.

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 Zoom 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 Zoom 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_files.
  2. Highlight the search_files 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 Zoom 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. Add the following in the <head> section of your code.

    <script language="JavaScript" type="text/javascript">
    //<![CDATA[
    <!--Script courtesy of http://www.web-source.net - Your Guide to Professional Web Site Design and Development //-->
    var time = null
    function move() {
    window.location = './mergedProjects/child_1/search_files/search_options.htm'
    }
    //]]>
    </script>

  5. Open the Skin Editor and create a new button. Call it Zoom 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

If you have set up your merge with content in the parent project:-

  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 Zoom, 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 System, 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 Zoom will create the files it requires. This can be done while setting up the Zoom 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 Zoom 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.

  4. If you are using RoboHelp 10, there is another step. Each output will contain a whtopic.js file. Around line 2034 you will see some code
    else
    document.location.reload();
    Prefix both lines with two forward slashes to comment them out.
    If not done, when the searches are started Firefox they will show as Connecting and go into an endless loop.

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 Zoom

In this step, you will set up Zoom.

The free version from www.zoomsearchengine.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.

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 Zoom 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 Zoom'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 Zoom. For this topic I am going to use the javascript method.

In short:

  • The Javascript method is something you can set up yourself. Zoom 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 Zoom 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 Zoom'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.

In earlier versions, plugins were required to search PDF and DOC files. In Version 7 these are now part of the standard installation.

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. Note, the start page is not the same as the default topic.
  • 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 Zoom will index varies with the version.

  • Free version - 50.
  • Pro version - 200,000. (The default in the Pro version is 1000 but you can change that.)
  • Enterprise version - 1,000,000

The Standard version for up to 100 files is no longer available in Version 7.

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 Zoom will output its files. If you can access that folder by file system (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.

Autocomplete

This is new in Version 7. Set this option if required.

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 Zoom but the word from someone who has was "doddle"! The downloadable Zoom 7 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 Zoom 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 Zoom 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 Zoom 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 Zoom will start its searching. In this tutorial, that is published_help.

Output Directory

The output directory is where you want the Zoom 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 Zoom 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 Zoom 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 Zoom 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 Zoom 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 Zoom. 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 you 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 Zoom creates, you will find some embedded styles. They are explained here.

https://www.zoomsearchengine.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.

WebHelp Pro

I have been advised that this method also works with WebHelp Pro.

Responsive HTML5 Layouts

This demo was created using RoboHelp 2017 and the method described only works with the Indigo layout.

Click here to see a working demo. Search for "red", "green", "blue" and "white".

Click here to download the demo project.

What do you need to know when setting up your own project?

There is an important proviso to consider before you embark on this. To use Dynamic Content Filtering, you must use RoboHelp's own search. Zoom cannot be configured to adapt to the different options the user may set. You could of course use Zoom's Categories but that would only filter the search results rather than the TOC, Index and so on. Otherwise, using Zoom with the Indigo layout is a lot easier than it might appear here from the number of steps!

If you are using the supplied Indigo layout that shipped with Update 2 without any customisation, you can skip Steps 3, 9 and 10 below. Simply open the demo download and export the layout for import into your project. If you have customised the default layout and do not want to redo those customisations, then you will need to follow all the steps.

  1. I have set the generate folder to within the RoboHelp project while the publish folder is outside the project. You will find it better to work that way.
  2. When you generate, RoboHelp deletes everything from the generate folder including the search_files folder so if you test after just generating it will not work.
  3. To save the hassle of remembering to add the search files back in each time you update the help, you don't use what is in the generate folder, you publish as well. In the publish folder RoboHelp does not delete anything, unless you set it up that way, so don't! When you publish, the search.html file in the publish folder will not be overwritten so use the published output.
  4. In the demo I have taken advantage of the Custom URLs that you can define in the layout editor. See Basic Settings. The relative path defined (./search_files/search.html) will find search_files folder within the output. In your project you need to add a Custom URL using the layout editor.
  5. With that URL defined, generate and publish an interim output.
  6. Next you need to run Zoom. For a basic test, use the configuration supplied with the demo and just amend the paths. Later you can amend the configuration to make Zoom work exactly as you want. How is described above.
  7. If you now open the published help, you will see the Search link and it should open the search page. Note it will open it in a new window but it will work and that's all we want to test at this point.
  8. Run a search and the topics should open in the same tab. That is not the same tab as the help but we will fix that later. The topic will open with the TOC and so on being available but there will be a link that changes that. You will also see the RoboHelp search fields at this point and that too will be fixed. For now the aim is just to check the search page does open and finds the topics.
  9. The next step is to remove RoboHelp's search field from HomePage.slp. In the Output Setup tab, go to the Screen Layouts and expand the Indigo layout. Double click HomePage to open it in Design Editor. Locate the following code and delete it. Right click HomePage and select View to check the Search field no longer appears.

    <div class="frontpage-search-field" role="search" data-controller="SearchController:sc">
    <input class="wSearchField" type="text" data-class="no-filter: [email protected]_FEATURE.filter" data-attr="placeholder: @KEY_LNG.Search; aria-label:@KEY_LNG.Search" data-value="KEY_SEARCH_TERM" data-focus="@focusin_searchbox(true)" data-blur="$sc.handleFocusOut('focusin_searchbox')|timeout:200" data-keyup="$mc.newSearch(node.value, event.keyCode),$sc.handleKey(event)|debounce:150" tabindex="7"/>
    <a class="wSearchLink" data-click="@EVT_SEARCH_TERM(true)" data-attr="href:'#';aria-label: @KEY_LNG.SearchTitle" tabindex="8"><span style="display: none" aria-hidden="true" data-html="@KEY-LNG.Search"></span></a>
    <div data-if="@focusin_searchbox" class="search-list" >
    <table>
    <tr data-repeat="search_results" data-class="search-suggestion:true; search-selected:@selected===#{@index}" data-click="$sc.handleClick(#{@index})">
    <td class="search-text-column"><div class="search-text" data-itext="item.term"></div> </td>
    <td><div class="search-delete" data-if="$sc.canDelete(#{@index})" data-click="$sc.handleDelete(#{@index})"></div></td>
    </tr>
    </table>
    </div>
    </div>
  1. There is also a search field when topics are open. Open Topic.slp and find the code shown below and delete it. It is near the end of the file and will appear as a single line. Right click the Topic and select View to check the Search field no longer appears.

    <input class="wSearchField" type="text" data-class="no-filter: [email protected]_FEATURE.filter" data-attr="placeholder: @KEY_LNG.Search; aria-label: @KEY_LNG.Search" data-value="KEY_SEARCH_TERM" data-focus="@focusin_topicsearchbox(true)" data-blur="$sc.handleFocusOut('focusin_topicsearchbox')|timeout:200" data-keyup="$mc.newSearch(node.value, event.keyCode), $sc.handleKey(event)|debounce:150" tabindex="-3"/>
  2. Now generate and publish the help again. We are not there yet but you will see it is working as described in 8 above but without RoboHelp's own search fields.
  3. Locate usersettings.js in the Output Setup tab > Screen Layouts > Indigo. Click View (not Edit With) to open the file in Notepad. Near the end you will find the line
    var link = '<a href="'+customlink_1_href+'" title="'+customlink_1_text+'" target="_blank">'+customlink_1_text+'</a>';
    Change _blank to _self.
    That will cause the search page to open in the same tab.
  4. In the Zoom Skip section, add topic.htm.
  5. In the Zoom Scan options, remove html so that only htm remains.
  6. Now generate and publish again and run Zoom again.
  7. When you click Search the search page will open in the same tab and when you click a topic in the results, that will be in the same tab but without the TOC and so on. The "Click here to see this page in full context" will restore those. If you don't like that text, you can change it in the project's Language File. Project Settings > General Tab > Advanced button and scroll down to ShowTopicInContext in the Responsive Help section.

Donations

If you find the information and tutorials on my site save you time figuring it out for yourself and help improve what you produce, please consider making a small donation.

Topic Revisions

Date

Changes to this page

17 Jun 2019

Amended to cover applicable RoboHelp versions.

22 Apr 2019

Originally Zoom was produced by Wrensoft whose site was www.wrensoft.com. The company is now part of Passmark Software. There is a dedicated site for Zoom. The text of this page has been changed to reflect these changes.

19 Apr 2019

Release of Zoom Version 8 referenced.

15 Jan 2018

New topic.