Mixing Online and CHM Content

by Tony Self, HyperWrite Pty Ltd

We recommend using Internet Explorer (Version 4 or later) to display this article because some of the examples are done in Dynamic HTML (DHTML) targeted at this browser.

Click a link below to jump to a particular section; click any "TOP" image following a section heading to jump back here.

Introduction
The Scenario
External HTML Help TOC Nodes
Integrating
Getting Clever
Onwards

Introduction

This article discusses some practical ways in which "live" online content from a Web server can be integrated with "static" local content stored in a Microsoft HTML Help CHM file.

Along the way, we will be talking about JavaScript routines, Cascading Style Sheets (CSS), HTML Help Workshop, and Hypertext Transfer Protocol (HTTP). Although you don't have to be an expert in these areas, a broad understanding of the concepts will make this article easy to follow.

We will also be making a few assumptions. One assumption is that to deliver "live" content you will need access to a web server. From this point on, we'll use the term Web content to describe live, online content. Local content will describe content in the CHM file installed on the user's PC. Another assumption, perhaps obvious, is that the user will need to have some sort of Internet/intranet connection to access the Web content.

The Scenario

You are building an HTML Help system to support a Windows application that will be installed on a user's PC. You would like to provide your users with access to the latest available Help information, such as just discovered workarounds for minor software bugs.

A typical approach in this scenario is to build into the application Help menu a number of Help choices. For example, Microsoft often includes an Office on the Web or similar option on the Help menu to link to the application's support Web site (see screen capture below left). As another example, Jasc Paint Shop Pro has a range of Web-based support options (see screen capture below right).

This approach tends to make the Help less contiguous; the Paint Shop Pro support information that the user is looking for could be in the Help file, could be at the Support Center, or could be on the Jasc Software web site. A different approach might be to present the Help file as the repository for all support information. Let's look at how we might accomplish this.

External HTML Help TOC Nodes

Sample HTML Help TOC When you build a typical HTML Help CHM file with a typical Help Authoring Tool (HAT), the tool creates the Table of Contents (TOC) tree structure based on the topics that make up the Help system.

The default book and page icons can be changed to alternatives, although some HATs make it difficult to change the default settings. There are actually 42 icons in the standard HTML Help "icon strip" that can be used in the TOC (see the icon strip below). You can even create your own alternative icon strip if you want something special, although custom icon strips do not work with a binary TOC. To find out more about icon strips, search for icon strips in the HTML Help Workshop Help, or read more at the MSDN site.

Usually, the books and pages look, or the folders and files look, are used for HTML Help topics. To indicate a recently modified topic, a starburst icon is not uncommonly used.

