Link object

Object. A piece of text, an image, or an area of an image identified as a hypertext link. When the user clicks the link text, image, or area, the link hypertext reference is loaded into its target window. Area objects are a type of Link object.

HTML syntax

To define a link, use standard HTML syntax with the addition of JavaScript event handlers:

<A HREF=locationOrURL
   [NAME="anchorName"]
   [TARGET="windowName"]
   [onClick="handlerText"]
   [onMouseOut="handlerText"]>
   [onMouseOver="handlerText"]>
   linkText
</A>

You can also define a link using the link method.

To define an area, use standard HTML syntax with the addition of JavaScript event handlers:

<MAP NAME="mapName">
   <AREA
      [NAME="areaName"]
      COORDS="x1,y1,x2,y2,..."|"x-center,y-center,radius"
      HREF="locationOrURL"
      [SHAPE="rect"|"poly"|"circle"|"default"]
      [TARGET="windowName"]
      [onMouseOut="handlerText"]
      [onMouseOver="handlerText"]>
</MAP>

HTML attributes

HREF=locationOrURL identifies a destination anchor or URL. For areas, any region of an image that does not have an HREF attribute does not function as a hyperlink. For areas, this attribute is required if you include the onMouseOut and onMouseOver event handlers. See the location object for a description of the URL components.

NAME="anchorName" is used only if the link is also an anchor. It specifies a name for the anchor that then becomes an available hypertext target within the current document. See the Anchor object for details.

TARGET="windowName" specifies the frame or window that the link is loaded into. windowName can be an existing window; it can be a frame name specified in a <FRAMESET> tag; or it can be one of the literal frame names _top, _parent, _self, or _blank. It cannot be a JavaScript expression (for example, it cannot be parent.frameName or windowName.frameName).

linkText is the text or HTML source that the user sees as a hypertext link to the URL.

NAME="mapName" specifies the name of the map. You can specify this map name in the USEMAP attribute of the <IMG> tag.

AREA defines an area of an image as an image map.

NAME="areaName" specifies the name of the Area object. This attribute is not reflected in JavaScript (you cannot refer to an Area object by name).

COORDS specifies the coordinates of the image map.

SHAPE specifies the shape of the map. "default" specifies a region as the default. If omitted, "rect" is used.

Syntax

To use a Link or Area object's properties:

document.links[index].propertyName

Parameters

index is an integer representing a Link or Area object or the name of a Link or Area object as specified by the NAME attribute.

propertyName is one of the properties listed below.

Property of

document

Implemented in

Navigator 2.0
Navigator 3.0: added onMouseOut event handler; added Area objects; links array contains areas created with <AREA HREF="...">

Description

Each Link object is a location object and has the same properties as a location object.

If a Link object is also an Anchor object, the object has entries in both the anchors and links arrays.

When a user clicks a Link object and navigates to the destination document (specified by HREF=locationOrURL), the destination document's referrer property contains the URL of the source document. Evaluate the referrer property from the destination document.

You can use a Link object to execute a JavaScript function rather than link to a hypertext reference by specifying the javascript: URL protocol for the link's HREF attribute. You might want to do this if the link surrounds an Image object and you want to execute JavaScript code when the image is clicked. Or you might want to use a link instead of a button to execute JavaScript code.

For example, when a user clicks the following links, the slower and faster functions execute:

<A HREF="javascript:slower()">Slower</A>
<A HREF="javascript:faster()">Faster</A>

You can use a Link object to do nothing rather than link to a hypertext reference by specifying the javascript:void(0) URL protocol for the link's HREF attribute. You might want to do this if the link surrounds an Image object and you want to use the link's event handlers with the image. When a user clicks the following link or image, nothing happens:

<A HREF="javascript:void(0)">Click here to do nothing</A>

<A HREF="javascript:void(0)">
   <IMG SRC="images\globe.gif" ALIGN="top" HEIGHT="50" WIDTH="50">
</A>

Area objects

Area objects are in the links array. You cannot refer to an Area object by name; you must use the links array. For example, if a document contains three Area objects, these objects are reflected as document.links[0], document.links[1], and document.links[2]. For information on the links array, see "The links array".

The HREF attribute is required for Area objects that use the onMouseOut or onMouseOver event handlers. However, if you create an Area for an image and do not want the image to link to a hypertext reference when clicked, specify a JavaScript function in the area's HREF attribute by using the javascript: URL protocol. For example, if a user clicks the following Area object, the function onTop executes.

<MAP NAME="worldMap">
   <AREA NAME="topWorld" COORDS="0,0,50,25" HREF="javascript:onTop()"
      onMouseOver="self.status='You are on top of the world';return true"
      onMouseOut="self.status='You have left the top of the world';return true">
</MAP>

If you want an area's link to do nothing, use javascript:void(0) in the HREF attribute. When the user clicks the following Area object, nothing happens:

<MAP NAME="worldMap">
   <AREA NAME="topWorld" COORDS="0,0,50,25" HREF="javascript:void(0)"
      onMouseOver="self.status='You are on top of the world';return true"
      onMouseOut="self.status='You have left the top of the world';return true">
</MAP>

The links array

You can reference the Area and Link objects in your code by using the links array. This array contains an entry for each Area (<AREA HREF="..."> tag) and Link (<A HREF=""> tag) object in a document in source order. It also contains links created with the link method.For example, if a document contains three Link objects, these links are reflected as document.links[0], document.links[1], and document.links[2].

To use the links array:

1. document.links[index]
2. document.links.length

index is an integer representing a link in a document or the name of a Link object as specified by the NAME attribute.

