dAlchemy | A standards-compliant in-line glossary technique for XHTML

210 W 21st #1RW
New York, NY 10011

A Standards-compliant In-line Glossary Technique for XHTML

The following documents a technique for adding an in-line glossary pop-up feature to XHTML pages. Its principle advantage is that the technique has been tested and works with many current browsers:

Internet Explorer 5.x (Windows and Macintosh)
Internet Explorer 6.x (Windows)
Netscape 6.x
Mozilla 1.x (Windows and Macintosh, *nix and probably any other browser that uses the Gecko engine)
Opera 6 (Windows and Macintosh, and any other platform that uses the same rendering engine)

The technique also conforms to Web standards, so when it doesn't work right for somebody, you can blame them for poor choice of browser without feeling too guilty. Caveat: there's no telling how this technique will hold up in the future as browsers continue to evolve.

The example

For an example of what this technique can look like, simply place your mouse cursor over this term: quality assurance. With this technique, you can accomplish similar results for any number of words on an XHTML page. For an example of a Web publication that uses this technique extensively, go here and navigate to the second page.

The term

The whole point of this glossary technique is that the definitions can be an inline feature throughout body text. Therefore, we use <span> to tag the term in question.

The class maps to the style sheet so the term has some distinctive appearance for the user so they know they can mouse over it.

The onmouseover and onmouseout parameters call the show and hide functions, passing an id that uniquely maps to the definition's <div> (see below).

<span class="glossaryTerm" onmouseover="javascript:showDiv('QualityAssurance')" onmouseout="javascript:hideDiv('QualityAssurance')">Quality Assurance</span>

The definition (popup "window")

The definition that will "pop up" goes in a <div>. I just group them all at the bottom of the page, but it shouldn't matter much where you put them.

The important part is the id, which associates the definition with mouseover events of the corresponding term.

<!-- glossary -->
<div class="glossaryPopup" id="QualityAssurance">
	<p><strong>Quality Assurance</strong></p>
	<p>A systematic process, usually executed in parallel with programming, for verifying that software meets specifications and for insuring bugs are fixed or otherwise resolved.</p>
</div>

The javascript

This code goes in the document <head>. Most of it is lifted verbatim from some excellent browser compatibility research by Peter-Paul Koch.

The critical code here is the two sets of if/else conditions. These are acquiring the necessary parameters from different browsers that behave idiosyncratically. I won't attempt to repeat Koch's research results here: for whole story, read his article.

	<script type="text/javascript">

	// function for poking a new property value into a DOM element;
	// used here to toggle the visibility of the floating definition "window"
	function setIdProperty( id, property, value )
	{
		var styleObject = document.getElementById( id );
		if (styleObject != null)
		{
			styleObject = styleObject.style;
			styleObject[ property ] = value;
		}
	}

	var timeoutID;

	// function triggered by glossary term mouseover events does the core
	// work of positioning the definition "window" for the particular browser
	// in use and enables its visibility
	function showDiv( domId )
	{
		var theWidth = 0
		var theHeight = 0
		var yOffset = 0
		
		// Try to get the yoffset...
		if (window.pageYOffset)
		{
			yOffset = window.pageYOffset
		}
		else if (document.documentElement && document.documentElement.scrollTop)
		{
			yOffset = document.documentElement.scrollTop
		}
		else if (document.body)
		{
			yOffset = document.body.scrollTop
		}
		
		// Try to get the "inner width" and "inner height"
		if (window.innerWidth)
		{
			theWidth = window.innerWidth
			theHeight = window.innerHeight
		}
		else if (document.documentElement && document.documentElement.clientWidth)
		{
			theWidth = document.documentElement.clientWidth
			theHeight = document.documentElement.clientHeight
		}
		else if (document.body)
		{
			theWidth = document.body.clientWidth
			theHeight = document.body.clientHeight
		}
		
		var left = (theWidth-500)/2 + "px"
		var top = (theHeight-200)/2 + yOffset + "px"
		
		setIdProperty( domId, "left", left )
		setIdProperty( domId, "top", top )	
		
		// timeout delay
		timeoutID = window.setTimeout( 'setIdProperty( "'+ domId + '", "visibility", "visible" );', 500 );
	}

	// handles hiding the definition "window" when the mouse moves off the term
	function hideDiv( domId )
	{
	
		// cancel the dely on the show code
		window.clearTimeout(timeoutID);
		
		setIdProperty( domId, "visibility", "hidden" );
	}

	</script>

The style sheet

Without a style sheet, this technique simply doesn't work very well. You can either put this in the <head> or you can link to it in an external file.

There isn't much to it, actually. The critical bits are that the popup <div> be hidden by default and use absolute positioning.

	.glossaryPopup {
		position: absolute;
		background: #FFF5BD;
		border: 2px solid #D5B500;
		padding: 15px;
		width:500px;
		visibility:hidden;
		z-index: 100;	
	}
	
	.glossaryTerm {
		border-bottom: 2px dotted orange;
		background-color: #FFFFBF;
		cursor: help;

Quality Assurance

A systematic process, usually executed in parallel with programming, for verifying that software meets specifications and for insuring bugs are fixed or otherwise resolved.