508 Part III ✦ Document Objects Reference Depending on the type and size of image, you will be amazed at the speedy response of this kind of loading. With small-palette graphics, the image displays instantaneously. A popular user-interface technique is to change the appearance of an image that represents a clickable button when the user rolls the mouse pointer atop that art. This action assumes that a mouse event fires on an element associated with the object. Prior to IE4 and NN6, IMG element objects did not respond to mouse events on their own. The required technique was to encase the IMG element inside an A element. This allowed the events associated with rollovers ( onMouseOver and onMouseOut) and a user click on the image to effect some change (usually to navi- gate to another page). While IE4+ and NN6+ provide these events directly for IMG element objects, you can guarantee your pages to be backward-compatible if you continue to surround your images with A elements. You can see examples of these kinds of actions in Chapters 12 and 22. Image rollovers are most commonly accomplished in two different image states: normal and highlighted. But you may want to increase the number of states to more closely simulate the way clickable buttons work in application programs. In some instances, a third state signifies that the button is switched on. For example, if you use rollovers in a frame for navigational purposes and the user clicks a button to navigate to the Products area, that button stays selected but in a different style than the rollover highlights. Some designers go one step further by providing a fourth state that appears briefly when the user mouses down an image. Each one of these states requires the download of yet another image, so you have to gauge the effect of the results against the delay in loading the page. The speed with which image swapping takes place may lead you to consider using this method for animation. Though this method may be practical for brief bursts of animation, the many other ways of introducing animation to your Web page (such as via GIF89a-standard images, Java applets, and a variety of plug-ins) produce animation that offers better speed control. In fact, swapping preloaded JavaScript image objects for some cartoon-like animations may be too fast. You can build a delay mechanism around the setInterval() method, but the precise timing between frames varies with client processor performance. All browsers that implement the IMG element object also implement the document.images array. You can (and should) use the availability of this array as a conditional switch before any script statements that work with the IMG element or Image object. The construction to use is as follows: if (document.images) { // statements working with images as objects } Earlier browsers treat the absence of this array as the equivalent of false in the if clause’s conditional statement. If you place an image inside a table cell, Navigator 3 sometimes generates two copies of the image object in its object model. This can disturb the content of the document.images array for your scripts. Specifying HEIGHT and WIDTH attributes for the image sometimes cures the problem. Otherwise, you have to craft scripts so they don’t rely on the document.images array. Tip IMG 509 Chapter 22 ✦ Image, Area, and Map Objects Most of the properties discussed here mirror attributes of the IMG HTML element. For more details on the meanings and implications of attribute values on the rendered content, consult the HTML 4.0 specification ( http://www.w3.org/TR/ REC-html40 ) and Microsoft’s extensions for IE (http://msdn.microsoft.com/ workshop/author/dhtml/reference/objects/img.asp ). Properties align Value: String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The align property defines how the image is oriented in relation to surrounding text content. It is a double-duty property because you can use it to control the ver- tical or horizontal alignment depending on the value (and whether the image is influenced by a float style attribute). Values are string constants, as follows: absbottom middle absmiddle right baseline texttop bottom top left The default alignment for an image is bottom. Increasingly, element alignment is handed over to style sheet control. Example (with Listing 22-1) on the CD-ROM Related Items: text-align, float style sheet attributes. alt Value: String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The alt property enables you to set or modify the text that the browser displays in the image’s rectangular space (if height and width are specified in the tag) before the image downloads to the client. Also, if a browser has images turned off (or is incapable of displaying images), the alt text helps users identify what is normally displayed in that space. You can modify this alt text even after the page loads. On the CD-ROM IMG.alt 510 Part III ✦ Document Objects Reference Example on the CD-ROM Related Item: title property. border Value: Integer Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ ✓✓✓ The border property defines the thickness in pixels of a border around an image. Remember that if you wrap an image inside an A element to make use of the mouse events (for rollovers and such), be sure to set the BORDER=0 attribute of the <IMG> tag to prevent the browser from generating the usual link kind of border around the image. Even though the default value of the attribute is zero, surrounding the image with an A element or attaching the image to a client-side image map puts a border around the image. Example on the CD-ROM Related Items: isMap, useMap properties. complete Value: Boolean Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ ✓✓✓ Sometimes you may want to make sure that an image is not still in the process of loading before allowing another process to take place. This situation is different from waiting for an image to load before triggering some other process (which you can do via the image object’s onLoad event handler). To verify that the IMG object displays a completed image, check for the Boolean value of the complete property. To verify that a particular image file has loaded, first find out whether the complete property is true; then compare the src property against the desired filename. An image’s complete property switches to true even if only the specified LOWSRC image has finished loading. Do not rely on this property alone for determining whether the SRC image has loaded if both SRC and LOWSRC attributes are specified in the <IMG> tag. On the CD-ROM On the CD-ROM IMG.complete 511 Chapter 22 ✦ Image, Area, and Map Objects One of the best ways to use this property is in an if construction’s conditional statement: if (document.myImage.complete) { // statements that work with document.myImage } The complete property is not reliable in Navigator 4 and some versions of Internet Explorer 4. For those browsers, the value returns true in all instances. Example (with Listing 22-2) on the CD-ROM Related Items: IMG.src, IMG.lowsrc, IMG.readyState properties; onLoad event handler. dynsrc Value: URL String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ The dynsrc property is a URL to a video source file, which (in IE) you can play through an IMG element. You can turn a space devoted to a static image into a video viewer by assigning a URL of a valid video source (for example, an .avi or .mpg file) to the dynsrc property of the image element object. Unlike the src property of image objects, assigning a URL to the dynsrc property does not precache the video. You may experience buggy behavior in various IE versions when you assign a value to an image’s dynsrc property after the IMG element renders a .gif or .jpg image. In IE5/Windows, the status bar indicates that the video file is still download- ing, even though the download is complete. Clicking the Stop button has no effect. IE5.5/Windows may not even load the video file, leaving a blank space on the page. IE5/Macintosh changes between static and motion images with no problems, but playing the video file multiple times causes the IMG element to display black space beyond the element’s rectangle. You can experience all this behavior in the example provided in Listing 22-3. None of these bugs is fatal, but they should discourage you from using the IMG element as a vehicle for video content. Example (with Listing 22-3) on the CD-ROM Related Items: IMG.loop, IMG.start properties. On the CD-ROM On the CD-ROM Note IMG.dynsrc 512 Part III ✦ Document Objects Reference fileCreatedDate fileModifiedDate fileSize Value: String, Integer (fileSize) Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ These three IE-specific properties return information about the file displayed in the IMG element (whether still or motion image). Two of the properties reveal the dates on which the current image’s file was created and modified. For an unmodi- fied file, its creation and modified dates are the same. The fileSize property reveals the number of bytes of the file. Date values returned for the first two properties are formatted differently between IE4 and IE5. The former provides a full readout of the day and date; the lat- ter returns a format similar to mm/dd/yyyy. Note, however, that the values contain only the date and not the time. In any case, you can use the values as the parameter to a new Date() constructor function. This enables you to then use date calcula- tions for such information as the number of days between the current day and the most recent modification. Not all servers provide the proper date or size information about a file or in a format that IE can interpret. Test your implementation on the deployment server to ensure compatibility. Also, be aware that these properties can be read-only for a file that is loaded in the browser. JavaScript by itself cannot get this information about files on the server that are not loaded in the browser. All of these file-related properties are present in the Mac version of IE, but the values are empty. Example on the CD-ROM Related Items: None. On the CD-ROM Note IMG.fileCreatedDate 513 Chapter 22 ✦ Image, Area, and Map Objects height width Value: Integer Read/Write (see text) NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ ✓✓✓ The height and width properties return and (in later browsers) control the pixel height and width of an image object. The property is read-only in NN3 and NN4, but it is read/write in all others that support the IMG element object. If you adjust the height property of an image, the browser automatically scales the image within the same proportions as the original. But adjusting the width property has no effect on the height property in most browser versions. Scaling of an image may cause unwanted pixelation in the image, so modify an image’s size with extreme care. Example on the CD-ROM Related Items: hspace, vspace properties. href See src property. hspace vspace Value: Integer Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ ✓✓✓ The hspace and vspace properties control the pixel width of a transparent margin surrounding an image. Specifically, hspace controls the margins at the top and bottom of the image; vspace controls the left and right side margins. Images, by default, have margins of zero pixels. Example on the CD-ROM Related Items: height, width properties. On the CD-ROM On the CD-ROM IMG.hspace 514 Part III ✦ Document Objects Reference isMap Value: Boolean Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The isMap property enables you to set whether the image should act as a server-side image map. When set as a server-side image map, pixel coordinates of the click are passed as parameters to whatever link HREF surrounds the image. For client-side image maps, see the useMap property later in this chapter. longDesc Value: URL String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The longDesc property is a URL of a file that is intended to provide a detailed description of the image associated with the IMG element. While NN6 recognizes this property, the browser does not appear to do anything special with this information — whether specified by script or the LONGDESC attribute. Related Item: alt property. Example on the CD-ROM Related Item: IMG.useMap property. loop Value: Integer Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ The loop property represents the number of times a video clip playing through the IMG element object should run. After the video plays that number of times, only the first frame of the video appears in the image area. The default value is 1; but if you set the value to -1, the video plays continuously. Unfortunately, setting the property to 0 prior to assigning a URL to the dynsrc property does not prevent the movie from playing at least once (except on the Mac, as noted in the dynsrc property discussion earlier in this chapter). On the CD-ROM IMG.loop 515 Chapter 22 ✦ Image, Area, and Map Objects Example on the CD-ROM Related Item: dynsrc property. lowsrc lowSrc Value: URL String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ ✓✓✓ For image files that take several seconds to load, recent browsers enable you to specify a lower-resolution image or some other quick-loading placeholder to stand in while the big image crawls to the browser. You assign this alternate image via the LOWSRC attribute in the <IMG> tag. The attribute is reflected in the lowsrc property of an image object. All compatible browsers recognize the all-lowercase version of this property. But the W3C DOM specification calls for the interCap “S”. NN6 recognizes this version as well. Be aware that if you assign a URL to the LOWSRC attribute, the complete property switches to true and the onLoad event handler fires when the alternate file finishes loading: The browser does not wait for the main SRC file to load. Example on the CD-ROM Related Items: IMG.src, IMG.complete properties. name Value: Identifier String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓✓(✓) ✓✓ ✓ The name property returns the value assigned to the NAME attribute of an IMG element. Starting with IE4 and NN6, you can use the ID of the element to reference the IMG element object via document.all and document.getElementById(). But references in the form of document.imageName and document.images[imageName] must use only the value assigned to the NAME attribute. On the CD-ROM On the CD-ROM IMG.name 516 Part III ✦ Document Objects Reference In some designs, it may be convenient to assign numerically sequenced names to IMG elements, such as img1, img2, and so on. As with any scriptable identifier, the name cannot begin with a numeric character. Rarely, if ever, will you need to change the name of an IMG element object. Example on the CD-ROM Related Item: id property. nameProp Value: Filename String Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ Unlike the src property, which returns a complete URL in IE, the IE nameProp property (not implemented in IE5/Mac) returns only the filename exclusive of protocol and path. If your image swapping script needs to read the name of the file currently assigned to the image (to determine which image to show next), the nameProp property makes it easier to get the actual filename without having to perform extensive parsing of the URL. Example on the CD-ROM Related Item: IMG.src property. protocol Value: String Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ The IE protocol property returns only the protocol portion of the complete URL returned by the src property. This allows your script, for example, to see if the image is sourced from a local hard drive or a Web server. Values returned are not the actual protocol strings; rather, they are descriptions thereof: HyperText Transfer Protocol or File Protocol. On the CD-ROM On the CD-ROM IMG.protocol 517 Chapter 22 ✦ Image, Area, and Map Objects Example on the CD-ROM Related Items: IMG.src, IMG.nameProp properties. src Value: URL String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓(✓) ✓✓ ✓ The src property is the gateway to precaching images (in instances of the Image object that are stored in memory) and performing image swapping (in IMG element objects). Assigning a URL to the src property of an image object in memory causes the browser to load the image into the browser’s cache (provided the user has the cache turned on). Assigning a URL to the src property of an IMG element object causes the element to display the new image. To take advantage of this powerful combination, you preload alternate versions of swappable images into image objects in memory and then assign the src property of the image object to the src property of the desired IMG element object. These powers are available in IE3 only in the Macintosh version (specifically, version 3.01, which was the first scriptable version of IE3 for the Mac). In NN3 and NN4 (all OS platforms) and IE3 for the Mac, the size of the image defined by the IMG element’s attributes (or, if not specified, then calculated by the browser from the size of the incoming image) governs the rectangular space devoted to that image. An attempt to assign an image of a different size to that IMG element object causes the image to rescale to fit the rectangle (usually resulting in a distorted image). In all later browsers, however, the IMG element object resizes itself to accommodate the image, and the page content reflows around the new size. Note that when you read the src property, it returns a fully formed URL of the image file including protocol and path. This often makes it inconvenient to let the name of the file guide your script to swap images with another image in a sequence of your choice. Some other mechanism (such as storing the current filename in a global variable) may be easier to work with (and see the IE5+/Windows nameProp property). IE4+ replicates the src property as the href property for an image object. This may be deprecated in IE, so stick with the src property when dealing with the URL of a still image. Example (with Figure 22-1 and Listing 22-4) on the CD-ROM Related Items: IMG.lowsrc, IMG.nameProp properties. On the CD-ROM On the CD-ROM IMG.src . 508 Part III ✦ Document Objects Reference Depending on the type and size of image, you will be amazed. variety of plug-ins) produce animation that offers better speed control. In fact, swapping preloaded JavaScript image objects for some cartoon-like animations may be too fast. You can build a delay. that space. You can modify this alt text even after the page loads. On the CD-ROM IMG.alt 510 Part III ✦ Document Objects Reference Example on the CD-ROM Related Item: title property. border Value: