Detailed instructions for mouseovers

By Tim Green
April 6, 2006

Original article link

Creating mouseover images in your HTML code is a bit daunting at first. Although there are other tutorials that cover the subject a couple of people have asked me to post these instructions as well, which started life as an answer to a question in the Help & Manual 4 Forum. The code here is universal -- you can use it in any version of Help & Manual.

Introduction: How Mouseover Links Work

Basically, a mouseover link is just a normal hyperlink using an image instead of text as the visible part of the link. However, it includes some JavaScript code that switches the image in response to mouse pointer actions. Most mouseover links have two versions of the image: One for the normal state and one for the "mouseover" state, when the mouse pointer is over the image (normally a highlighted version of the original image). If you want to get fancy you can also use a third image that is displayed when the user clicks with the mouse -- for example if you're using 3D buttons this could be an image of the button in a depressed state (poor button), which is a nice effect.

It works like this: You give the standard version of the image a unique name (in addition to its file name), which must not appear anywhere else on the current page. Let's say we call it "Image_A". The command in the JavaScript code effectively says, "When the mouse is over the image called Image_A display button_h.gif instead of the original image file referenced for this button." There are similar commands for what to do when the mouse is moved away again and what to do when the user clicks.

You can see how it works in the mouseover code for the standard navigation buttons used in some of Help & Manual's HTML templates. Here is the code for the link to the default topic:

Code:

<a
href="<%HREF_PARENT_CHAPTER%>"
onmouseover="document.images.main.src='btn_home_h.gif'"
onmouseout="document.images.main.src='btn_home_n.gif'"
>
<img name="main" src="btn_home_n.gif" border="0" alt="Return to chapter overview">
</a>

Here you have two images: btn_home_h.gif is the "highlighted" version and btn_home_n.gif is the "normal" version.

The main image that is visible on the page when no mouse action is performed is displayed with this line:

It has been given the unique name main that can only be used once on the entire page (i.e. the entire template in this case).

The "mouseover magic" is performed by the following code inside the opening <a> link:

<a
href="<%HREF_PARENT_CHAPTER%>"
onmouseover="document.images.main.src='btn_home_h.gif'"
onmouseout="document.images.main.src='btn_home_n.gif'"
>

The target of the link is defined by the href= attribute. In the example this is an H&M variable, but you will often want to use the address of a specific topic page:

href="<%HREF_PARENT_CHAPTER%>"

href="topicid.htm"

The onmouseover and onmouseout commands reference the "main" name and tell the browser to replace this image with another image when the mouse pointer is moved over the image and off the image. This is done with the reference "document.images.main.src".

All this code is placed inside the definition for the hyperlink, which is between the opening <a tag and the closing > tag, which I have placed on single lines in the code box further above for more clarity. This is then followed by the tag that displays the original image for the link, which we already discussed above:

And everything is closed with the closing </a> tag to complete the link:

</a>

Putting it all together:

Step 1 -- Preparing the graphics:

Now let's see how this works with an ordinary image. Let's say you want to create a button that links to a syntax reference page, so we're going to call it "syntax". The first thing you need to to do is fire up your favorite graphics program and make at least two versions of the button, one for the normal state and one for the mouseover state. If you want you can also make a third version for the click state. All the versions must have exactly the same dimensions, of course! Name the files as follows (we're using GIFs but you can use JPGs or PNGs if you prefer):

syntax_n.gif

syntax_h.gif

syntax_c.gif

Next you need to include make the images available to H&M so that it can use them when you compile your output. How you do this depends on whether you are using Help & Manual 3 or 4:

Help & Manual 4:

In H&M4 it's easy. Just go to Project Properties - Common Properties - Baggage Files and add the two or three button graphics to the Baggage. They will then automatically be made available to all relevant output formats (they are physically stored inside your project file).Help & Manual 3:

Project Properties - HTML Help Export - Extended .HHP Settings

Code:

[FILES]
..\syntax_n.gif
..\syntax_h.gif
..\syntax_c.gif

This takes care of the button graphics files for HTML Help. (The "..\" tells H&M3 to look in the project folder, which is always one folder up from the temporary folder in which HTML Help is compiled.) If you are also using the mouseover in Browser-based HTML in H&M3 you must manually copy the button graphics files to your HTML output folder, H&M3 will not do this for you. (In H&M4 this is taken care of by the Baggage files.)

Step 2 -- Entering the Code:

Next you can open the HTML template and enter the code for the mouseover link in the place where you want it to appear. In H&M4 go to Project Properties - HTML Help - Topic Pages and select "Let me edit HTML code directly" to display the template editor (you can also access the Topic Pages in the Browser-based HTML section, it's the same templates.) In H&M3 go to Project Properties - HTML Export Layout - Topic Pages and select "Edit HTML template directly" in the Design Mode field at the top of the dialog.

First enter the tag that displays the main version of the image (syntax_n.gif), which will look like this in our example:

Code:

The "name" attribute is essential for the mouseover functionality. You can use any name you like as long as it's unique -- we're using "syntax" in this example. The "alt" attribute displays a mouseover text when the mouse pointer is over the image.

Next we enclose the image in a link tag containing the mouseover code:

Code:

The onmousedown line is optional and only necessary if you have made a third version of the graphic for the depressed state. I've divided everything up into single lines to make it clearer here, but in your own code you could format it like this:

Code:

Now we need to go through the individual lines, every single little detail is crucial, so study this carefully:

<a href="topicid.htm"
This defines the target of the link. You put this together from the Topic ID of the target topic, all in lower case letters, + ".htm". Remember to place quotes around the target, exactly as shown in the example.

onmouseover="document.images.syntax.src='syntax_h.gif'"
onmousedown="document.images.syntax.src='syntax_c.gif'"
onmouseout="document.images.syntax.src='syntax_n.gif'"
>
This defines the mouseover behavior. The most important part is the reference to the unique image name (syntax), which must be different for every mouseover link you create and which must match the name of the main image. The "onmouseout" line is necessary to restore the original image when the user moves the mouse away from it.

Important: Note that the entire argument of each mouse command is enclosed in double quotes and the image name is enclosed in single quotes. This is absolutely essential, you must do it exactly as shown here.

<img name="syntax" src="syntax_n.gif" border="0" alt="Syntax Reference">
</a>
This is just the image reference we created at the beginning and the closing </a> tag to terminate the link.

That's basically it. You need to repeat this entire procedure with a unique name for the main image and references to that name in the code (as shown) for every single mouseover image link you want to create. Cool

Tim Green is an experienced help author and translator. He wrote the online help of Help & Manual and is the site admin of the H&M user forum. You can reach him through his private web site http://www.it-authoring.com