Sunday, June 19, 2005
Properties II: The Document Object
Blog Entry #13
References
(1) HTML Goodies' JavaScript Primers #7
(2) DevGuru's document object page
(3) JavaScript Kit's document object page
(4) IRT's document object page
We continue our JavaScript property odyssey by turning to the document object. In HTML Goodies' JavaScript Primers #7, Joe lists and gives definitions for thirteen document object properties:
bgColor, fgColor, linkColor, alinkColor, vlinkColor, location, referrer, title, lastModified, cookie, anchors, forms, links
Joe demonstrates the first nine of these properties in the Primer #7 script, which reads them, returning their values. Of this group, the bgColor, fgColor, linkColor, alinkColor, vlinkColor, location, and title properties are in fact read/write, whereas the referrer and lastModified properties are read-only.
The first five properties are analogous to familiar-but-now-mostly-deprecated attributes of the document <body> element:
| Document Property | Corresponding <body> Attribute |
| bgColor | bgcolor |
| fgColor | text |
| linkColor | link |
| alinkColor | alink |
| vlinkColor | vlink |
We discussed and demonstrated the document bgColor property in Blog Entry #8. Also, here is a page that demonstrates the document fgColor property. (Here at Blogger, my use of a document.fgColor command will change the color of the reptile7's JavaScript blog title at the top of the page but not the color of the post text, which is part of a div element and is thus not "foreground" text.) I leave it to you to devise your own demos for the linkColor, alinkColor, and vlinkColor properties.
The document location property, according to the HTML Goodies' JavaScript Properties Keyword Reference page, returns the URL of the current document and is "read-only". I nonetheless find that I am able to write this property when using either MSIE or Netscape, i.e., I can use a document.location command to set up a link, much like the parent.location command that we discussed in Blog Entry #10. Try it out below:
The code for the button is:
<form>
<input type="button" value="Click Here to See the document.location Property in Action" onclick="document.location='#doclocDiv';">
</form>
However, the folks at Netscape say: "Location is not a property of the document object; its equivalent is the document.URL property. The document.location property, which is a synonym for document.URL, is deprecated." Hmmm...I was wondering why neither DevGuru, nor JavaScript Kit, nor IRT lists a location property at its document object page (they all list a URL property)...it would seem, then, that the window.location command is a better choice for setting up a link or for returning the URL of the current page than is the document.location command.
In the name of completeness: in comparing the document.location and document.URL expressions, I find that they are indeed both writable and return the same values when using MSIE; with Netscape, in contrast, document.location is writable but document.URL is read-only, although they read identically.
For the document referrer property, which as noted above is read-only, DevGuru provides the best and most precise definition: "If a destination document [the one you're currently looking at] is reached by a user clicking on a Link object [a hyperlink] in another document (the referrer), this property returns the referring document's URL." The document.referrer command does not simply return the URL of the Web page that you were at prior to the current page. If you arrive at the current page in some way other than clicking a link on the preceding page, for example:
(a) you typed the URL of the current page into the browser's address bar and then hit the return/enter key; or
(b) perhaps the current page is a bookmark and you accessed it via the Favorites/Bookmarks menu; or
(c) maybe you are reaccessing the current page via the Back button on the browser's toolbar after following a link on the current page, etc.;
then, as Joe notes, "no [referring] page is available...it [document.referrer] returns a blank space."
BTW, JavaScript makes a distinction between a Link object, representing a source anchor element whose <a> tag holds a href="http://www.some_web_page.com" attribute, and an Anchor object, which represents a target anchor element whose <a> tag holds a name="codeword" attribute.
Primer #7's definition of the document title property - "[it] returns the text between the HTML document's TITLE [element tags]" - suggests that it is read-only (as does its definitions in the HTML Goodies JavaScript Properties Keyword Reference and at DevGuru). However, JavaScript Kit correctly notes that the title property is "read/write in modern browsers", as we can see from the demo below:
Roll your mouse over these words to change the page title.
(The code for this is...ah, I'm sure that you can write it out by now.)
One might think that because status is a property of the window object, as was noted in Primer #4, then title would be a property of the window object; evidently not.
Like the title property, the document lastModified property, which "returns
Now, what about those last four properties - cookie, anchors, forms, and links? According to Joe, "examples of [these] would be above your heads at this point." I'm not so sure I agree...in any case, they still deserve some comment.
The cookie property of the document object is read/write. A document can use the document.cookie command to write a cookie to the user's hard disk or to retrieve the name/value information of cookies that have been set previously by (more precisely, are associated with) that same document. We will discuss the setting and retrieval of cookies in more detail in Script Tips #60-64.
Finally, the anchors, forms, and links properties of the document object represent built-in arrays of document body elements and they refer to these elements in JavaScript expressions. Much like the relationship between the Plugin object and the navigator object that we discussed in Blog Entry #12, Anchor, Form, and Link are again themselves JavaScript objects, with their own properties.
The anchors, forms, and links properties are a subset of a larger group of property/object arrays that are listed under "Document Collections" at IRT's document object page.
(Strangely, Joe does not bring up built-in arrays until Primer #26 - see the "Here's a little more on arrays:" subsection thereof. FWIW, the built-in frames array of the window object crops up in Joe's "So You Want To Change More Than One Frame, Huh?" tutorial.)
I do a lot of linking on this blog, so let's wrap up this entry with a couple of demos for the document links property.
(1) How many links does this page have? Roll your mouse over this sentence to find out.
The code for the demo sentence is:
<span style="color:brown;" onmouseover="window.alert('This page has ' + document.links.length + ' links.');">Roll your mouse over this sentence to find out.</span>
As you can deduce, length is a property that returns the size of the links array of the document. We'll see other uses of the length property in due course.
(2) Where does the first link on this page point to? Roll your mouse over this sentence to find out.
The code for the demo sentence is:
<span style="color:blue;" onmouseover="window.alert('The first link on this page points to: ' + document.links[0].href);">Roll your mouse over this sentence to find out.</span>
The 0 in square brackets is an index number for the referenced link as it appears in the flow of the document. Remembering that JavaScript begins counting at 0 (as noted in Blog Entry #6), the first link on the page is referenced as document.links[0], the second link is document.links[1], the third link is document.links[2], etc. In turn, href is a property that returns, in this case, the value of the href attribute of the <a> element that corresponds to the document's first Link object, i.e., the URL of the first link, as you would expect.
The document.location demo target anchor
Welcome to the document.location demo div.
Click here to return to the post's "The document location property... " paragraph.
Click here to return to the post's "The document location property... " paragraph.
In the previous entry, I complained that "there is no mention [in Primer #7] of the properties relating to text, image, and form elements". Of course, that doesn't mean that WE can't take a look at some of these properties, and we'll do that in the next post.
reptile7
- posted by A. Peak @ 7:26 PM
Actually, reptile7's JavaScript blog is powered by Café La Llave. ;-)