To obtain the number of links in a document, use the length property: document.links.length.

Elements in the links array are read-only. For example, the statement document.links[0]="link1" has no effect.

Properties

The Area and Link objects have the following properties:


Property	Description
hash	Specifies an anchor name in the URL
host	Specifies the host and domain name, or IP address, of a network host
hostname	Specifies the host:port portion of the URL
href	Specifies the entire URL
pathname	Specifies the url-path portion of the URL
port	Specifies the communications port that the server uses for communications
protocol	Specifies the beginning of the URL, including the colon
search	Specifies a query
target	Reflects the TARGET attribute

The links array has the following property:


Property	Description
length	Reflects the number of links in a document

Methods

Event handlers

Area objects have the following event handlers:

Link objects have the following event handlers:

Examples

Example 1. The following example creates a hypertext link to an anchor named javascript_intro:

<A HREF="#javascript_intro">Introduction to JavaScript</A>

Example 2. The following example creates a hypertext link to an anchor named numbers in the file doc3.html in the window window2. If window2 does not exist, it is created.

<LI><A HREF=doc3.html#numbers TARGET="window2">Numbers</A>

Example 3. The following example takes the user back x entries in the history list:

<A HREF="javascript:history.go(-1 * x)">Click here</A>

Example 4. The following example creates a hypertext link to a URL. The user can use the set of radio buttons to choose between three URLs. The link's onClick event handler sets the URL (the link's href property) based on the selected radio button. The link also has an onMouseOver event handler that changes the window's status property. As the example shows, you must return true to set the window.status property in the onMouseOver event handler.

<SCRIPT>
var destHREF="http://home.netscape.com/"
</SCRIPT>
<FORM NAME="form1">
<B>Choose a destination from the following list, then click "Click me" below.</B>
<BR><INPUT TYPE="radio" NAME="destination" VALUE="netscape"
   onClick="destHREF='http://home.netscape.com/'"> Netscape home page
<BR><INPUT TYPE="radio" NAME="destination" VALUE="sun"
   onClick="destHREF='http://www.sun.com/'"> Sun home page
<BR><INPUT TYPE="radio" NAME="destination" VALUE="rfc1867"
   onClick="destHREF='http://www.ics.uci.edu/pub/ietf/html/rfc1867.txt'"> RFC 1867
<P><A HREF=""
   onMouseOver="window.status='Click this if you dare!'; return true"
   onClick="this.href=destHREF">
   <B>Click me</B></A>
</FORM>

Example 5: links array. In the following example, the linkGetter function uses the links array to display the value of each link in the current document. The example also defines several links and a button for running linkGetter.

function linkGetter() {
   msgWindow=window.open("","msg","width=400,height=400")
   msgWindow.document.write("links.length is " +
      document.links.length + "<BR>")
   for (var i = 0; i < document.links.length; i++) {
      msgWindow.document.write(document.links[i] + "<BR>")
   }
}

<A HREF="http://home.netscape.com">Netscape Home Page</A>
<A HREF="http://www.catalog.com/fwcfc/">China Adoptions</A>
<A HREF="http://www.supernet.net/~dugbrown/">Bad Dog Chronicles</A>
<A HREF="http://www.best.com/~doghouse/homecnt.shtml">Lab Rescue</A>
<P>
<INPUT TYPE="button" VALUE="Display links"
   onClick="linkGetter()">

Example 6: Area object with onMouseOver and onMouseOut event handlers. The following example displays an image, globe.gif. The image uses an image map that defines areas for the top half and the bottom half of the image. The onMouseOver and onMouseOut event handlers display different status bar messages depending on whether the mouse passes over or leaves the top half or bottom half of the image. The HREF attribute is required when using the onMouseOver and onMouseOut event handlers, but in this example the image does not need a hypertext link, so the HREF attribute executes javascript:void(0), which does nothing (see "void" for more information).

<MAP NAME="worldMap">
   <AREA NAME="topWorld" COORDS="0,0,50,25" HREF="javascript:void(0)"
      onMouseOver="self.status='You are on top of the world';return true"
      onMouseOut="self.status='You have left the top of the world';return true">
   <AREA NAME="bottomWorld" COORDS="0,25,50,50" HREF="javascript:void(0)"
      onMouseOver="self.status='You are on the bottom of the world';return true"
      onMouseOut="self.status='You have left the bottom of the world';return true">
</MAP>
<IMG SRC="images\globe.gif" ALIGN="top" HEIGHT="50" WIDTH="50" USEMAP="#worldMap">

Example 7: Refer to Area object with links array. The following code refers to the href property of the first Area object shown in Example 1.

document.links[0].href

Example 8: Simulate an Area object's onClick using the HREF attribute. The following example uses an Area object's HREF attribute to execute a JavaScript function. The image displayed, colors.gif, shows two sample colors. The top half of the image is the color "antiquewhite", and the bottom half is "white". When the user clicks the top or bottom half of the image, the function setBGColor changes the document's background color to the color shown in the image.

<SCRIPT>
function setBGColor(theColor) {
   document.bgColor=theColor
}
</SCRIPT>
Click the color you want for this document's background color
<MAP NAME="colorMap">
   <AREA NAME="topColor" COORDS="0,0,50,25" HREF="javascript:setBGColor('antiquewhite')">
   <AREA NAME="bottomColor" COORDS="0,25,50,50" HREF="javascript:setBGColor('white')">
</MAP>
<IMG SRC="images\colors.gif" ALIGN="top" HEIGHT="50" WIDTH="50" USEMAP="#colorMap">