Table of Contents | Previous | Next | Index

# Link

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.

Client-side object
Implemented in | JavaScript 1.0 JavaScript 1.1: added `onMouseOut` event handler; added `Area` objects; `links` array contains areas created with `<AREA HREF="...">` JavaScript 1.2: added `x` and `y` properties; added `handleEvent` method

#### Created by

By using the HTML `A` or `AREA` tag or by a call to the `String.link` method. The JavaScript runtime engine creates a `Link` object corresponding to each `A` and `AREA` tag in your document that supplies the `HREF` attribute. It puts these objects as an array in the `document.links` property. You access a `Link` object by indexing this array. To define a link with the `A` or `AREA` tag, use standard HTML syntax with the addition of JavaScript event handlers. To define a link with the `String.link` method:

    theString.link(hrefAttribute)

where:

    theString
| A `String` object.
    hrefAttribute
| Any string that specifies the `HREF` attribute of the `A` tag; it should be a valid URL (relative or absolute).

#### Event handlers

`Area` objects have the following event handlers:

- `onDblClick`
- `onMouseOut`
- `onMouseOver`

`Link` objects have the following event handlers:

- `onClick`
- `onDblClick`
- `onKeyDown`
- `onKeyPress`
- `onKeyUp`
- `onMouseDown`
- `onMouseOut`
- `onMouseUp`
- `onMouseOver`

#### 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>

#### Property Summary

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.
    protocol
| Specifies the beginning of the URL, including the colon.
    search
| Specifies a query string.
    target
| Reflects the `TARGET` attribute.
    text
| A string containing the content of the corresponding `A` tag.
    x
| The horizontal position of the link's left edge, in pixels, relative to the left edge of the document.
    y
| The vertical position of the link's top edge, in pixels, relative to the top edge of the document.

#### Method Summary

Method | Description
--- | ---
    handleEvent
| Invokes the handler for the specified event.

In addition, this object inherits the `watch` and `unwatch` methods from `Object`.

#### 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: 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 7: 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.

    <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 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">

#### See also

`Anchor`, `Image`, `link`

## handleEvent

Invokes the handler for the specified event.

Method of | `Link`
Implemented in | JavaScript 1.2

#### Syntax

    handleEvent(event)

#### Parameters

    event
| The name of an event for which the specified object has an event handler.

#### Description

For information on handling events, see the Client-Side JavaScript Guide.

## hash

