Microsoft Office 2000/Visual Basic Programmer's Guide   

Working with Objects and Collections

What does it mean to say that every element on a Web page is exposed as an object in the DHTML object model? In HTML code, an element is the portion of a page represented by an HTML tag. A page contains an object for each HTML tag or tag pair. A tag pair consists of the opening and closing tags for an element, such as <BODY> and </BODY>.

For example, in the following simple page, there are eight objects. These objects consist of the following element tags and the text they enclose: <HTML>, <HEAD>, <TITLE>, <BODY>, <CENTER>, <H1>, and <P>.

<HTML>
<HEAD>
   <TITLE>
      A Simple Page
   </TITLE>
</HEAD>
<BODY>
   <CENTER>
      <H1>
         This is the heading on a simple page.
      </H1>
   </CENTER>
   <P>
      This is the first paragraph on a simple page.
   </P>
   <P>
      This is the second paragraph on a simple page.
   </P>
</BODY>
</HTML>

Important   Some HTML tags, such as the <BR> tag or the <P> tag, work with or without a closing tag. However, if you want to use DHTML to work with the contents of an element, you should always use both the opening and the closing element tags and specify the ID attribute for the tag. For information about tags you can use to enclose items for the purpose of creating objects that you can work with through DHTML, see "Working with <DIV> and <SPAN> Tags" later in this chapter.

Collections in the DHTML object model are similar to collections of objects exposed by an Office application. You can retrieve an item from a collection by specifying its name or the index number that corresponds to the position of the item in the collection. Collection indexes are zero-based, so the first item in a collection always has an index number of zero.

In the DHTML object model, the document object represents the HTML page that is displayed in the browser or in a particular frame of a frameset. The document object exposes several collections that represent elements on a page, and one collection, called all, that represents all the objects on a page. This discussion covers only the all collection.

Note   When you create a data access page in Microsoft Access, the VBA DataAccessPage object representing the page has a Document property that returns the DHTML document object. You can use VBA to work with the HTML code in a data access page by accessing the DHTML object model for the page through this property. For more information about data access pages, see "Working with the Office Web Components" later in this chapter or see Chapter 5, "Working with Office Applications."

One difference between collections in the DHTML object model and collections in Office applications is the property you use to determine the total number of items in a collection. In VBA, you use a collection's Count property to determine the number of items in a collection. In DHTML, you use a collection's length property to determine the number of items in a collection. The following VBScript code displays a message box showing the number of objects in the Web page in which the script is run:

MsgBox "This page contains " & document.all.length & " DHTML objects."

A Web page can have multiple elements of the same type. For example, you might have a page with ten paragraphs of text where each paragraph is contained in a <P></P> tag pair. You can use the tags method of the all collection to return a subcollection of items of the same type. The tags method returns the members of the all collection that have the same tagName property value that is specified in the method's sTag argument. For example, the following VBScript code can be used to create a new collection of objects representing all the <P> objects on the current page. The sample code then specifies new text to appear in the third paragraph and underlines all the new text:

Dim colParagraphs
Dim objSinglePara

Set colParagraphs = document.all.tags("P")
Set objSinglePara = colParagraphs(2)
objSinglePara.innerText = "This is brand new text!"
objSinglePara.style.textDecoration = "underline"

When you know a page will contain objects that you want to manipulate from script, you can uniquely identify an object by using its id property. You can set the id property by specifying the ID attribute within the tag itself. The attribute for an element usually has a corresponding property in the DHTML object model. For example, all the following <P> elements within the body of the page are specifically identified by using the ID attribute:

<BODY>
   <CENTER>
      <H1>
         This is the heading on a simple page.
      </H1>
   </CENTER>
   <P ID="para1">
      This is the first paragraph on a simple page.
   </P>
   <P ID="para2">
      This is the second paragraph on a simple page.
   </P>
</BODY>

When you add a control to a page by using the toolbox for a data access page in Access or the toolbox in the Script Editor, a default ID attribute is added automatically. The following example shows the HTML element representing a command button that has been created by using the toolbox for a data access page:

<BUTTON ID=Command0 STYLE="HEIGHT: 0.57in; LEFT: 1in; POSITION: absolute; TOP: 0.31in; WIDTH: 3.06in" tabIndex=1 TITLE=Command0>Command0</BUTTON>

You can use the id property to return a reference to an object in the all collection. For example, the following VBScript procedure shows how to change the text associated with a particular element. The ChangeElementText procedure uses the id property specified by the strID argument to return a reference to the specified object:

' Call the ChangeElementText procedure.
ChangeElementText "para2", "I am the new text in the second paragraph."

Sub ChangeElementText(strID, strNewText)
   Dim objElement

   Set objElement = document.all(strID)
   If Len(objElement.innerText) > 0 Then
      objElement.innerText = strNewText
   End If
End Sub

You can see the ChangeElementText procedure work in an HTML page by opening the SimpleObjectReference.htm file in the ODETools\V9\Samples\OPG\Samples\CH12 subfolder on the Office 2000 Developer CD-ROM. The preceding example illustrates how to use a DHTML object's innerText property to work with the text associated with an object. If you use the same ID attribute for multiple tags, the all collection will return a collection of all elements that share the same ID attribute. For example, in a page where five elements all have an ID attribute of "MyElement", the following myObject variable will contain a collection of those five items:

myObject = document.all("MyElement")

When you have uniquely identified an object on a page by specifying its ID attribute, you can also directly refer to the element in script without going through the all collection. For example, the following two lines are equivalent for an element that has an ID attribute of "myElement":

MsgBox document.all("myElement").innerText
MsgBox myElement.innerText

For more information about working with the text or the HTML code associated with an object, see the following section, "Understanding Dynamic Content."

Capitalization of Object, Collection, Method, and Property Names in HTML Code

VBA objects, collections, methods, and properties use names that begin with a capital letter and use capitals for the first letter of concatenated names; for example, ActiveDocument and MoveNext.

DHTML objects, collections, methods, and properties always begin with a lowercase letter; for example, document, all, and setTimeout.