[Chapter 14] 14.2 The Link Object
Author: David Flanagan
Date: Fri Aug 29 11:00:47 1997

#

| Chapter 14 Documents and Their Contents |

## 14.2 The Link Object

The previous section has described the Document object and some of its important methods and properties. The Document object has a number of other properties that we have not discussed yet. These properties are arrays, each of which contains references to other important JavaScript objects. This and the following sections explain the `links[]`, `anchors[]`, `applets[]`, `embeds[]`, `images[]`, and `forms[]` properties of the Document object, and the Link, JavaObject, Image, and Form objects those array properties refer to.

The Link object represents a hypertext link in a document, and is created with an `<A HREF="``hyperlink``">` HTML tag, or, in Navigator 3.0, with an `<AREA>` tag within a client-side image map `<MAP>` tag. The `links[]` property of the Document object is an array that contains a complete list of hypertext links in the document. The `Link` object represents the URL of the hypertext link, and contains all of the properties that the `Location` object does. For example, the `href` property of a Link object contains the complete text of the URL that is linked to, and the `hostname` property contains only the hostname portion of that URL. See the reference section for a complete list of these URL-related properties.

One obvious use of the Link object and the `links[]` array is to write a "web crawler" program. This program would run in one browser window or frame and read web pages into another window or frame (by setting the `location` property of the Window object). For each page it reads in, it would look through the `links[]` array and recursively follow them. If carefully written (so it doesn't get caught in infinite recursion or doesn't start going in circles) such a program can, for example, be used to generate a list of all web pages that are accessible from a given starting page, and can be quite useful in web site maintenance. Example 14.3 shows a simple function that can be used to generate a list of all the links in a specified Document object.

#### Example 14.3: Listing the Links in a Document

    // Create a new window and list the destinations of all links in document d
    // in that window. Note that we use a text/plain document.
    function listlinks(d)
    {
        var newwin = window.open("", "linklist",
                        "menubar,scrollbars,resizable,width=600,height=300");
        newwin.document.open("text/plain");
        for (var i = 0; i < d.links.length; i++)
            newwin.document.writeln(d.links[i]);
        newwin.document.close();
    }

Don't expect to search the entire Internet with this technique, however. For security reasons, JavaScript in Navigator 2.0 and Navigator 3.0 is "hobbled" so that it cannot steal data that may be private. The restriction is this: a script running in one window or frame can read properties from other windows or frames only if the contents of the other window or frame were loaded from the same web server as the script. While our "web crawler" program as we've described it above is not a threat to Internet security or privacy, this general security restriction will prevent it from crawling very far beyond the site from which it was loaded. (When the crawler loads a page from a different site, it will appear as if that page simply has no links on it.) See Chapter 20, JavaScript Security, for a complete discussion of JavaScript security, including a description of how to partially lift the restriction described here with the `domain` property, or to fully lift it by enabling the data-tainting security model.

More interesting than the URL-related properties of the Link object are the event handlers it supports. We saw the `onMouseOver()` event handler previously in Example 12.3 where it was used with both `<A>` and `<AREA>` to change the message in the browser's status line when the mouse moved over the link.

In addition to this `onMouseOver()` event handler, the link object supports two others. The `onClick()` event handler is invoked when the user clicks on a hypertext link. In Navigator 3.0, if this event handler returns `false` then the browser won't follow the link, as it would otherwise. Note that `onClick()` only works for Link objects created with the `<A>` tag; it should work for those created with the `<AREA>` tag in a future version of the language.

In Navigator 3.0, both the `<A>` and `<AREA>` tags support an `onMouseOut()` event handler. This is simply the opposite of the `onMouseOver()` handler--it is run when the mouse pointer moves off of a hypertext link. If you used `onMouseOver()` to display a message in the status line, you can use `onMouseOut()` to clear it; as we saw in Chapter 12, Programming with Windows, the status line is not automatically cleared, as it should be, on Windows platforms.

Finally, it is worth mentioning that the `href` and other URL properties of the Link object are read/write. Thus, you can write JavaScript programs that dynamically modify the destinations of hypertext links! Example 14.4 is a frivolous piece of JavaScript-enhanced HTML that implements a random hypertext link. It demonstrates each of the features of the Link object that we've considered: the `links[]` array, the use of the Link event handlers, and dynamic setting of the destination of a Link. Note that the example sets the `href` property of the Link, but doesn't bother to read the `href` property of the link it randomly chooses. Instead, it simply relies on the `toString()` method of the Link object to return the URL.

#### Example 14.4: A Random Hypertext Link

    <A HREF="about:"
        onMouseOver="status = 'Take a chance... Click me.'; return true;"
        onMouseOut="status = ''"
        onClick="this.href =
                  document.links[Math.floor(Math.random()*document.links.length)]"
    >
    Random Link
    </A>

The Document Object |  | The Anchor Object