Make your own free website on Tripod.com

Cross-browser DHTML Functions
  Overview

Dynamic HTML has the promise to increase the interactive nature of web pages as well as enhance their look. Unfortunately, the two biggest players in the browser market, Netscape and Microsoft, have implemented DHTML quite differently in their latest versions.

The Cross-browser DHTML library is a small set of JavaScript functions designed for adding basic Dynamic HTML objects to a web page that can be viewed using either Netscape Communicator 4.0+ or Microsoft Internet Explorer 4.0+ browsers.

In order to achieve this, some compromises have to be made. But the result still provides a great deal of flexibilty while ensuring that the behaviour and look of a page will remain consistent regardless of which browser is being used.

What the Library Provides

These functions allow you to create and manipulate layer-type objects on a page. These layers contain any text and images you wish to display and can be positioned anywhere within the browser window or frame, even overlapping one another. You can animate the layers, hide and display them and rearrange their stacking order.

Note that the term layer is used to refer to the DHTML objects created and used by these functions, not the layer object used by Netscape.

Dealing with Different Browsers

The key to making these functions work on both DHTML browsers is by hiding the differences. Internally, almost all the functions check to see what browser is being used and then use the particular syntax, objects and methods specific to that browser.

For Netscape, this means testing for the document.layers object an using layer objects and methods. For IE, we test for the document.all object and use style sheets to create the layers. This not only allows you to determine which brand of browser is being used, but helps prevent errors from occuring when an older version of either browser is being used. When a object doesn't exist, no attempt is made to manipulate it.

Using the Libary

All the functions are contained in the file cbdhtml.js which you can download by right-clicking on the name and saving to your local drive, or you can view the source in your browser.

You can also use it with other cross-browser JavaScript utilities such as the event handling library offered by Netscape. See the examples page.

To use the library with a web page, add the following code somewhere in the header section (between the <head> and </head> tags):

<script language="JavaScript1.2" src="cbdhtml.js"></script>

You can then add your own JavaScript code to the page to call the various functions.

Examples

You can view these examples to see the kinds of effects you can create and the code needed to create them. For fun, you can try this asteroids game made using the library.

Function Descriptions

The functions are descriped below. Note that all the parameters listed for each are required. Unless otherwise specified, functions do not return a value.

createLayer(name,left,top,width,height,visible,content)

name
A string denoting the name to be given to this layer.
left, top
Integers specifying the position of the layer on the page, these correspond to the x and y coordinates of the layers upper-left corner.
width, height
Integers specifying the width and height of the layer, in pixels.
visible
A boolean value. True makes the layer initially visible, false will hide the layer.
content
A string containing the HTML code to display on the layer.

This function creates a layer object. You must call this function before the page has finished loading as it actually adds the necessary HTML code to the page using syntax appropriate for the browser. The easiest way to ensure this is to place the call between the <body> and </body> tags like in this example:

<body>
...
<script language="JavaScript1.2"
  var layer1 = "myLayer";
  createLayer(layer1, 10, 20, 50, 20, true, "<b>Hello</b>");
</script>
...
<body>

You could then refer to this layer in other functions using the variable layer1 or the string "myLayer".

Each call to createLayer() adds the layer name to an global array called layerList, which you can use if, for example, you wanted to loop through all the layers on the page and hide them.

hideLayer(name)

name
A string denoting the name used to create this layer.

Makes the named layer invisible. Note that you can still move or perform other functions on the layer while it is hidden.

showLayer(name)

name
A string denoting the name used to create this layer.

Makes the named layer visible.

isVisible(name)

name
A string denoting the name used to create this layer.

Returns true if the layer currently has visibility turned on. Note that it may still not be displayed if it's clipping area is zero or it is positioned off the edge of the page.

moveLayer(name,x,y)

name
A string denoting the name used to create this layer.
x, y
Integers specifying x and y coordinates relative to the page.

Moves the named layer so that its upper-left corner is positioned at the given coordinates.

slideLayer(name,x,y,speed[,code])

name
A string denoting the name used to create this layer.
x, y
Integers specifying x and y coordinates relative to the page.*
speed
An integer denoting the speed of the animation in pixels per second.*
code (optional)
A string containing JavaScript code to be executed at the end of the slide.*

