Link to a PDF from HTML Help
Contents
Description
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.
References
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>}}}
- Where:
- 'Click Here' is the next to be displayed on the link.
- 'filename.pdf' is the name of the file to which you are linking.
Replace name="Text" with name="Button" to create a clickable button link.
- The file path should be entered as relative to the CHM file (no path if in the same folder).
JavaScript
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 = location.href.search(ra); 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> |
- Where:
- 'Click Here' is the next to be displayed on the link.
- 'filename.pdf' is the name of the file to which you are linking (with relative path).
- You can add CSS style attributes as needed to get the look you want for the link.
- You only need to add the function definition once per output topic page.
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.
- Note:
- PDFLink.pdf is the file created for the top-level group in the project when output is generated.
- Quick Start Guide.pdf is a file included in the project's User Files folder; it is copied into the output folder on generation.
Source document is FrameMaker format. Word example coming soon...