JavaScript API

Download Zip Now

WARNING: This is a very old API and is only kept here for historical purposes. If you are looking for a robust API to make javascript coding easier I recommend you check out prototype or jQuery

Introduction

This is a simple API (Application Programming Interface) for creating dHTML pages.

There’s nothing even remotely new here, but I use this code in many of the other scripts on the site so I thought I’d explain how it works.

The API provides the following functionality:

• Basic Browser Sniffing - Not a complete browser sniffer, it only highlights those browsers that can cause problems for the API.
• Get Style Object - Returns the Style object for a given page element.
• Change Object Visibility - Hides or shows an element.
• Find Image (NS4 only) - Used to find image objects in NS4.
• Find object (NS4 only) - Used to find other objects in NS4.
• Get Element Width/Height - Gets the width or height of any page element (not images in NS4).
• Get Element Top/Left - Get the page co-ordinates of any element (not images in NS4).
• Get Image width/Height - Gets the width or height of any image.
• Get Image Top/Left - Get the page co-ordinates of any image.
• Move Element - Sets the x and y co-ordinates of an element.
• Change Style Class - changes the style class of an object (Not NS4 or Opera 5/6).
• Change Image - changes the source of an image element.
• Change Background Colour - changes the background colour of an element.

In these pages I’ll refer to the three types of browsers. These are the DOM Browsers (MSIE 6+, Netscape 6+, Mozilla, Opera 7+, Konqueror etc), Internet Explorer 4/5 and Netscape 4.x.

The DOM browsers use document.getElementById to reference object, Internet Explorer usesdocument.all, Netscape 4.x uses document.layers.

Most of the functions in the API have three sections, one for each of the three browser types.

Browser Sniffer - sniffBrowser()

This function is used to sniff out problem browsers. The ones we need to know about are:

• Netscape Navigator 4.x (ns4): The most important test – NS4 does almost everything differently to the other browsers.
• Opera 5 (op5): Opera 5 lacks some of the functions that other browsers have. These include not being able to change an elements background colour and style class. Opera 5 also chokes when sizes and co-ordinates are set using the “px” suffix.
• Opera 6 (op6): Opera 6 only lacks the ability to change an elements style class.
• MSIE on the Mac (mac_ie): The problem with MSIE on the Mac is when you try to get the top co-ordinate of a table cell element. It incorrectly returns the top co-ordinate of the table element, not the table cell. To get round this, you have to base positioning on table row elements instead. Konqueror on Linux seems to have the opposite problem which adds to the fun.

The Code

function sniffBrowsers() {
	var ns4 = document.layers;
	var op5 = (navigator.userAgent.indexOf("Opera 5")!=-1)
		||(navigator.userAgent.indexOf("Opera/5")!=-1);
	var op6 = (navigator.userAgent.indexOf("Opera 6")!=-1)
		||(navigator.userAgent.indexOf("Opera/6")!=-1);
	var agt=navigator.userAgent.toLowerCase();
	var mac = (agt.indexOf("mac")!=-1);
	var ie = (agt.indexOf("msie") != -1);
	var mac_ie = mac && ie;
}

Get Style Object - getStyleObject()

This function is lifted pretty much straight from Apple developer site (the copyright message allows it’s use in other sites). This version will handle nested layers however.

The function returns the style object for the threetypes of browsers.

The Code

function getStyleObject(objectId) {
	if(document.getElementById && document.getElementById(objectId)) {
		return document.getElementById(objectId).style;
	} else if (document.all && document.all(objectId)) {
		return document.all(objectId).style;
	} else if (document.layers && document.layers[objectId]) {
		return getObjNN4(document,objectId);
	} else {
		return false;
	}
}

Change Object Visibility - changeObjectVisibility()

This function is also from Apple developer site (the copyright message allows it’s use in other sites).

The function hides or shows a page element.

The Code

function changeObjectVisibility(objectId, newVisibility) {
    var styleObject = getStyleObject(objectId, document);
    if(styleObject) {
	styleObject.visibility = newVisibility;
	return true;
    } else {
	return false;
    }
}

Example Usage

// show an element
changeObjectVisibility('myObjectId', 'visible');

// hide an element
changeObjectVisibility('myObjectId', 'hidden');

 

Find Image (NS4) - getImage()

This function is also from Apple developer site (the copyright message allows it’s use in other sites).

The function getImage returns the object for “name”.

The Code

function findImage(name, doc) {
	var i, img;
	for (i = 0; i < doc.images.length; i++) {
    	if (doc.images[i].name == name) {
			return doc.images[i];
		}
	}
	for (i = 0; i < doc.layers.length; i++) {
    	if ((img = findImage(name, doc.layers[i].document)) != null) {
			img.container = doc.layers[i];
			return img;
    	}
	}
	return null;
}

function getImage(name) {
	if (document.layers) {
    	return findImage(name, document);
	}
	return null;
}

Example Usage

// get object for image with ID "myImage"
var myObject = getImage('myImage');

Find Object (NS4) - getObjNN4()

This function is also from Apple developer site (the copyright message allows it’s use in other sites).

The function getObjNN4(obj,name) returns the object for “name”. It starts the search in “obj”

This function is needed to find nested elements in a page.

The Code

function getObjNN4(obj,name)
{
	var x = obj.layers;
	var foundLayer;
	for (var i=0;i<x.length;i++)
	{
		if (x[i].id == name)
		 	foundLayer = x[i];
		else if (x[i].layers.length)
			var tmp = getObjNN4(x[i],name);
		if (tmp) foundLayer = tmp;
	}
	return foundLayer;
}

Example Usage

// get object for image with ID "objectId", searches the whole document
getObjNN4(document,'objectId');

