Introducing DOCJSLIB, Part I: How to Use DOCJSLIB - Doc JavaScript

How to Use DOCJSLIB

DOCJSLIB is a set of JavaScript functions that create and manage DHTML elements, taking care of all browser inconsistencies. Since Netscape Navigator 4.01 cannot handle an external JavaScript file, we opted to keep DOCJSLIB in the same file of the application. Just copy DOCJSLIB from the first page and paste it in your JavaScript application, as we demonstrate in this column with our Connect-Three board game.

We designed DOCJSLIB in such a way that will free you from taking care of the nitty gritty details of DHTML element creation and keeping it consistent across platforms. DOCJSLIB presents you with a clean procedural interface (API) through which you can drive and control its behavior. This powerful interface allows you to become more efficient programmer. You will be able to focus your effort on your specific application as opposed to working on a generic stuff that people keep reinventing over and over again, all over the Internet community. If you are a newcomer to this field, DOCJSLIB will allow you to ramp up much faster, as you'll not have to solve problems that many people have solved before. For our column readers that complain that they cannot comprehend some of our complex JavaScript code, DOCJSLIB is a great answer for you. You won't have to dive into a complex code any more, but rather focus on your ideas and how to translate them into an attractive eye-catching application.

The cornerstone of DOCJSLIB Version 1.0 is the makeImage() function. This is the function you call to create a DHTML element. You can control its physical appearance and program its onClick() event handler. Here is the procedural interface you should become familiar with:

function makeImage(imgID,          // given id
                   imgURL,         // image URL
                   imgHeight,      // image height
                   imgWidth,       // image width
                   imgAlt,         // alternative image
                   posFromLeft,    // absolute position from left of window
                   posFromTop,     // absolute position from top of window
                   clickParam1,    // parameter passed to "onclick" handler
                   clickParam2)    // parameter passed to "onclick" handler

The parameters are self explanatory, but let's rehash their meaning:

• imgID. Put a unique ID for the image you want to create. Use a simple string for your image's ID.
• imgURL. This is the URL of the image's GIF. This is the URL you would normally assign the SRC attribute of the IMG tag.
• imgHeight. Put here the image height, in pixels. The image will be distorted if the height of the image's GIF (specified in the imgURL parameter) will not match the value you specify for imgHeight.
• imgWidth. Put here the image width, in pixels. The image will be distorted if the width of the image's GIF (specified in the imgURL parameter) will not match the value you specify for imgWidth.
• imgAlt. This is the alternative text message that will be displayed in the image area, until its GIF will be loaded. Just put a simple string that users will be able to recognize and click before the GIF is fully loaded. This alternative message is nice to have since it may save your users precious time.
• posFromLeft. This is the distance in pixels from the upper left corner of the image to the left edge of the window. Specify the desired distance from the edge of the window that you want your image to be positioned at.
• posFromTop. This is the distance in pixels from the upper left corner of the image to the top edge of the window. Specify the desired distance from the edge of the window that you want your image to be positioned at.
• clickParam1. This is the first of two parameters that you can pass to the onClick() event handler. It is not exactly onClick(), as we explain below.
• clickParam2. This is the second of two parameters that you can pass to the onClick() event handler. It is not exactly onClick(), as we explain below.

DOCJSLIB supports the handleImageClick() event handler. This event handler behaves similarly to the onClick() event handler, natively supported by many DHTML elements. You have to provide this event handler in your application. Its procedural interface must match the following format:

function handleImageClick(id, param1, param2) {
.
.
.
}

The first parameter is the image's ID, the same ID you specify as the first parameter of the DOCJSLIB makeImage() function. The other two parameters are those originally passed to makeImage(), called clickParam1 and clickParam2 above. You are responsible for writing the body of the function. This is the place to program the behavior of the image when clicked by the user. You can hide it, replace it, move it, etc. Later this column we show the example of the Connect-Three board game.

DOCJSLIB Version 1.0 includes two other functions, the getSrc() and setSrc(). The getSrc() function accepts one parameter, the image's ID, and returns the URL of the image's GIF:

function getSrc(id) {
.
.
.
}

The setSrc() function accepts two parameters, the image's ID and the URL of the image's GIF, and replaces the current image's GIF with the new one:

function setSrc(id url) {
.
.
.
}

The bodies of these functions are shown later this column

Created: October 12, 1998
Revised: October 12, 1998

URL: https://www.webreference.com/js/column27/usage.html