Like moveLayer() but the movement is animated, causing the layer to slide from its current position to the new coordinates. The speed is given in pixels per second so if a layer is at (100,100) and you call slideLayer("myLayer", 200, 100, 50) it will slide to the right in two seconds.

*Denotes parameters that can be either a single value or an array of values. When arrays are used the function will execute a series of slides, one after the other, for each value given. This allows you to set a path of motion for animations. Note that if any parameter has a smaller number of values than the rest, the last value for that parameter is used for subsequent slides. For example, the code below uses arrays for x and y values but a single value for speed, so all slides will move at that speed.

  var x = new Array(10, 300, 240, 50);
  var y = new Array(100, 50, 170, 200);
  slideLayer("myLayer", x, y, 200);

If code is given, the string will be executed via the JavaScript eval() function at the end of the slide. This allows you to perform a new action once the movement has completed. For example, if you define a layer called "myLayer" and use the following code, the layer would continuously bounce back and forth across the screen.

function goLeft() {
  slideLayer("myLayer", 0, 0, 200, "goRight()");
}

function goRight() {
  slideLayer("myLayer", 0, 500, 200, "goLeft()");
}

goLeft();

You can use any valid JavaScript statement (or compound statement) in code, including function calls, that the eval() function will accept. This allows you to designate code to execute after the animation has completed.

clipLayer(name,clipleft,cliptop,clipright,clipbottom)

name
A string denoting the name used to create this layer.
clipleft, cliptop
Integers specifying x and y coordinates of the upper-left corner of the clipping region.
clipright, clipbottom
Integers specifying x and y coordinates of the lower-right corner of the clipping region.

Sets the clipping (viewable) region of the named layer. The coordinates are relative to the layer, not the page. Note that this does not affect the position of the layer on the page although it may appear to move as the viewable region changes.

swipeLayer(name,clipleft,cliptop,clipright,clipbottom,speed[,code])

name
A string denoting the name used to create this layer.
clipleft, cliptop
Integers specifying x and y coordinates of the upper-left corner of the clipping region.*
clipright, clipbottom
Integers specifying x and y coordinates of the lower-right corner of the clipping region.*
speed
An integer denoting the speed of the animation in pixels per second.*
code (optional)
A string containing JavaScript code to be executed at the end of the swipe.*

This function is to clipLayer() as slideLayer() is to moveLayer(). The layers clipping region is changed to the specified coordinates at the given rate, creating an animated effect. This is useful for expanding/collapsing, panning or scrolling effects.

*Denotes parameters that can be either a single value or an array of values. When arrays are used the function will execute a series of swipes, one after the other, for each value given. See slideLayer() above.

The optional code parameter works the same as in the slideLayer() function, allowing you to designate code to execute once the animation has completed.

scrollLayer(name,dx,dy)

name
A string denoting the name used to create this layer.
dx, dy
Integers specifying the amount of scroll to the left or right and up or down respectively, in pixels.

This function achieves the effect of scrolling a layer's contents by moving both the layer and it's clipping region at the same time. Use positive values for scrolling right or down and negative values to scroll left or up. To be used effectively, you should first set the clipping region of the layer so that only part of the layer is visible. The layer will not be scrolled past it's edges.

orbitLayer(name,x,y,a,b,start,num,rpm,rotation[,code])

name
A string denoting the name used to create this layer.
x, y
Integers specifying x and y coordinates of the center of the orbit.
a, b
Positive integers specifying the maximum horizontal and vertical radii of the orbit.
start
The starting angle of the orbit, in degrees.
num
The total number of orbits to make.
rpm
A positive value denoting the speed of the orbit in rotations per minute.
rotation
Angle, in degrees, to rotate the entire path.
code (optional)
A string containing JavaScript code to be executed at the end of the orbit.

This function will move the layer along an elliptical path about a given point. For a circular orbit, set a and b to the same value. The orbit will start at the postion given by the starting angle where zero degrees is at 12 o'clock, 90 degrees is at 3 o'clock, etc.

The value of num determines how many orbits will be made before the animation ends. You can use any value such as .5 for half an orbit or 3.25 for three and a quarter orbits. A negative value will create a counter-clockwise rotation.

The speed of the layer is determined by the rpm value. For example, a value of 60 would cause the layer to make one complete orbit every second while a value of 30 means that it would take two seconds for the layer to complete one orbit.

The rotation value defines the orientation of the ellipse, allowing you to tilt the orbit. Use a positive value to tilt it clockwise, negative for counter-clockwise.