Get Element Width/Height - getElementHeight() & getElementWidth()

The functions return the width or height of an object.

NOTE: This code will not work for images in Netscape 4.x. Use getImageWidth and getImageHeight instead.

The Code

function getElementHeight(Elem) {
	if (ns4) {
		var elem = getObjNN4(document, Elem);
		return elem.clip.height;
	} else {
		if(document.getElementById) {
			var elem = document.getElementById(Elem);
		} else if (document.all){
			var elem = document.all[Elem];
		}
		if (op5) {
			xPos = elem.style.pixelHeight;
		} else {
			xPos = elem.offsetHeight;
		}
		return xPos;
	}
}

function getElementWidth(Elem) {
	if (ns4) {
		var elem = getObjNN4(document, Elem);
		return elem.clip.width;
	} else {
		if(document.getElementById) {
			var elem = document.getElementById(Elem);
		} else if (document.all){
			var elem = document.all[Elem];
		}
		if (op5) {
			xPos = elem.style.pixelWidth;
		} else {
			xPos = elem.offsetWidth;
		}
		return xPos;
	}
}

Get Element Left/Top - getElementLeft() & getElementTop()

The functions return the x or y co-ordinate of an element.

NOTE: This code will not work for images in Netscape 4.x. Use getImageTop and getImageLeft instead.

The Code

function getElementLeft(Elem) {
	if (ns4) {
		var elem = getObjNN4(document, Elem);
		return elem.pageX;
	} else {
		var elem;
		if(document.getElementById) {
			var elem = document.getElementById(Elem);
		} else if (document.all){
			var elem = document.all[Elem];
		}
		xPos = elem.offsetLeft;
		tempEl = elem.offsetParent;
  		while (tempEl != null) {
  			xPos += tempEl.offsetLeft;
	  		tempEl = tempEl.offsetParent;
  		}
		return xPos;
	}
}

function getElementTop(Elem) {
	if (ns4) {
		var elem = getObjNN4(document, Elem);
		return elem.pageY;
	} else {
		if(document.getElementById) {
			var elem = document.getElementById(Elem);
		} else if (document.all) {
			var elem = document.all[Elem];
		}
		yPos = elem.offsetTop;
		tempEl = elem.offsetParent;
		while (tempEl != null) {
  			yPos += tempEl.offsetTop;
	  		tempEl = tempEl.offsetParent;
  		}
		return yPos;
	}
}

Get Image Width/Height - getImageWidth() & getImageHeight()

The functions return the width or height of an image.

NOTE: All the browsers except Netscape 4.x just call getElementWidth(myImage) or getElementHeight(myImage) to get the width or height.

The Code

function getImageWidth(myImage) {
	var x, obj;
	if (document.layers) {
		var img = getImage(myImage);
		return img.width;
	} else {
		return getElementWidth(myImage);
	}
	return -1;
}

function getImageHeight(myImage) {
	var y, obj;
	if (document.layers) {
		var img = getImage(myImage);
		return img.height;
	} else {
		return getElementHeight(myImage);
	}
	return -1;
}

Get Image Left/Top - getImageTop() & getImageLeft()

The functions return the x or y co-ordinate of an image.

NOTE: All the browsers except Netscape 4.x just call getElementLeft(myImage) or getElementTop(myImage) to get the x or y co-ordinates.

The Code

function getImageTop(myImage) {
	var y, obj;
	if (document.layers) {
		var img = getImage(myImage);
		if (img.container != null)
			return img.container.pageY + img.y;
		else
			return img.y;
	} else {
		return getElementTop(myImage);
	}
	return -1;
}

function getImageLeft(myImage) {
	var x, obj;
	if (document.layers) {
		var img = getImage(myImage);
    	if (img.container != null)
			return img.container.pageX + img.x;
		else
			return img.x;
  	} else {
		return getElementLeft(myImage);
	}
	return -1;
}

Move Page Element - moveXY()

Move the element “myObject” to screen co-ordinates x, y.

NOTE: All browsers except Opera 5 use the “px” suffix. Otherwise, when the doctype of your document is specified as HTML4.0 in the DOM browsers, the function will not work.

The Code

function moveXY(myObject, x, y) {
	obj = getStyleObject(myObject);
	if (ns4) {
		obj.top = y;
 		obj.left = x;
	} else {
		if (op5) {
			obj.pixelTop = y;
 			obj.pixelLeft = x;
		} else {
			obj.top = y + 'px';
 			obj.left = x + 'px';
		}
	}
}

Change Style Class - changeClass()

Changes the Style Class of “Elem” to “myClass”.

NOTE: This function will not work in Opera 5 or 6, or Netscape 4.x.

There is a NS4 workaround at WebReference.com.

The Code

function changeClass(Elem, myClass) {
	var elem;
	if(document.getElementById) {
		var elem = document.getElementById(Elem);
	} else if (document.all){
		var elem = document.all[Elem];
	}
	elem.className = myClass;
}

Change Image - changeImage()

Changes the source the source of “target” to “source”.

The Code

function changeImage(target, source) {
	var imageObj;

	if (ns4) {
		imageObj = getImage(target);
		if (imageObj) imageObj.src = eval(source).src;
	} else {
		imageObj = eval('document.images.' + target);
		if (imageObj) imageObj.src = eval(source).src;
	}
}

Change Background Colour - changeBGColour()

Changes the background colour of element “myObject” to colour.

The Code

function changeBGColour(myObject, colour) {
	if (ns4) {
		var obj = getObjNN4(document, myObject);
		obj.bgColor=colour;
	} else {
		var obj = getStyleObject(myObject);
		if (op5) {
			obj.background = colour;
		} else {
			obj.backgroundColor = colour;
		}
	}
}