Link to an external local file from a CHM

Please note: Recent Microsoft Windows Service Packs (e.g. SP3 and later for Windows 2000) block SHORTCUT commands for "security reasons" and so these instructions may NOT work with upgraded and later versions of Windows.

Date created: ~2003

Sometimes a CHM needs to reference other documents that will reside either in the same directory as the CHM, a higher level directory, or in a sub-directory 'beneath' the CHM. This may be the case when you are creating a CHM for internal usage within a company, or where there are many related documents that are delivered with the software (for example, on a CD-ROM).

Caveats

  • All testing was done using AuthorIT, although the tool used shouldn't make any difference. However, tests have not been done using any other Help Authoring tool, so no claims can be made that these instructions will work in every case. Note: If you are using AuthorIT, test the links by opening the CHM in the Publishing folder, NOT from the View Output option on the Publishing window.
  • These notes do not discuss linking to an external file located on the internet.
  • All files that are to be linked must either reside in the same directory as the CHM, a higher level directory, or a sub-directory 'beneath' the CHM's directory.
  • If the name of the directory(ies) or file changes, the link will no longer work.
  • The application that would normally open the file type must be installed on the user's computer, otherwise the file will not open. (For example, if you are linking to an Excel spreadsheet, you must have Excel installed.)
  • Only HTML Help (CHM) has been tested, not plain HTML. It is known that the 'shortcut' command used by hhctrl.ocx will NOT work in plain HTML.

Linking to a file located on a network

If the CHM will only be used internally, then you can link directly to a file by specifying the full file path as the link within the <a href> tag.

For example: <a href="file:\\servername\foldername\filename.ext">, where:

  • servername is the name of the server,
  • foldername is the name of the directory (you can have as many of these as are needed, each separated by \ ),
  • filename is the name of the file, and
  • ext is the file extension (e.g. DOC, XLS, PDF, PPT, TXT, etc.).

You can use a drive letter instead of servername, however you must be absolutely sure that everyone on the network maps the servers to the same drive letters.

Assuming the application is installed on the same machine as the CHM, and is one that Internet Explorer recognizes (for example: HTML, text, graphics, PDF and Office files) the file will open in the right hand pane of the Help and has some basic editing features (but no menus or toolbars). Any changes you make to the document within the pane will be saved to the ORIGINAL linked document if you press Ctrl+S. (Note: if the file type is not one recognized by IE, it will be executed as an external program and cause an "open or download" prompt.)

Be VERY CAREFUL if the link is to a Microsoft template (e.g. DOT). Any changes you make will be saved to the template itself if you do a Save (CTRL+S) and not a Save As (F12). F12 will at least ask for a new filename, but will still try to save the document as a template, by default. You can overcome the problem of a DOT file being modified by NOT including the file name. So, you'd use file:\\servername\foldername\ ONLY, where:

  • servername is the server name, and
  • foldername is the name of the directory where the DOT file is stored.

By using this syntax, the right pane of the CHM opens like an Explorer window listing all the files in that directory. Double-clicking on a DOT file opens Word as a separate application (ignore the message), with the template opening as a new DOC (as it should be). Because Word opens as a separate application, you have all the controls you normally have with Word.

Linking to a file in the same directory as the CHM

When you start linking a CHM to files that don't have a defined path, you will need to use the hhctrl.ocx shortcut object for each link. You can specify whether the link will be text or a button. Using the hhctrl.ocx Shortcut command opens the linked file separately from the CHM; for example: a Word document link will force Word to open and display the document.

<OBJECT id=hhctrl
type="application/x-oleobject"
classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"
codebase="hhctrl.ocx#Version=4,73,8412,0"
width=100
height=100>
<PARAM name="Command" value="ShortCut">
<PARAM name="Button" value="Text:Document">
<PARAM name="Item1" value=",document.ext,">
</OBJECT>

where:

  • Document is the name you want to appear on the Button, and
  • document.ext is the file (with the relevant extension) you wish to open. (For example, abc.doc, defg.ppt, hijk.xls, lmno.pdf.)

You can replace the PARAM name Button with Text and this will result in a text link as opposed to a button, and you can specify the font and size of the text displayed:

<OBJECT id=hhctrl
type="application/x-oleobject"
classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"
codebase="hhctrl.ocx#Version=4,73,8412,0"
width=100
height=100>
<PARAM name="Command" value="ShortCut">
<PARAM name="Font" value="Arial, 10pt">
<PARAM name="Text" value="Text:Doc name">
<PARAM name="Item1" value=",document.ext,">
</OBJECT>

where Doc name is the text that will be displayed as the link; note that the PARAM name is Text and the beginning of the value is also Text:.

To make these links look as much like real hyperlinks as possible, add the Font param and value - if you don't, the text comes out at about 8pt.

Linking to a file in a sub-directory of the CHM

Use the same syntax as the previous example, but change the last PARAM value. You can even link to sub-directories a few levels below the CHM's directory. For example:

<OBJECT id=hhctrl
type="application/x-oleobject"
classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"
codebase="hhctrl.ocx#Version=4,73,8412,0"
width=100
height=100>
<PARAM name="Command" value="ShortCut">
<PARAM name="Font" value="Arial, 10pt">
<PARAM name="Text" value="Text:Doc name">
<PARAM name="Item1"
value=",subdirectoryname\subsubname\
document.ext,">
</OBJECT>

where:

  • subdirectoryname is the name of the first level sub-directory below the root CHM,
  • subsubname is the second level sub-directory, and
  • document.ext is the file name with the relevant extension.

Linking to a file in a higher level directory

Use similar syntax to linking to a file in the same directory, making sure you add ..\ in front of the file name for each level 'up' you need to go.

<OBJECT id=hhctrl
type="application/x-oleobject"
classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"
codebase="hhctrl.ocx#Version=4,73,8412,0"
width=100
height=100>
<PARAM name="Command" value="ShortCut">
<PARAM name="Font" value="Arial, 10pt">
<PARAM name="Text" value="Text:Doc name">
<PARAM name="Item1" value=",..\document.ext,">
</OBJECT>

For two levels higher, use ..\..\document.ext

Linking to a sub-directory of the CHM

If you have a large number of documents in the one sub-directory, or if the name of the document changes regularly as new revisions are signed-off, you may want to link just to the sub-directory.

<OBJECT id=hhctrl
type="application/x-oleobject"
classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"
codebase="hhctrl.ocx#Version=4,73,8412,0"
width=100
height=100>
<PARAM name="Command" value="ShortCut">
<PARAM name="Font" value="Arial, 10pt">
<PARAM name="Text" value="Text:Folder name">
<PARAM name="Item1" value=",subdirectoryname,">
</OBJECT>

where:

  • Folder name is the name that will be displayed as the text link,
  • subdirectoryname is the name of the first level sub-directory below the root CHM (you could go down further by using subdirectoryname\subsubname where subsubname is the second level sub-directory).

Linking using a JavaScript (JS) file

You can also create links using a JS file. However, I have not experimented with this so can't confirm that it works. For instructions, see:
http://msdn.microsoft.com/library/en-us/htmlhelp/html/
vsconOcxscriptslinkchm.asp?frame=true

Other

  • For details on the hhctl.ocx control, see:
    http://msdn.microsoft.com/library/default.asp?
    url=/library/en-us/htmlhelp/html/vsconocxintro.asp
  • For details on using an Applet, see:
    http://helpware.net/FAR/far_faq.htm#Applets

Thanks

Thanks to the following people whose information helped me get this figured out: Kendra Carter, Debbie Pulver, Gretchen Wilcox (AuthorIT), and Rob Chandler (Helpware). Also to Rob Cavicchio who took the time to check the code and correct me on a number of things.