More important to us, though, is the ability for a TOC node to reference an external URL, rather than an included topic. Again, some HATs make it a little difficult to add these external TOC nodes, but most do support the feature. (Consult your HAT's Help file to find out exactly how. Search for "external" or "URL" or "Internet access".) Alternatively, you can use the HTML Help Workshop, which makes the feature very easy to access from the Contents pane.

If you know how to add an external URL node to your TOC, you should hide the following few paragraphs and skip to Integrating.

In HTML Help Workshop, open the HHC file you want to add the external node to, and click the Insert A Page button . In the Table of Contents Entry dialog box, type the name that will appear in the TOC (e.g., WinWriters Web Site), and then add the URL by clicking the Add... button and typing the full URL (e.g., http://www.winwriters.com/) and clicking OK.

Table of Contents Entry dialog box

Now, select the Advanced tab, and change the icon for this TOC entry to something that reflects the Web (e.g., ), by cycling through the Image index. Click OK to complete the process, and you will have achieved the objective of adding an external TOC node.

Table of Contents Entry dialog box

To recap, we have now seen how we can add links to Web content in our local CHM's Table of Contents, thus providing the ability to pull all our support resources, online and local, into the one location.

Integrating

On closer examination, the external TOC nodes concept is a simple way of drawing Web content into a CHM environment. Similarly, we can use absolute URL hotspots within our CHM topics to link to Web pages. For example, a link to http://www.mycompany.com/goodapp/support/custfield.htm will function perfectly well within the HTML Help engine (HH.EXE). You should think of HH.EXE as a "cut-down" version of Internet Explorer. Most things that IE can display, HH can display.

So practically speaking, there's nothing to stop us from structuring a particular See Also list of links as in the following example:

Sample See Also List

Local links (links to topics in our HTML Help project) will be generated as relative links using HTML Help's mk:@MSITStore protocol. External links will be generated as absolute links using standard HTTP protocol.

Although we could technically structure our content like this, it isn't generally going to be practical. Nonetheless, it is important to understand there is no technical reason why we can't integrate local and Web content seamlessly. (Oh... there is one technical issue. If the user is not connected when he or she reads the Help, and then unwittingly follows a link to a Web URL, the dreaded Error 404 page will display. Not what we want to feature in our Help! So fully integrating local and Web content will only run seamlessly in an always connected environment. Oh... wait, there's another technical issue. Any external content will not be included in the CHM's text search or index.)

Getting Clever

Having established there are (almost) no technical impediments to integrating Web and local content within a CHM file, we can take the opportunity to do some clever things. For starters, wouldn't it be really nice if users could work out whether their CHM file was the most recent release? Or, if there was important new information you wanted readers to be aware of, wouldn't it be great if a flashing "new info" notice appeared on every page until the update had been read? Let's see how we could make this happen!

Current Release Information

Add a new external URL node on your Help system's TOC. Let's say the URL is http://www.myapp.com/support/latesthelp.htm. We will give the node a title of Latest Help Updates. The latesthelp.htm file, located on the Web server, could contain some simple information such as:

	The latest Help version available is:	15NOV02
	Download the latest version now.

This information might be useful, but it doesn't tell the user what Help version he or she has. Using a bit of JavaScript, we can solve this problem. Firstly, we must change the link to latesthelp.htm slightly. We need to add a query string (or parameter) to the URL used on the TOC, so that it reads: http://www.myapp.com/support/latesthelp.htm?ver=11APR02

The user won't notice this, of course, as the URL is "underneath" the Latest Help Updates node title. We will have to modify change this link every time we release a new version of our Help file. Now, we need to add some JavaScript to our latesthelp.htm file so that it displays all but the first five characters (?ver=). The JavaScript will be:

<script language="JavaScript1.2" type="text/javascript">
<!-- //
   document.write(location.search.substring(5));
//-->
</script>

and we place it adjacent to a new line describing the user's Help version. So the text the user sees on latesthelp.htm will now be:

	Your current Help version available is:	11APR02
	The latest Help version available is:	15NOV02
	Download the latest version now.

If you have plenty of time, you could embellish the JavaScript so that the Download the latest version now line did not display if the user had the most recent release.

New Information Notice

We've just seen how some JavaScript provided a neat solution to being able to display the user's Help version. This will work if the user thinks to go to the Latest Help Updates node on the TOC. (How many users think? I hear you ask!) We can use some similar clever ideas to be a little more proactive.

The result we want to accomplish is this... when a user opens the CHM file, and there has been a new update released in the last four weeks, some sort of alert flashes on every page of the CHM file.

The first thing we have to do is add a little line to the top of every topic indicating that we wish to use an external JavaScript file. This will be easy to do in some HATs, but more difficult in others. Essentially, we need to add the following line in the <head> section of every topic:

<script language="JavaScript1.2" type="text/javascript"
   src="http://www.myapp.com/support/jscheck.js"></script>

If you are familiar with HTML and JavaScript, you will recognize this method as a common technique for storing JavaScript routines in a separate file, and "including" them when they're needed. Our CHM file is therefore going to try to include the JavaScript file. Fortunately for us, if the user is not connected, we won't get an error message. (That's lucky!)

That's the easy part. The difficult part is to write a JavaScript routine that will display some sort of alert. Being a proponent of the R&D philosophy (where R&D stands for Rip-off and Duplicate), I found a free script by Stefano Occhetti on a site called The JavaScript Source, and modified it to make it suitable. The original script created the effect of a blowfly GIF following the mouse cursor around. Yes, a blowfly. Fearing user backlash, I changed this to an image of a butterfly, but you might want to replace the image with something that suits your purposes. I suggest an image of the words "Help Updates Available!": I also added a link from the image to the latesthelp.htm page.

The JavaScript routine is quite lengthy, but fortunately you don't need to understand it. You just have to copy it and save it into a file called jscheck.js, and then replace any references to www.myapp.com in the code to your own Web server.

------------------------------------------------
/*
	Original:	Stefano Occhetti
	E-mail:	starnuto_di_topo@hotmil.com
	Web Site:	http://www.geocities.com/starnuto_di_topo_2001
/*
var ns = (document.layers)?1:0;
/*
Button:
	this code is to show a "button" to switch
	the fly ON/OFF.
	It is always shown on the frame's
	bottom-right corner.
------------------------------------------------
*/
var imgwidth=40;	// Image width
var imgheight=40;	// Image height

var button = Array();	// to pre-cache images
button[0]=new Image();
button[0].src="http://www.myapp.com/support/Mosca_OFF.gif";
button[1]=new Image();
button[1].src="http://www.myapp.com/support/Mosca_ON.gif";

var text="<table width=10 bgcolor=#ffffff><td><a href='javascript:showhideAnimation()'><center><img name='Button' src='"+button[0].src+"' width='"+imgwidth+"' height='"+imgheight+"' border='0'></center></a></font></td></table>"	// A bit of HTML code to display the button

//Initialize some variables to make the button always to appear on the frame's bottom-right corner
if (ns) {
	document.write("<LAYER NAME='FlyOnOff' LEFT=0 TOP=0>"+text+"</LAYER>");
	horz=".left";
	vert=".top";
	docStyle="document.";
	styleDoc="";
	innerW="window.innerWidth";
	innerH="window.innerHeight";
	offsetX="window.pageXOffset";
	offsetY="window.pageYOffset";
}else {
	document.write("<div id='FlyOnOff' style='position:absolute; visibility:show; left:235px; top:-50px; z-index:2'>"+text+"</div>");
	horz=".pixelLeft";
	vert=".pixelTop";
	docStyle="";
	styleDoc=".style";
	innerW="document.body.clientWidth";
	innerH="document.body.clientHeight";
	offsetX="document.body.scrollLeft";
	offsetY="document.body.scrollTop";
}

// Moves the button in the right position
function checkLocation() {
	objectXY="FlyOnOff";
	var availableX=eval(innerW);
	var availableY=eval(innerH);
	var currentX=eval(offsetX);
	var currentY=eval(offsetY);
	x=availableX-(imgwidth+30)+currentX;
	y=availableY-(imgheight+20)+currentY;
	eval(docStyle + objectXY + styleDoc + horz + "=" + x);
	eval(docStyle + objectXY + styleDoc + vert + "=" + y);
}

setInterval('checkLocation()', 10);

/*
end of Button management
------------------------------------------------
*/

/*
Fly:
	this code provides some facilities
	to show a fly moving on the screen.

The fly does not actually follow the
	mouse, but a "Dot" (not shown!).
------------------------------------------------
*/

(document.layers)?window.captureEvents(Event.MOUSEMOVE):0;
(document.layers)?window.onMouseMove=getMousePosition:document.onmousemove=getMousePosition;

var Dot_Ro=60;	//Dot's distance from the mouse pointer
var Dot_Theta=0;	//Dot's initial angle
var Dot_Speed;	//Dot's absolute Angular speed
var Dot_Direction=1; //Dot's direction (1=clockwise)
var Dot_x=0;	//Dot's original position
var Dot_y=0;

var alpha;	//Angle from the fly to the mouse
var mult;	//Ausiliary variable to define the angle

var picX = 20;	//Fly's coords.
var picY = 100;
var mouseX = 0;	//Mouse coords.
var mouseY = 0;
var step = 10;	//Pixels
var speed = 100;//u-seconds

// Dir specifies the right picture;
// img pre-caches images.
var dir = Array();
dir[-4]="Mosca_3.gif";
dir[-1]="Mosca_6.gif";
dir[-2]="Mosca_5.gif";
dir[-3]="Mosca_4.gif";
dir[3]="Mosca_8.gif";
dir[4]="Mosca_7.gif";
dir[1]="Mosca_2.gif";
dir[2]="Mosca_1.gif";
dir[0]="";

var img = Array();
for (var i=-4; i<5; i++){
	img[i]=new Image();
	img[i].src="http://www.myapp.com/support/"+dir[i];
}

// Some HTML code to show the fly.
if (ns) {
	document.write("<LAYER NAME='FlyDiv' LEFT=0 TOP=0><a href="latesthelp.htm"><img src="+img[1].src+" name='pic'></a></LAYER>");
}else {
	document.write("<div id='FlyDiv' style='position:absolute'>");
	document.write("<img name='pic' src=" + img[1].src + "></div>");
}

// Shows the proper image for the fly.
function display(direction) { //direction must be from -4 to 4, but not 0.
	if (ns) {
		document.pic.src = img[direction].src;
	}else{
		pic.src = img[direction].src;
	}
}

function getMousePosition(e) {
	mouseY=(ns)?e.pageY:window.event.y + document.body.scrollTop;
	mouseX=(ns)?e.pageX:window.event.x + document.body.scrollLeft;
}

//Calculate new position
function calcNewPos() {
	/*
		All this calculations make the Dot
		to come near the mouse-pointer,
		and the fly to follow the dot.
	*/
	var dist=Math.sqrt(Math.pow(mouseY-picY,2) + Math.pow(mouseX-picX,2));
	Dot_Speed=Math.PI/15;
	Dot_Theta+=Dot_Direction*Dot_Speed;
	Dot_x=mouseX+Dot_Ro*Math.cos(Dot_Theta);
	Dot_y=mouseY+Dot_Ro*Math.sin(Dot_Theta);
	var arg = (Dot_y-picY) / (Dot_x-picX);
	mult = (Dot_x - picX < 0)? mult = -1:1;
	alpha = Math.atan(arg);
	var dx = mult * step * Math.cos(alpha);
	var dy = mult * step * Math.sin(alpha);
	picX += dx;
	picY += dy;
}

//Shows or hides the fly when the "button" is pressed
function showhideAnimation() {
	if (ns) {
		document.layers['FlyDiv'].visibility=document.layers['FlyDiv'].visibility=="hide"?"show":"hide";
		document.Button.src = document.layers['FlyDiv'].visibility=="hide"?button[1].src:button[0].src;
	}else {
		FlyDiv.style.visibility=="hidden"?FlyDiv.style.visibility = "visible":FlyDiv.style.visibility = "hidden";
		Button.src = FlyDiv.style.visibility=="hidden"?button[1].src:button[0].src;
	}
}

// Moves the fly around the screen
function moveFly() {
	// moves the fly in a new position...
	calcNewPos();
	if (ns) {
		document.layers['FlyDiv'].left = picX;
		document.layers['FlyDiv'].top = picY;
	}else{
		FlyDiv.style.left = picX - pic.width / 2;
		FlyDiv.style.top = picY - pic.height / 2;
	}

// ... and changes the image.
	alpha=-180*alpha/Math.PI;
	alpha+=22.5;
	var OK=0;
	for(var i=0; (i<4)&& !OK; i++){
		if (alpha<-Math.PI+45*i){
			display(mult*(i+1));
			OK=1;
		}
	}
}

// Changes Dot's turning direction
function ChangeDotDirection() {
	Dot_Direction=-Dot_Direction;
	Dot_Theta+=Math.PI;
}

//Go!
setInterval('moveFly()', speed);
setInterval('ChangeDotDirection()', speed*50);

/*
The end.
------------------------------------------------
*/

The last thing to do is to create your images, and upload them along with jscheck.js to your Web server. The original script uses eight different images to animate the effect, but if you don't need animation, just reference the same picture eight times. The images are expected to be named mosca_1.gif through to mosca_8.gif. Two additional images (mosca_OFF.gif and mosca_ON.gif) are used in a feature that will appear at the bottom of each page, allowing the user to turn the images on and off (usually off!).

This explanation will more easily be understood if you take a look at it in action. Although it is difficult to click the butterfly, it is possible!

By removing, renaming, or changing the jscheck.js file on the Web server, we can effectively turn on and turn off the feature. When the jscheck.js file is in place, the effect will appear (when the user is connected). When the file is not in place, the effect will not appear.

A Much Simpler Method

The butterfly effect is amusing, but not professional enough for many purposes. You may also felt a chill when you noted that the above script involved 10 images and a scary JavaScript file, which you had to modify! If so, calm down and take a big breath. Any JavaScript that adds any sort of visible effect will work under the same concept. For example, you could more simply (do you like that word?) include an image on your page which has its display style setting set to none. (The display style setting is a Dynamic HTML feature. It is set as in the example <img src="a.gif" id="pic" style="display:none">.) Our JavaScript could simply change the display setting of the image to on. In other words, If the script file is available, the image will display. Let's simulate that idea now. There is an image immediately below this paragraph, with its display setting turned off.

For our simulation, we will embed some JavaScript in a link. When the link is executed (which simulates the script file being available), the display setting of the left image is set on. To try again, click reset.

The jscheck.js file in this case would simply comprise one line! Namely:

document.all['pic'].style.display='';

Further Refinement

The above ideas work on the basis that a "flag" (be it butterflies, blowflies, or notices) will display when a new version becomes available, and displays for a period of time (say, two weeks). This may cause some annoyance for a user who downloads the updated version on the first day of the "flag," but continues to see the Updates Available flag for the next 13 days! A better system would be to set a cookie when the user chooses to download the update, and also make the display of the Updates Available flag conditional on that cookie not being found on the user's system. (We would have to be careful that we set the cookie from a web page, not a CHM topic, as cookie setting is unreliable from CHM files.)

You may also think of some other applications for the idea of using external files to enhance CHM files. As well as JavaScript files, external Cascading Style Sheet files and XML data files can also be referenced from within the HTML markup. Maybe a current price list, drawn from an external XML data file, could be included within the Help? Perhaps that will form the basis of another WinWriters article!

Onwards

Let's summarize what we've covered.

An HTML Help (CHM) file's Table of Contents can include nodes that link to web-based topics.
The icon used in the TOC for web-based topics can be set to differentiate online topics from local topics.
Hyperlinks can easily be set from local CHM hotspots to Web-based topics.
A link from within a CHM file to a web page can pass a simple parameter, which permits the Help file to pass information to JavaScript within a web page. This facility could be used to let users identify whether they have the latest version of the Help.
By using external JavaScript files, you can create some useful features, such as an Updates Available "flag."
You will have to check if your HAT easily allows you to incorporate external TOC nodes and JavaScript coding.

If you think some of these features could be applicable to your projects, start experimenting with and expanding these ideas! Help technologies are proving to be extensible, and, as the famous philosopher Anon. once said, "you are only limited by your imagination."

Based in Australia, Tony Self is recognised as one of the pioneers of hypertext and online documents. For 15 years, Tony has worked in the areas of online help systems, computer-based training, and electronic documents. In 1993, Tony founded HyperWrite, a business and technical documentation company specialising in hypertext. In 1998, HyperWrite founded the Australasian Online Documentation Conference, an annual event attracting specialists from Australia and New Zealand. Tony served as Chief Technology Officer for Asia-Inc.com in 2000, where he was responsible for an innovative Asian business information Web and WAP service. Tony has now returned to HyperWrite, where he consults to organisations on online documentation and Internet strategy.