Key Information

You must create popup topics in the Topic Files section, not in the TOC section! You cannot assign the Popup topic class in the TOC.

1.Open the Project Files section In the Project Explorer and click on Topic Files, or a subfolder if you have created one and want to use it (see Creating new topics in Topic Files for more details).

2.Click on Add File in the Project tab to create a new topic.

3.Click on More and select Popup In the Topic Class: field. Note that you cannot select this class when creating topics in the TOC. You must do this in the Topic Files section!

4.You must enter a context number if you want to use your popup topics as field-level popups displayed in your application (without the main help, CHM files only). This is required by the Microsoft HTML Help API for field-level popups and if your popup topics do not have help context numbers they will not be exported to the internal popup text file in the CHM it.

The HTML Template and topic header settings are irrelevant for these topics because popups do not use HTML templates or headers. When you create hyperlinks to popup topics in your help they will automatically be displayed as popups. See Using Context-Sensitive Help for information on calling popups directly from your application. See this topic for instructions on creating field-level CHM popups displayed in your application.

How popup topics are handled depends on your output formats. If you want popups in HTML Help CHM files and WebHelp you must activate JavaScript popups, otherwise links to popup topics will be displayed as normal topics. HTML Help's native plain-text popups are not supported within the help, only in field-level popups that are displayed in your application without the main help file.

HTML Help and WebHelp:

In the Project Explorer select Configuration > Publishing Options > HTML Help/WebHelp > HTML Export Options. The settings are at the bottom of the page. The settings are shared for both formats

•Export popup topics as JavaScript popups
This enables JavaScript popups for both HTML Help CHM files and WebHelp. If you want to use popups within your help in these formats you must enable this option. Popup links in the project's topic files will be displayed as JavaScript popups in both formats when this option is activated. If it is turned off, popup links will display the target topics as normal topics. You can still use plain-text field-level popups in your application in HTML Help CHM files because the plain-text popup file is always included in the CHM, even when JavaScript popups are activated.

•Customize popup appearance
Select this to configure the formatting, colors and behavior of your JavaScript popup topics.

JavaScript popups are generated by Help & Manual. They support formatting, links and graphics but they cannot be used as field-level popups. They can only be displayed within your help file by other links in your help file.

Native CHM plain text popups are only available in HTML Help CHM files and can only be used as field-level popups that are displayed directly in your application without the main help. They only support plain text without any formatting, graphics or links. They cannot be

eBooks:

Windows Exe eBooks have no special popup topics settings. Popups are supported, but their behavior and appearance are automatic and cannot be changed. Popups are not supported in ePub eBooks.

In HTML Help CHM files the width of popup windows is controlled by the help viewer on the basis of the amount of text in the popup and the user's screen width. Since this system was designed a long time ago it does not allow for modern computers with wide-format screens and multiple monitors. When normal popups are displayed on these computers the popups are sometimes too wide.

Controlling popup width in HTML Help:

•In HTML Help's plain text popup topics (used when you turn JavaScript popups off, see above), the only way you can control popup width is by entering a hard line break (ENTER) at the end of each line.

Controlling popup width JavaScript popups:

•In JavaScript popups you can control popup width precisely by entering the entire text of the popup in a single-cell table with a fixed width. (Note that this doesn't work in HTML Help's native plain text popups because the table and its contents are stripped when you publish, resulting in an empty topic.)

•You must set the width of the single-cell table you use for this to an absolute value in pixels. Select Size Table Manually and enter the value in pixels. Don't use percentage values for this, it won't work properly!

You can speed up the process by defining a topic content template for your popup topics or using snippets. See Content templates for topics and Re-using content with snippets for details.

Any link within a project to a topic defined with the Popup class will automatically be displayed as a popup in any of the output formats where popups are supported (HTML Help, Windows Exe eBooks and WebHelp with JavaScript popups activated). Just create a normal link to the topic. Popups are not supported in ePub eBooks.

This is basically a job for the programmer, not the help author (you may be both, of course). All the help output formats generated by Help & Manual are fully standard-compliant so you can use the standard procedures for linking to and calling popups.

JavaScript popups in WebHelp and HTML Help CHM files:

You cannot create external links to JavaScript popups in WebHelp or CHM files. They can only be displayed with normal links within the page where they are being displayed.

HTML Help's plain-text popups:

•When you export to HTML Help with native, plain-text popups (turn JavaScript popups OFF to do this) Help & Manual stores the popup text topics in an internal text file in the HTML Help CHM file. By default this file is called CSHelp.txt, but you can change this file name in Configuration > Publishing Options > HTML Help > Popup Topics.

•Plain text popup calls from your application must be made to this file within the CHM file using the standard popup syntax of the HTML Help API.

•Plain text popup topics used in HTML Help must have context numbers for external calls from your application! This is required by the Microsoft HTML Help API for popups and if your popup topics do not have help context numbers they will not be exported to the internal popup text file in the CHM.

Tutorials for interfacing between your help and your application in the most common programming languages are available on the  tutorials page at the EC Software website. A free set of tools for interfacing to help and context-sensitive in help Borland Delphi and Borland C++ is also available at the website, on the Delphi resources page.

Output Format

Supported Popup Types

Where Supported

HTML Help (.CHM):

•Plain-text popups integrated in the main help file. Context numbers are required for these popup topics!

•Formatted JavaScript popups stored in the main help file.

Plain-text popups are supported both in the help text and as field-level popups in applications.

Formatted JavaScript popups can only be used in the help text. They are not supported for context-sensitive help.

Browser-based HTML
(.HTM):

•Fully-formatted JavaScript popups integrated in the individual HTML files.

JavaScript popups can only be used in help topics. You cannot link to them from your application.

Windows Exe eBooks:

•Fully-formatted popups with graphics, fonts, emphasis (bold, italics etc.) and hyperlinks (topic and Internet links).

Only available within eBooks. eBooks do not support context calls of any kind.

iBooks®/ePub eBooks:

•Popups are not supported. Popup links are automatically converted to plain text.

N/A

Adobe PDF and printed  user manuals:

•Popups are not supported. Popup links are automatically converted to plain text.

N/A

Word RTF:

•Popups are not supported. Popup links are automatically converted to plain text.

N/A