About popup topics

<< Click to Display Table of Contents >>

Navigation:  Reference > Modules, Conditional Output & Variables > Context-Sensitive Help & Popups >

About popup topics

Popup topics must be created without TOC entries because they are never included in the TOC (Table of Contents). If a topic has a TOC entry you will not be able to use it as a popup.

Instead of being displayed in the help viewer popups are displayed in small "popup windows" that are closed again when the user clicks after reading their contents.

All popup topics can be displayed with links from within your help file. HTML Help (CHM) native plain-text popups can also be displayed within your application, without displaying the main help viewer. Then they are referred to as "field-level popups".

The two uses for popup topics:

Within the help file:

Inside the help file popups are used to display small items of information that you want to make available but you don’t want to include again and again in the help text.

A good example of this would be a definition of a technical term that is used frequently in your text. Instead of repeating the definition again and again you would turn the term into a link that links to a popup topic. However, you may also want to consider using inline text toggles for this.

When the user clicks on the link the contents of the topic are displayed in a small popup box, without leaving the current topic.

Context-sensitive help:

HTML Help popup topics (but not JavaScript popups) can also be called directly from applications. When they are called in this way they are displayed on their own, without displaying the help file, and closed again immediately when the user clicks on them. This makes them a useful context-sensitive help tool for describing controls and functions in programs. See About field-level popups for more details.

The pros and cons of using popups:

Popups are definitely useful and it is tempting to make extensive use of them. However, there are a couple of issues you need to think about before doing so:

Using popups makes it more difficult to produce a printed version of your help. The user can’t display popups in a PDF or a printed manual so to produce the printed version you need to provide different ways of accessing the same information, for example by creating different versions of the text and using conditional output. This can be quite a lot of work and can get quite complicated to maintain.

Popups reduce the multi-output compatibility of your source. Plain text popups are exclusive to HTML Help, and in WebHelp (HTML) you can only use JavaScript popups. Popups do not work at all in Word DOCX, PDF and printed manuals.

If you want to produce multiple format versions of your help project from the same source it’s best not to use popups too much because they can significantly increase the work involved in maintaining the multiple versions.

If you need context-sensitive field-level HTML Help for display within your application it may be advisable to make a separate Help+Manual project just for these popups.

Where popup topics are supported:

Popups are not supported in all the output formats generated by Help+Manual, and the way popups are handled and the options available also vary from format to format. The following table provides a summary of where and how you can use popups:

Click to expand/collapseWhere popups are supported

See also:

Context-Sensitive Help (HowTo)

Conditions and Customized Output

Using JavaScript popups