Calling WebHelp Using URLs

What's covered?

This topic describes how to call webhelp without using Map IDs. It covers calling webhelp in both single projects and merged projects.

See Snippet 70 if you are having problems with this method when using IE7.

Single Projects

If a topic from webhelp is called by an application, how it displays depends on how it is called by the developers.

Via the Start Page

Any topic in the help can be called in such a way that the user sees the required topic, the navigation pane (TOC etc) and the toolbar. It is done by using the format

X:/helpfolder/startpage.htm#path/target_topic_1.htm.

where X is the drive letter.

Provided the help is called in that way (startpage#target), the developers can use either an absolute path or a relative path.

That method is fine for calling one topic and is an approved method.

If you call a second topic in this way before the browser is closed, the new topic will not display and this was a problem. There are two solutions that I am aware of.

Solution 1

If your developers amend each call so that the first call has one query mark added and the next call has two query marks, then it will work correctly.

startpage?#path/topic1.htm

startpage??#path/topic2.htm

After that calls need to alternate so it would continue as below

startpage?#path/topic3.htm

startpage??#path/topic4.htm

My thanks to Werner Hutter for telling us about adding query marks to the call and Tony Harris for simplifying the method.

Solution 2

Add target="_new" to give something like

startpage?#path/topic1.htm target="new"

 

Direct Call to the Topic

Any method that is effectively the same as double clicking the topic in Windows Explorer, will open the topic but without displaying the TOC. This includes calling the help in the format

X:/helpfolder/path/target_topic_1.htm. (Note the absence of the start page and the # symbol).

Disadvantage of direct calls

The help will open without the navigation pane or the toolbar. Unless you have changed the RH defaults, there will be a Show link at the top of the page which will open the navigation pane and toolbar.

Using Map IDs

Help can also be called using map ids. The map id method is not covered in this topic.

Merged WebHelp

Help that is part of a merged webhelp project can be called using either of the above methods. If it is called via the start page, the format will be

X:/helpfolder/startpage.htm#mergedprojects/child_project/target_topic_1.htm.

The user will see the required topic, the navigation pane (TOC etc) and the toolbar.

The topic can also be called directly using the format

X:/helpfolder/mergedprojects/child_project/target_topic_1.htm.

The problem with a direct call and merged webhelp is that unless the topic was in the parent project, the TOC displayed will be for the child project of the topic that was called and there will then be no way of displaying the merged TOC.

The rest of this topic covers how to work around that limitation and improve things for the user. The work involved is not difficult but it may take a couple of attempts the first time. Getting your developers to call the help via the start page is strongly recommended.

Displaying the Merged TOC

This method suggests how to present the help in a way that is user friendly while preventing the TOC from being accessed until the user is in a topic from the master project. It is only necessary if your developers cannot call the help via the start page, and first ask them for a very good reason why not!

Let's cover how it works for the user before we look at the method.

When your application opens one of the topics as context sensitive help, if it is from a child project, the method prevents the Show link from being displayed. All the links on the page will work and the user can navigate according to whatever you put in the page. So if the topic were the help for a field in a data entry form, then one of the links could be to the help for the form itself. Thus having got to the context sensitive help for the field, the user could get the form level help in an easy and obvious way and, thus far, without needing the TOC. On many occasions, this will suffice.

For the user who does need more assistance, they can click an icon that will be include in each topic and the default help page for the parent project will displayed with the Show Contents and Index link. Click that and the full merged TOC will show.

All the method has done is prevent the user accessing the TOC until a parent project topic is displayed. However, they have been given access to help topics closely related to what they were doing so if they want help beyond that, then it is not unreasonable to effectively say "OK, you decide what help you want" and provide quick access to it. It is at least more friendly than giving them a TOC for a child project which then denies them access to the full merged TOC.

Method

Please note that this method was devised to work with the original method of merging webhelp described on this site. With some additional steps described below, it can be used with other structures, including the new method of merging webhelp described on this site.

As you will see, some of the steps may require you to use a multi file find and replace tool. RH has one built in or you can use something like Helpware's FAR, see the useful links topic on this site. They can be frightening the first time because unless you choose to OK each change individually, they will blast through your code and it is all too easy to really mess up a lot of things. Don't be put off by that as these tools can be very useful. It's just a case of being sensible as you are when you use chisels and knives, just make sure you have a backup of your project and you should be protected.

  1. Make that backup!
  2. In the parent project, change the text for the Show link to "Show=Show Contents and Index". Go to Project Settings, click Advanced and find "Show=Show" in the LNG file tab and edit that to "Show=Show Contents and Index". You can skip this step but I think it makes the purpose of the link more obvious.
  3. Except for the parent project default page, add an icon (say a house to represent the home page) in front of the heading of all topics in all projects and hyper-link it to the parent project default page.
  4. Generate and publish the parent project, make sure the "Show Navigation Pane Link in Topics" check box IS selected.
  5. Generate and publish the child (sub) projects, make sure the "Show Navigation Pane Link in Topics" check box IS NOT selected.
  6. Because of the different structure between source projects and published help, some changes will almost certainly be needed before the house icon functions correctly.
  1. If you are using the new method of merging webhelp described on this site, this method will not work with a redirect page. However the new structure can still be used.

The redirect page is a useful way of avoiding any links that are parent / child links. All the links used by the method are child / child links. If you want to use the method described here then you have to remove the redirect meta tag and make the default topic into one the user will see.

What you need to do is just have the one topic in the parent and this will contain whatever you would have put in the default topic for the merged help. On that page avoid links to any of the child projects, instead pointing the user to the TOC books for those projects. If links are unavoidable, then you need to manually edit them either in the source or in the generated / published files so that the relative paths are corrected.

When you have generated / published your help, you will find that not one of the house icons will work! That's expected at this stage. As you will understand from when you read the topic on merging the help, the structure between the source files and the published files is different. What you now need to do is use a multi file find and replace tool to correct things. The link for the house icon will be something like ../../parent/default_topic.htm. What you need to do is search for parent/ and replace it with nothing so that the path becomes ../../default_topic.htm.

Demo

Download a zip file to see this method working without going to the trouble of setting it up. Note that the demo is not structured in the way that I now advocate for creating merged webhelp elsewhere on this site. The demo preceded that method but does demonstrate what the user will see.

After downloading and unzipping the files (use Winzip's Extract icon to keep the required structure), open \Demo\mergedprojects\Module B\Module_B_Topic_2.htm or Module_C_Topic_2.htm using Windows Explorer to see the same as a user calling context sensitive help for a field or step in a process.

Also open Main_Module_A_Topic_1.htm in the same way to see the difference when calling a topic from the parent project.

Then open the help by double clicking \Demo\Main_Module_A.htm to see the help as if called from the menu.

Note Module_B_Topic_1.htm and Module_B_Topic_2.htm are the only topics in Module B. (Module_B.htm is the file created when RH publishes and the one that would be used to open that help if you wanted to give a user direct access to the sub project help.) The same principle applies to Module C.

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

24 Mar 2007 Reference to IE7 problem added.
21 Nov 2006 What's Covered revised following restructure of this area. No content change.
04 Jun 2006 What's Covered revised to include link to Greg Minter's topic on calling merged projects using map ids.
07 May 2005 Link added to Tommy Simmons method.
18 Mar 2005 Hyperlink added to Macromedia's Technote.
21 Feb 2005 Hyperlink added to topic on calling context sensitive help using Map IDs.
20 Dec 2004 Note added indicating that Method 2 does not work in RH Version X5.
22 May 2004 Method of highlighting the false broken links added.
17 May 2004 Topic amended to include a method which is easier but falsely reports broken links.