mmmObjectLib.js
Instructions for Use

Michael Masumoto
email: michael@michaelmasumoto.com
phone: 707-869-1205

Updated: June 20, 2000

Synopsis:

This library allows you to create DynamicLayer objects, dynamically positionable and editable layers which are cross-browser compatible, supporting Netscape 4, IE4 and 5, and Netscape/Mozilla 6 (build M16 or better). DynamicLayer objects can be made visible and invisible, repositioned dynamically (with some very primitive animation methods), have their contents rewritten with fresh HTML code, moved in-front-of and behind other layers, and have image switches/rollovers performed on IMG tags within them. Additional properties and methods may easily be added to the base DynamicLayer object, should you so desire, to extend functionality.

DynamicLayer objects may also be used as quasi-superclass objects to create subclasses, should you so desire; beware, however, that subclassing javascript objects is non-standardized through the 4 browsers... See JavaScript: The Definitive Guide (O'Reilly & Assoc, pub), section 8.5.7, for more details.

This object does not support specialized event handling, such as drag-and-drop, although it could probably be extended to do so.

DynamicLayer objects are created from DIV based elements to create simple quasi-application screens or layers, and are currently restricted to Netscape 4 functionality. IE 4 and 5 and Netscape/Mozilla 6 have expanded capabilities which are not addressed in this library.

Note: All examples below assume that you have initialized a DynamicLayer object called myDivLayer, and that the ID for that DIV is "divLayer". Alternatively, for a nested DIV, the parent DIV would have an ID of "parentDivLayer" and a DynamicLayer object called myParentDivLayer, while the child DIV would have an ID of "childDivLayer" and a DynamicLayer object called myChildDivLayer.

Property List:

css
ref
x
y
home_x
home_y
layerID
obj
defaultZindex
isVisible

Property Descriptions:

Property: css
Description: contains a reference to the style object for a DIV layer. Can be used to actually manipulate all CSS properties for the layer. Remember that in IE5 and Netscape6, these properties are empty strings until set in JavaScript, so you can get information out of them only after you have set them once in JavaScript.
Example:
// this example only works if content for a layer is not tagged, that is to say, at
// the base level of the DIV tag and not tagged with <p></p> or anything else; it does
// not work on Netscape 4.
myDivLayer.css.fontSize = "14px"; // sets the fontSize for the layer to 14px.

Property: ref
Description: contains a reference to the actual DIV layer itself, for changes to be made directly to the layer. Used in this library for facilitating the write() and switchImage() methods.
Examples:
myDivLayer.ref.innerHTML = "<p>Hi There</p>"; // writes HTML to the layer; ie4/5 and netscape6 only
myDivLayer.ref.document.write("<p>Hi There</p>"); // writes HTML to the layer; netscape 4 only

Properties: x, y
Description: contains an integer representing the current left (x) and top (y) properties for the layer. Does not affect the actual layer, merely records current position information.
Examples:
// gets the current x position of the layer and stores it in the variable myXPosition:
var myXPosition = myDivLayer.x;
// gets the current y position of the layer and stores it in the variable myYPosition:
var myYPosition = myDivLayer.y;

Properties: home_x, home_y
Description: contains an integer representing the initial left (home_x) and top (home_y) positions for the layer. If you've been animating a layer, you can use these properties to return that layer back to its starting point.
Example:
// use the moveTo() method to move the layer back to its original position:
myDivLayer.moveTo(myDivLayer.home_x, myDivLayer.home_y);

Property: layerID
Description: contains a string which represents the ID for the DIV layer; this is a copy of the actual name, or ID, for the layer.
Example:
var myID = myDivLayer.layerID; // extracts the layer id/name from myDivLayer

Property: obj
Description: contains a string which is the ID for the layer plus the word "Object". If the ID for the myDivLayer DynamicLayer was "divLayer", then the obj property for that layer would be "divLayerObject". This property is used by the slide() method, and can be evaluated to an actual reference to the layer itself, which can then be manipulated in JavaScript.
Examples:
eval(myDivLayer.obj + ".write('<p>Hi</p>');");
is the same as:
divLayerObject.write("<p>Hi</p>");
which works the same as:
myDivLayer.write("<p>Hi</p>");
(all examples access the write() method of myDivLayer, the DynamicLayer object)

Property: defaultZindex
Description: contains an integer which represents the original z-index for a layer, so that if you start moving the layer around, you'll have a record of its original z-index state.
Example:
myDivLayer.setZindex(myDivLayer.defaultZindex);
which works the same as:
myDivLayer.resetZindex();

Property: isVisible
Description: contains a boolean representing the current visibility of the layer: false is hidden, true is visible. Test this to check the current visibility for the layer.
Example:
// if it's visible, hide it, otherwise, show it.
(myDivLayer.isVisible) ? myDivLayer.hide() : myDivLayer.show();

Method List:

initialize()
setZindex()
resetZindex()
hide()
show()
switchImage()
moveTo()
moveBy()
slideTo()
slideBy()
slide()
write()

Method Descriptions:

Method: initialize(xpos, ypos, zpos, myVisible)
Description: initializes DynamicLayer object properties to their correct starting values. This method must be passed either 5 or 6 arguments: xpos (int representing left value), ypos (int representing top value), zpos (int representing z-index value), myVisible (boolean representing initial visibility; true - visible, false - hidden), and the DIV ID name; if the DIV in question is a child DIV of a parent DIV, then you must first state the parent DIV name, followed by a comma, then the child DIV name. This method is usually called from an init() function invoked by the onLoad event handler in the BODY tag (see "Instructions for Use", below).
Examples:
myDivLayer.initialize(10, 10, 0, true, "divLayer");
myChildDivLayer.initialize(10, 100, 10, false, "parentDivLayer", "childDivLayer");

Method: setZindex(zpos)
Description: sets new z-index for DIV layer. Requires one argument, zpos (int representing new z-index value for the DIV layer).
Example:
myDivLayer.setZindex(25); // sets the z-index for the DIV layer to 25

Note: If you want to check the current z-index of the DIV layer, you'll have to look at the actual z-index property for the layer, like this:
// if the z-index is less than 10, bring the DIV layer forward to z-index of 100.
if (myDivLayer.css.zIndex < 10) myDivLayer.setZindex(100);

Method: resetZindex()
Description: resets the z-index for the DIV layer back to its initial state.
Example:
myDivLayer.resetZindex();

Method: hide()
Description: hides the DIV layer in question, and sets the isVisible property of the object to false.
Example:
myDivLayer.hide();

Method: show()
Description: makes the DIV layer in question visible, and sets the isVisible property of the object to true.
Example:
myDivLayer.show();

Method: switchImage(myImgName, myImgObj2Switch2)
Description: switches image that lays within a positioned DIV layer. Requires two arguments, myImgName (string which is the NAME of the IMG tag in question) and myImgObj2Switch2 (Image object). This method is required for image switches/rollovers when you use CSS-P/CSS2 to position elements in an HTML page because CSS-P/CSS2 necessitates the use of the browser-specific DOM calls rather than the simplified DOM calls standard in JavaScript1.1 and above. To make this method work, you have to be sure that you have initialized Image objects for each image that you want to switch, as follows:
var capitalA = new Image(54, 54);
var capitalB = new Image(54, 54);
capitalA.src = "./graphics/capitalA.gif";
capitalB.src = "./graphics/capitalB.gif";

In the BODY of the document, you also need an IMG tag in a positioned layer, as follows:
<div id="divLayer">
<img src="./graphics/capitalA.gif" width="54" height="54" name="theImage">
</div>

Example:
myDivLayer.switchImage("theImage", capitalB);

Method: moveTo(x, y)
Description: moves the DIV layer to the x,y coordinates indicated. Requires two arguments, x (int) and y (int).
Example:
myDivLayer.moveTo(200, 350);

Method: moveBy(x, y)
Description: moves the DIV layer BY the number of pixels in x and the number of pixels in y, i.e. if you were at 10,10 and you wanted to moveBy(20, 25) you would jump to 30,35. If, at 30,35, you then wanted to moveBy(-10,15), you would jump to 20,50. An essential part of the slide() method. Requires two arguments, x (int) and y (int).
Example:
myDivLayer.moveBy(25,25);

Method: slideTo(endx, endy, inc, speed, fn)
Description: causes DIV layer to slide to indicated point in jumps of inc pixels (1 or more) at a given speed (higher is slower, lower is faster), and executes a function at the end of the slide (optional). Requires four arguments, with an optional fifth argument (fn). endx (int representing ending x position), endy (int representing ending y position), inc (int representing how many pixels moved at a time, 1 or greater only!), speed (int representing overall speed, lower is faster, higher is slower, NO negative numbers!), and fn (string representing a function call to be invoked at the end of the slide, optional).
Examples:
myDivLayer.slideTo(200, 200, 1, 5);
myDivLayer.slideTo(10, 200, 2, 1, "myDivLayer.hide()");

Method: slideBy(distx, disty, inc, speed, fn)
Description: works the same as slideTo() method above, except that it slides BY the number of pixels indicated in distx and disty (both integers). Values of distx and disty may be negative, if appropriate.

Method: slide(dx, dy, endx, endy, speed, fn)
Description: base function for slideTo and slideBy methods above. Requires how many pixels x moved each iteration of the method (dx) and how many pixels y moved each iteration of the method (dy). Also requires ending x,y coordinates (endx, endy). Requires speed, just like slideTo and slideBy, above. May also be passed a string for fn, to be executed. This method is not called directly, it is only invoked when you call slideTo and slideBy above. speed is actually the number of milliseconds waited between each iteration of the setTimeout() loop in the method.

Method: write(myText)
Description: writes text to a DIV layer. You may write plain text to a layer, or text encased in HTML tags. You may write as much text or HTML as you desire. Requires one argument, myText (string representing text to be written).
Examples:
myDivLayer.write("Hi There");
myDivLayer.write("<p>Here is a paragraph of text.</p>");

Notes on Properties and Methods outlined above:

All CSS properties which are manipulated by methods above MUST be set using the appropriate methods (i.e. moveTo() to reset top and left properties, or setZindex() to set the z-index property, or hide()/show() to set the visibility property); otherwise, the corresponding DynamicLayer object properties will contain false information. The DynamicLayer x and y properties allow you to check current x,y coordinates and receive integer values rather than string information, as you would with the left and top properties polled directly from the style objects. You may test visibility through the isVisible property of the DynamicLayer objects, to prevent having to conditionalize for browser-inconsistent readings ("hide" vs "hidden", for instance).

mmmObjectLib.js
Instructions for Use:

1. Attach the mmmObjectLib.js file to your HTML page using the <SCRIPT> tag in the head of your document as follows:

<script language="JavaScript" src="./mmmObjectLib.js"></script>

2. Create both a <style></style> and an additional <script></script> in the head of your document as follows:

<style type="text/css">
<!--

//-->
</style>

<script language="JavaScript">
<!--

//-->
</script>

Note: if you are using a linked style sheet containing ID definitions for all of the DIV layers on your page, you may forego using the embedded STYLE tag shown above.


3. Define your <div> layers in the body of your HTML page, as follows:

<div id="divLayer">
<p>Here is some content</p>
</div>

4. Create the ID style information for your layer in your embedded STYLE sheet.

#divLayer { position:absolute; top:0px; left:0px; width:300px; height:200px; background-color:#FFFFFF; layer-background-color:#FFFFFF; border:solid 1px #FFFFFF; visibility:visible; z-index:3 }


5. Declare your layers as variable names in your SCRIPT, and initialize them as instances of the vanilla DynamicLayer object (remember: your variable name MUST be different than the ID name in your style sheet):

var myDivLayer = new DynamicLayer();


6. In your BODY tag, add the onLoad event handler, and set it to init(), as follows:

<BODY onLoad="init()">


7. Create the init() function in your <SCRIPT>:

function init() {

};


8. In your init() function, initialize your DynamicLayer objects using their initialize() method, passing the appropriate arguments, as follows:

function init() {
	myDivLayer.initialize(0, 0, 3, true, "divLayer");
};


9. You have now done everything necessary to create DHTML layers in your document. To manipulate those layers in your code, refer to the layers you have created by their variable names, and call the appropriate object methods or properties, as needed.