Link to a PDF from HTML Help


You might find it difficult to get the desired behavior from external links in a project with HTML Help output. Microsoft has released a string of recent security updates which have placed limitations on what can be done in this format. For example, you cannot open a CHM directly from a URL, you can't launch another CHM file from one currently open, and you can't [easily] launch external files and applications from a CHM hyperlink. This project demonstrates the latter—how to create links which will open an external file (in this case, a PDF).

You'll use conditional text with pass-through behavior to insert the necessary object for the desired type of link.


The following pages from Microsoft's knowledge base and development site were used to design the procedures necessary to make external links function correctly in a CHM:

How To

There are two main methods recommended for inserting links to external documents into a CHM. You can use either ActiveX Commands or a JavaScript function to implement the workaround. In both cases, you'll want to apply a conditional text tag to the script. Then, you'll use the "passthrough" feature in your ePublisher project to force the HTML Help viewer to treat it as code instead of content.

ActiveX Command

You can present the link as either text or a clickable button by creating an ActiveX object and passing it the basic commands to get the results you want. The code you'll use will follow this basic format: {{{<OBJECT id=hhctrl type="application/x-oleobject" classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11" codebase="hhctrl.ocx#Version=4,73,8412,0"><PARAM name="Command" value="ShortCut"> <PARAM name="Text" value="Text:Click Here"> <PARAM name="Item1" value=",filename.pdf,"></OBJECT>}}}


The HTML Help viewer requires an absolute path to launch an external file, but you may not know the path to which your help system is installed on a user's machine. You can use a JavaScript function to determine that path when a link is clicked. This will require two steps: insert the function definition, then insert the function call.

The definition can be included with passthrough conditional text as needed in individual files that require it (be sure it appears after the page break preceding the link), or you can add it as part of an override to Page.asp, meaning it will be copied into every output page (use this method if you have many external links throughout your help system). The function code looks like this: {{{<SCRIPT Language="JScript"> function parser(fn) { var X, Y, sl, a, ra, link; ra = /:/; a =; if (a == 2) X = 14; else X = 7; sl = "\\"; Y = location.href.lastIndexOf(sl) + 1; link = 'file:///' + location.href.substring(X, Y) + fn; location.href = link; } </SCRIPT>}}}

In place of a link with a hypertext marker, you'll insert the anchor tag below with the same chm-only conditional text for each desired link.

<a onclick="parser('filename.pdf')">Click here</a>

Sample Project

This project demonstrates the problems caused by typical hyperlinks in a CHM, and includes examples of how to implement the workarounds described here. The project uses a condition called "CHM_Link" which is set to "visible" and "passthrough" in the project's Conditions settings.

Download sample project

HelpCenter/Tips/PassThroughCondition/CHM_LinkToPDF (last edited 2008-02-13 06:18:24 by localhost)