A Layer Object entry (and corresponding layers array entry) is created for every layer (specified by either <LAYER> or <ILAYER> elements, or for any element using the position:absolute or position:relative style sheet positioning attributes). These objects expose various methods, properties and events.

Referencing Layers
All layers defined in a document (the Layer object and layers array are properties of the Document object) can be referenced by their name (given in their NAME attribute) or by their index in the layers array. It's generally easier to reference layers by their name though, as their index in the layers array is determined by their z-order, from back (i.e. the furthest away) to front (the front-most layer). This isn't always the same as their zIndex property (or Z-INDEX attribute in the <ILAYER> or <LAYER> element) as these don't take account of the z-order of the layer with respect to any parent/sibling layers that the particular layer you are trying to reference may have. To reference a particular layer, use :

document.layerName...

or

document.layers.['layerName']...

Each layer object in the layers array has a document property, through which any child layers can be referenced through its parent layer, thus :

document.layers.['parentlayerName'].document.layers['layerName']..

To reference a layer in a different window, a valid window reference will need to be used to access the document object (a property of the Window Object), to access the layer object, or layers array.

Layer Properties
above
The above property returns a reference to the layer object that is above the referenced layer in the z-order, of all the layers in the document. For example, if you authored two layers, one NAMEd 'Red' and one NAMEd 'Blue', with the 'Blue' layer having a higher z-order than the 'Red' layer, then :

document.layers['Red'].above

would return a reference to the 'Blue' layer. (You'd need to append another property, such as name - see below - to be able to make sense of that layer object reference). If the referenced layer is the top-most layer (or the only layer), then the above property would return 'null'. The above property is read-only.

background
This property returns a reference to the referenced layers background image (if any - it returns 'null' if the referenced layer has no background image). Each background image is an Image Object (see the Images collection), whose properties can be interrogated, or methods manipulated. The background property can be dynamically changed.

below
The below property is the opposite of the above property (see above), in that it returns a reference to the layer that is immediately below (in terms of z-order) the currently referenced layer, or 'null' if the current layer is the bottom, or only layer. The below property is read-only.

bgColor
This property reflects the referenced layers background colour (as set in the BGCOLOR attribute of either the <ILAYER> or <LAYER> elements). It can be dynamically changed, by setting the property to a new colour, using any valid colour referencing technique (i.e. a #rrggbb hex triplet, or colour name).

clip
The clip property has 6 sub-properties, namely clip.top, clip.left, clip.right, clip.bottom, clip.width and clip.height, which can be used to determine, or dynamically set the clipping area (the area of the layer that is actually displayed) for the current layer.

left
This property reflects the referenced layers left-most point in pixels, relative to either its parent layer, or the left-most edge of the browser window if it has no parent layer. It can be manipulated to move the layer.

name
The name property reflects the referenced layers name, as set in the NAME attribute of either the <ILAYER> or <LAYER> element that defines the layer.

pageX
The pageX property represents the horizontal position of the referenced layer object, in pixels, relative to the main document page.

pageY
The pageY property represents the vertical position of the referenced layer object, in pixels, relative to the main document page.

parentLayer
The parentLayer property references the immediate parent layer of the currently referenced layer. If the currently referenced layer has no parent, then parentLayer returns 'null'.

siblingAbove
siblingAbove references the layer that is above the currently referenced layer (in terms of z-order), of all the layers that share the same parent layer. If the currently referenced layer is has no parent, or is a top-most layer, the siblingAbove property returns 'null'.

siblingBelow
siblingBelow references the layer that is below the currently referenced layer (in terms of z-order), of all the layers that share the same parent layer. If the currently referenced layer is has no parent, or is a bottom-most layer, the siblingBelow property returns 'null'.

src
The src property reflects the document that contains the content for the currently referenced layer (i.e. set by the SRC attribute of the <ILAYER> or <LAYER> element that defines the layer. It is read-only, that is, layer content can not be dynamically changed.

top
This property reflects the referenced layers top-most point in pixels, relative to either its parent layer, or the top-most edge of the browser window if it has no parent layer. It can be manipulated to move the layer.

visibility
The visibility property reflects the value of the VISIBILITY attribute (as set in the <ILAYER> or <LAYER> element). It can be manipulated to hide the currently referenced layer or force it to inherit its parent layers (if any) visibility (by setting the visibility property to inherit or hide within a script function.

zIndex
The zIndex property can be used to determine, or dynamically set the z-order (only with respect to parent or sibling layers) of the currently referenced layers. This can be useful for dynamically changing the overlap of any layers within the document.

Layer Methods
load (URL,width)
The load method can be used to replace the contents of the referenced layer object with a new source document, referenced by the URL argument of the method, the newly loaded source document also resizing the referenced layer object according to the width argument, which is specified in pixels.

moveAbove (LayerName)
The moveAbove method accepts one argument which must be a valid layer name. The layer referenced for the method is then placed above (in terms of z-order) the layer named in the argument, without physically altering its position on the screen. After the z-order change, both layers then share the same parent (if one of the layers was a child layer to start with).

moveBelow (LayerName)
The moveBelow method accepts one argument which must be a valid layer name. The layer referenced for the method is then placed below (in terms of z-order) the layer named in the argument, without physically altering its position on the screen. After the z-order change, both layers then share the same parent (if one of the layers was a child layer to start with).

moveBy (x,y)
The moveBy method moves the referenced layer horizontally (by the pixel amount given in the x argument) and vertically (by the pixel amount given in the y argument) relative to its current horizontal and vertical position.

moveTo (x,y)
The moveTo layer accepts two arguments which are screen positions in pixel values. For example :

document.layers['RedLayer'].moveTo (50,200)

would move the layer whose NAME is RedLayer to the position x=50, y=200 on the screen. The position can be anywhere on, or even off, the current browser viewing area.

moveToAbsolute (x,y)
The moveToAbsolute method moves the referenced layer to the position specified by the x and y arguments in the page, regardless of the position of the containing layer object.

resizeBy(x,y)
The resizeBy method resizes the referenced layer according to the pixel measurements given in the x and y arguments, relative to the referenced layers current size.

resizeTo(x,y)
The resizeTo method resizes the referenced layer absolutely, according to the x and y pixel measurements, regardless of its original size.

Layer Events
Each layer object in the Layers array/collection, fires the following events:

onblur
The onblur event fires whenever the referenced layer loses the users current focus.

onfocus
Whenever the user focuses (by clicking on) the referenced layer, the onfocus event fires.

onload
The onload event is fired when the document containing the referenced layer is fully loaded, regardless of the referenced layers visibility.

onmouseout
When the users mouse leaves the referenced layer, the onmouseout event is fired.

onmouseover
The onmouseover event is fired whenever the users mouse moves over the referenced layer.

© 1995-1998, Stephen Le Hunte