A string beginning with a hash mark (#) that specifies an anchor name in the URL.

Property of | `Link`
Implemented in | JavaScript 1.0

#### Security

JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

The `hash` property specifies a portion of the URL. This property applies to HTTP URLs only. Be careful using this property. Assume `document.links[0]` contains:

    http://royalairways.com/fish.htm#angel

Then `document.links[0].hash` returns `#angel`. Assume you have this code:

    hash = document.links[0].hash;
    document.links[0].hash = hash;

Now, document.links[0].hash returns `##angel`. This behavior may change in a future release. You can set the `hash` property at any time, although it is safer to set the `href` property to change a location. If the hash that you specify cannot be found in the current location, you get an error. Setting the `hash` property navigates to the named anchor without reloading the document. This differs from the way a document is loaded when other `link` properties are set. See RFC 1738 (`http://www.cis.ohio-state.edu/htbin/rfc/rfc1738.html`) for complete information about the hash.

#### See also

`Link.host`, `Link.hostname`, `Link.href`, `Link.pathname`, `Link.port`, `Link.protocol`, `Link.search`

## host

A string specifying the server name, subdomain, and domain name.

Property of | `Link`
Implemented in | JavaScript 1.0

#### Security

JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

The `host` property specifies a portion of a URL. The `host` property is a substring of the `hostname` property. The `hostname` property is the concatenation of the `host` and `port` properties, separated by a colon. When the `port` property is null, the `host` property is the same as the `hostname` property. You can set the `host` property at any time, although it is safer to set the `href` property to change a location. If the host that you specify cannot be found in the current location, you get an error. See Section 3.1 of RFC 1738 (`http://www.cis.ohio-state.edu/htbin/rfc/rfc1738.html`) for complete information about the hostname and port.

#### See also

`Link.hash`, `Link.hostname`, `Link.href`, `Link.pathname`, `Link.port`, `Link.protocol`, `Link.search`

## hostname

A string containing the full hostname of the server, including the server name, subdomain, domain, and port number.

Property of | `Link`
Implemented in | JavaScript 1.0

#### Security

JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

The `hostname` property specifies a portion of a URL. The `hostname` property is the concatenation of the `host` and `port` properties, separated by a colon. When the `port` property is 80 (the default), the `host` property is the same as the `hostname` property. You can set the `hostname` property at any time, although it is safer to set the `href` property to change a location. If the hostname that you specify cannot be found in the current location, you get an error. See Section 3.1 of RFC 1738 (`http://www.cis.ohio-state.edu/htbin/rfc/rfc1738.html`) for complete information about the hostname.

#### See also

`Link.host`, `Link.hash`, `Link.href`, `Link.pathname`, `Link.port`, `Link.protocol`, `Link.search`

## href

A string specifying the entire URL.

Property of | `Link`
Implemented in | JavaScript 1.0

#### Security

JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

The `href` property specifies the entire URL. Other `link` object properties are substrings of the `href` property. You can set the `href` property at any time. See RFC 1738 (`http://www.cis.ohio-state.edu/htbin/rfc/rfc1738.html`) for complete information about the URL.

#### See also

`Link.hash`, `Link.host`, `Link.hostname`, `Link.pathname`, `Link.port`, `Link.protocol`, `Link.search`

## pathname

A string specifying the URL-path portion of the URL.

Property of | `Link`
Implemented in | JavaScript 1.0

#### Security

JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

The `pathname` property specifies a portion of the URL. The pathname supplies the details of how the specified resource can be accessed. You can set the `pathname` property at any time, although it is safer to set the `href` property to change a location. If the pathname that you specify cannot be found in the current location, you get an error. See Section 3.1 of RFC 1738 (`http://www.cis.ohio-state.edu/htbin/rfc/rfc1738.html`) for complete information about the pathname.

#### See also

`Link.host`, `Link.hostname`, `Link.hash`, `Link.href`, `Link.port`, `Link.protocol`, `Link.search`

## port

A string specifying the communications port that the server uses.

Property of | `Link`
Implemented in | JavaScript 1.0

#### Security

JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

The `port` property specifies a portion of the URL. The `port` property is a substring of the `hostname` property. The `hostname` property is the concatenation of the `host` and `port` properties, separated by a colon. When the `port` property is 80 (the default), the `host` property is the same as the `hostname` property. You can set the `port` property at any time, although it is safer to set the `href` property to change a location. If the port that you specify cannot be found in the current location, you will get an error. If the `port` property is not specified, it defaults to 80 on the server. See Section 3.1 of RFC 1738 (`http://www.cis.ohio-state.edu/htbin/rfc/rfc1738.html`) for complete information about the port.

#### See also

`Link.host`, `Link.hostname`, `Link.hash`, `Link.href`, `Link.pathname`, `Link.protocol`, `Link.search`

## protocol

A string specifying the beginning of the URL, up to and including the first colon.

Property of | `Link`
Implemented in | JavaScript 1.0

#### Security

JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

The `protocol` property specifies a portion of the URL. The protocol indicates the access method of the URL. For example, the value `"http:"` specifies HyperText Transfer Protocol, and the value `"javascript:"` specifies JavaScript code. You can set the `protocol` property at any time, although it is safer to set the `href` property to change a location. If the protocol that you specify cannot be found in the current location, you get an error. The `protocol` property represents the scheme name of the URL. See Section 2.1 of RFC 1738 (`http://www.cis.ohio-state.edu/htbin/rfc/rfc1738.html`) for complete information about the protocol.

#### See also

`Link.host`, `Link.hostname`, `Link.hash`, `Link.href`, `Link.pathname`, `Link.port`, `Link.search`

## search

A string beginning with a question mark that specifies any query information in the URL.

Property of | `Link`
Implemented in | JavaScript 1.0

#### Security

JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

The `search` property specifies a portion of the URL. This property applies to http URLs only. The `search` property contains variable and value pairs; each pair is separated by an ampersand. For example, two pairs in a search string could look like the following:

    ?x=7&y=5

You can set the `search` property at any time, although it is safer to set the `href` property to change a location. If the search that you specify cannot be found in the current location, you get an error. See Section 3.3 of RFC 1738 (`http://www.cis.ohio-state.edu/htbin/rfc/rfc1738.html`) for complete information about the search.

#### See also

`Link.host`, `Link.hostname`, `Link.hash`, `Link.href`, `Link.pathname`, `Link.port`, `Link.protocol`

## target

A string specifying the name of the window that displays the content of a clicked hypertext link.

Property of | `Link`
Implemented in | JavaScript 1.0

#### Description

The `target` property initially reflects the `TARGET` attribute of the`A` or `AREA` tags; however, setting `target` overrides this attribute. You can set `target` using a string, if the string represents a window name. The `target` property cannot be assigned the value of a JavaScript expression or variable. You can set the `target` property at any time.

#### Examples

The following example specifies that responses to the `musicInfo` form are displayed in the `msgWindow` window:

    document.musicInfo.target="msgWindow"

#### See also

`Form`

## text

A string containing the content of the corresponding `A` tag.

Property of | `Link`
Implemented in | JavaScript 1.2

## x

The horizontal position of the link's left edge, in pixels, relative to the left edge of the document.

Property of | `Link`
Read-only |
Implemented in | JavaScript 1.2

#### See also

`Link.y`

## y

The vertical position of the link's top edge, in pixels, relative to the top edge of the document.

Property of | `Link`
Read-only |
Implemented in | JavaScript 1.2

#### See also

`Link.x`

Table of Contents | Previous | Next | Index

Last Updated: 05/28/99 11:59:47

Copyright (c) 1999 Netscape Communications Corporation