Availability

JavaScript 1.0; enhanced in JavaScript 1.1

Inherits from/Overrides

Inherits from HTMLElement

Synopsis

document.links[] 
document.links.length

Properties

Link inherits properties from HTMLElement and defines the following properties. Many of the properties represent portions of a URL. For each of these properties, the example given is a portion of the following (fictitious) URL:

http://www.oreilly.com:1234/catalog/search.html?q=JavaScript&m=10#results 

hash

A read/write string property that specifies the anchor portion of the Link's URL, including the leading hash (#) mark. For example: "#result". This anchor portion of a URL refers to a named position within the document referenced by the Link. In HTML files, positions are named with anchors created with the <a name="anchor_name"> tag.

host

A read/write string property that specifies the hostname and port portions of a Link's URL. For example, "www.oreilly.com:1234".

hostname

A read/write string property that specifies the hostname portion of a Link's URL. For example "www.oreilly.com".

href

A read/write string property that specifies the complete text of the Link's URL, unlike other Link URL properties that specify only portions of the URL.

pathname

A read/write string property that specifies the pathname portion of a Link's URL. For example "/catalog/search.html".

port

A read/write string (not a number) property that specifies the port portion of a Link's URL. For example "1234".

protocol

A read/write string property that specifies the protocol portion of a Link's URL, including the trailing colon. For example, "http:".

search

A read/write string property that specifies the query portion of a Link's URL, including the leading question mark. For example, "?q=JavaScript&m=10".

target

A read/write string property that specifies the name of a Window object (i.e., a frame or a top-level browser window) in which the linked document should be displayed. See the Link.target reference page for details.

text [Netscape 4]

Specifies the plain text, if any, between the <a> and </a> tags of a link. Note that this property works correctly only if there are no intervening HTML tags between the <a> and </a> tags. If there are other HTML tags, the text property may contain only a portion of the link text. HTMLElement.innerText provides the IE 4 equivalent of this Netscape-specific property.

Methods

Link inherits the methods of HTMLElement.

Event Handlers

Link inherits the event handlers of HTMLElement and defines special behavior for the following:

onclick

Invoked when the user clicks on the link. In JavaScript 1.1, this event handler may prevent the link from being followed by returning false. On Windows platforms in Netscape 3, this event handler does not work for links created with the <area> tag.

onmouseout

Invoked when the user moves the mouse off the link. Available in JavaScript 1.1 and later.

onmouseover

Invoked when the user moves the mouse over the link. The status property of the current window may be set here. May return true to tell the browser not to display the URL of the link.

HTML Syntax

A Link object is created with standard <a> and </a> tags. The href attribute is required for all Link objects. If the name attribute is also specified, an Anchor object is also created:

<a href="url"                  // The destination of the link
    [ name="anchor_tag" ]      // Creates an Anchor object
    [ target="window_name" ]   // Where the new document should be displayed
    [ onclick="handler" ]      // Invoked when link is clicked
    [ onmouseover="handler" ]  // Invoked when mouse is over link
    [ onmouseout="handler" ]   // Invoked when mouse leaves link
>
link text or image             // The visible part of the link
</a>

In JavaScript 1.1 and later, a Link object is also created by each <area> tag within a client-side image map. This is also standard HTML:

<map name="map_name">
    <area shape="area_shape"
        coords="coordinates"
        href="url"                 // The destination of the link
        [ target="window_name" ]   // Where the new document should be displayed
        [ onclick="handler" ]      // Invoked when area is clicked
        [ onmouseover="handler" ]  // Invoked when mouse is over area
        [ onmouseout="handler" ]   // Invoked when mouse leaves area
>
    ...
</map>

Description

The Link object represents a hypertext link or a clickable area of a client-side image map in an HTML document. All links created with the <a> and <area> tags are represented by Link objects and stored in the links[] array of the Document object. Note that links created by both the <a> and <area> tags are stored in the same array -- there is no distinction between them.

The destination of a hypertext link is a URL, of course, and many of the properties of the Link object specify the contents of that URL. The Link object is similar to the Location object, which also has a full set of URL properties. In the case of the Location object, these properties describe the URL of the currently displayed document.

In addition to its properties, the Link object has three event handlers. The onmouseover( ), onclick( ), and onmouseout( ) event handlers specify code to be executed when the mouse passes over the hypertext link, clicks on it, and moves off or out of the link's region of the screen.

See Also

Anchor, Location; HTMLAnchorElement in the DOM reference section