You should note that unlike the other animation functions, orbitLayer() will move the layer to a new position at the beginning of the animation rather than moving it from it's current position. To find out where the animation will start, use the orbitStartX() and orbitStartY() functions described below.

The optional code parameter works the same as in the slideLayer() function, allowing you to designate code to execute once the animation has completed.

orbitStartX(x,y,a,b,start,rotation)

x, y
Integers specifying x and y coordinates of the center of the orbit.
a, b
Positive integers specifying the maximum horizontal and vertical radii of the orbit.
start
The starting angle of the orbit, in degrees.
rotation
Angle, in degrees, to rotate the entire path.

Returns the starting x-coordinate of the path generated using the given orbit parameters.

orbitStartY(x,y,a,b,start,rotation)

x, y
Integers specifying x and y coordinates of the center of the orbit.
a, b
Positive integers specifying the maximum horizontal and vertical radii of the orbit.
start
The starting angle of the orbit, in degrees.
rotation
Angle, in degrees, to rotate the entire path.

Returns the starting y-coordinate of the path generated using the given orbit parameters.

setBgColor(name,color)

name
A string denoting the name used to create this layer.
color
A string in standard RGB hexadecimal format.

This function will set the background color of a layer to the color specified. Use standard hex coding for the color value, e.g. setBgColor("myLayer", "#ccffcc");

setBgImage(name,imagesrc)

name
A string denoting the name used to create this layer.
imagesrc
A string denoting the url of the new image file.

This function will set the background image of a layer to the image specified.

replaceContent(name,content)

name
A string denoting the name used to create this layer.
content
A string containing the HTML code to display on the layer.

This function will delete the current contents of the named layer and replace it with the given content. Note that the original content is lost.

getLeft(name)
getTop(name)
getRight(name)
getBottom(name)

name
A string denoting the name used to create this layer.

These functions return an integer indicating the current x- or y-coordinate of the layers upper-left or lower-right corner relative to the page. These can be changed using moveLayer() or slideLayer();

getWidth(name)
getHeight(name)

name
A string denoting the name used to create this layer.

These functions return an integer indicating the width or height specified for a layer when it was created. Note that these values cannot be changed.

getClipLeft(name)
getClipTop(name)
getClipRight(name)
getClipBottom(name)

name
A string denoting the name used to create this layer.

These functions return an integer indicating the current x- or y-coordinates of the layers clipping region. Note that these coordinates are relative to the layers upper-left corner, not the page. These values can be changed using the clipLayer() and swipeLayer() functions.

getClipWidth(name)
getClipHeight(name)

name
A string denoting the name used to create this layer.

These functions return an integer indicating the current width or height of the layers clipping region.

getWinWidth()
getWinHeight()

Returns an integer indicating the width and height, respectively, of the current browser window or frame. These can be useful if you want to position a layer relative to the page. For example:

moveLayer(layer1, getWinWidth() - getWidth(layer1) / 2, getWinHeight - getHeight(layer1) / 2);

will position a layer in the center of the window or frame no matter what its dimensions are.

getzIndex(name)
setzIndex(name,z)

name
A string denoting the name used to create this layer.
z
A integer denoting the stacking value to assign to the layer.

getzIndex() returns an integer indicating the current stacking value of the layer. setzIndex lets you assign a new stacking value to the layer. When two layers overlap, the one with the higher stacking value is displayed on top of the other.

bringToFront(name)
sendToBack(name)

name
A string denoting the name used to create this layer.

These functions allow you to change the stacking order of all layers on the page so that the named layer appears on top of or below all the others. The order of the other layers relative to each other remains the same.

getImgSrc(imagename)

imagename
A string denoting the name assigned to an image via the 'name=' option of the <img> tag.

Returns the URL of the source file for the named image. Note that the full URL of the image file is returned. The image may be located within the body of the page or within a layer. In order to work properly, the name assigned to the image in the <img> tag should be unique to that page.

setImgSrc(imagename,imagesrc)

imagename
A string denoting the name assigned to an image via the 'name=' option of the <img> tag.
imagesrc
A string denoting the url of the new image file.

This provides an easy way to change an image on the page, whether it is defined within the body of the page or within the content of a layer. In order to work properly, the name assigned to the image in the <img> tag should be unique to that page.


Home