The Object Model | Programming Active Server Pages (Microsoft Programming Series)

Although many new features of Internet Explorer 4.0 are designed to enhance the user experience, improved browsing depends entirely on improved content. To that end, IE 4.0 provides a number of new features for content developers. Most of these features, including Dynamic HTML, are covered in later chapters of this book, but all content development depends on a strong understanding of the IE 4.0 architecture. This architecture takes the form of an object model.

The concept of constructing software from objects is certainly not new. Most of the applications that you know well—Microsoft Word, Microsoft Excel, Microsoft PowerPoint, and Internet Explorer—are constructed of objects. These applications are built from well-defined software modules that provide data through variables known as properties and provide services through function calls known as methods. Properties and methods perform useful functions for a piece of software. The collection of properties and methods that define an object is called an interface. An interface is invoked by a user through the toolbar and menus, but it can also be called directly by a programmer through code. In fact, virtually anything a user can do with an application can be done by a programmer who makes calls to the objects. This is an extremely powerful mechanism for manipulating applications that have rich object models, such as IE 4.0.

Microsoft's object models are based on a technology known as the Component Object Model (COM), a specification that defines how objects communicate for the purpose of sharing services. Sharing services gives object models power and flexibility.

Suppose you are building an application that requires the use of tabular data. Your application needs to store data in a flat table and perform arithmetic functions on that data. Sounds like a spreadsheet, right? Well, you could build your own spreadsheet, or you could borrow the services of an existing spreadsheet such as Excel. Excel has an object model, and because COM is the technology underlying Excel, the services provided by any Excel object can be shared with any application that knows how to implement COM. All of Microsoft's development tools know how to access COM objects, so you are free to call the functions of an Excel spreadsheet from code that you wrote in Microsoft Visual Basic, Visual C++, Visual J++, Visual InterDev, or Visual FoxPro. And that is an important key: COM is language independent.

Let's imagine that you want to use the services of the Excel spreadsheet from Visual InterDev. In order to access the object, you must first review the application's object model. A partial examination of Excel's large and complex object model reveals objects named Application, Workbook, and Worksheet. (See Figure 3-4.) These objects are arranged in hierarchical order in a "has a" type of relationship: the Excel Application "has a" Workbook, and a Workbook "has a" Worksheet.

Figure 3-4. Part of the Excel object model.

Once the object model is understood, you can programmatically access an object and its associated services. Accessing services is typically done by creating an instance of the object you need. An instance is a copy of the object that is created in memory and contains all of the functionality defined for the object and its services. In Visual InterDev, an instance of any COM object can be created by using the CreateObject method. The following code establishes a variable named MyWorksheet as a pointer to an instance of the COM object Worksheet contained in the application Excel:

Set MyWorksheet = Server.CreateObject("Excel.Worksheet")

Once this worksheet is created, all the services available through the object can be invoked from code. For example, a worksheet knows how to perform a spelling check on all the data contained in its cells. This service can be invoked using the CheckSpelling method. The following code does the job:

MyWorksheet.CheckSpelling

You might also find that additional objects exist under the current object. Worksheets have cells in them, so, not surprisingly, you can find a Cell object under the Worksheet object. Using the Cell object, you can access any cell in the worksheet. In fact, every cell in the worksheet is actually a member of the Cells collection. This collection allows easy access to any cell. The following code reads the value of cell A1 into a variable named MyData:

MyData = MyWorksheet.Cells(1, 1)

In a similar manner, all the objects in Internet Explorer are arranged hierarchically and are accessible from code. This code access could easily be written in a language such as Visual Basic (or any other language that supports COM). Visual InterDev, however, supports an additional access method: client-side scripting. Using languages such as VBScript or JavaScript, you can access any of the objects in IE 4.0 from script. This is a powerful technique that enables all of the client-side programming features discussed in this book.

As we continue through this book, we will add more and more capability to our Web pages by accessing the IE 4.0 object model. The complete model is shown in Figure 3-5 and provides a valuable reference. A complete object reference is also included on the CD-ROM that accompanies this book. But for now, let's take a look at some of the key objects found in the model and how to exploit them.

Window

As the top-level object in the Internet Explorer 4.0 hierarchy, the Window object represents the entire browser. When you address the Window object in script, you are directly manipulating IE 4.0. The Window object's properties, methods, and events (described in Appendix D) allow you to achieve interesting effects.

Figure 3-5. The IE 4.0 object model.

As an example of what is possible using the Window object, let's construct a sample that creates a status bar marquee, a special effect that rolls a text message across the browser status bar. (See Figure 3-6.) You can create this effect by using properties, methods, and events of the Window object.

Figure 3-6. A status bar marquee.

The Window object exposes several properties of the browser. One of these properties is Status, which allows you direct access to the text that appears on the status bar. The following code places a simple message in the status bar:

Window.Status = "Here is a message!"

Notice how the Window object is addressed directly in code. This syntax is used whenever you want to access the features of the object. Because Window is the main object in the hierarchy, it will also allow you to address its properties and methods implicitly—that is, without actually typing Window. Hence, the following code works just as well:

Status = "Here is a message!"

Making the text scroll is a simple matter of padding the message with spaces and reducing the number of spaces over time. In order to move the message, you need some sort of function with a periodic call that manages the position of the text in the status bar. A periodic function call can be made with the SetTimeout method of the Window object. SetTimeout allows you to specify a routine to call and a period of time to wait between calls. The timeout is identified by a variable you define. If you wanted, for example, to call a routine named Scroll every 100 milliseconds, you could write the following code:

Dim MyTimeout MyTimeout = SetTimeout("Scroll", 100)

Using the SetTimeout method and the Status property, you can set up a routine to scroll text across the status bar. The only question is when to start the scrolling. You need an event to trigger the scrolling routine. In this case, you want to begin scrolling as soon as the page finishes loading. You can detect when a page is fully rendered in the browser by using the OnLoad event of the Window object. OnLoad fires when the page is loaded, so you can use it to establish the initial call to SetTimeout. The following code makes it happen:

Public MyTimeout Sub Window_OnLoad()     MyTimeout = SetTimeout("Scroll", 100) End Sub

Note that the variable is declared Public, which makes it available to all the script in the page. This is important because you will use the variable in other routines.

Listing 3-1 shows how these pieces together—the OnLoad event, the Status property, and the SetTimeout method—create the status bar marquee.

Listing 3-1. The status bar marquee.

<HTML> <HEAD> <META NAME="GENERATOR" Content="Microsoft Developer Studio"> <META HTTP-EQUIV="Content-Type" content="text/html;     charset=iso-8859-1"> <TITLE>Status Bar Marquee</TITLE> <SCRIPT LANGUAGE="VBScript"> <!--          ` Script-level variables     Public strMessage     Public intSpaces     Public intTimeout one blank line within code     Sub Window_OnLoad()         ` Initialize the variables when the page is fully loaded         strMessage = "Check out this scrolling text!"         intSpaces = 100         intTimeout = Window.SetTimeout("Scroll", 100)     End Sub     Sub Scroll()         ` Call this routine every 100 milliseconds         Dim strTemp, i         ` Scroll right to left         intSpaces = intSpaces - 1         If intSpaces = 0 Then intSpaces = 100         ` Pad with spaces         For i = 1 to intSpaces             strTemp = strTemp & " "         Next         ` Write message         Window.Status = strTemp & strMessage         ` Reset timer         intTimeout = Window.SetTimeout("Scroll", 100)     End Sub --> </SCRIPT> </HEAD> <BODY> </BODY> </HTML>

This book contains examples that can be run properly only under Internet Explorer 4.0. The problem of cross-platform support has not gone away, and many of IE 4.0's new features simply exacerbate the problem. Therefore, you need a surefire methodology for identifying when your HTML is being run on IE 4.0. Fortunately, you can create a feature to examine the user agent string in a JavaScript function named Version. The user agent string is a special string that identifies the browser. User agent strings can be cryptic and quite confusing to humans, but if you know what to expect, they can be useful. Here is the user agent string for IE 4.0:

Mozilla/4.0 (compatible; MSIE 4.0; Windows 95)

This string can be parsed to retrieve the information that identifies the browser as an IE 4.0 browser. JavaScript is used to ensure support from the widest array of browsers. Listing 3-2 shows the function in action in a simple Web page.

Listing 3-2. Browser detection.

<HTML> <HEAD> <META NAME="GENERATOR" Content="Microsoft Developer Studio"> <META HTTP-EQUIV="Content-Type" content="text/html;     charset=iso-8859-1"> <TITLE>Browser Type</TITLE> <SCRIPT LANGUAGE=JavaScript> <!--     function browserType()     {         // Define new properties for the         // Window object, and assign them         // using the Version function         window.Version = Version();         if (window.Version >= 4) window.IE4 = true;         // Test the new properties here         if (window.IE4 == true)             alert("Congratulations! You are running IE 4.0!");         else             alert("Oh, no! Please get IE 4.0 now!");     }     function Version()     {         // Get the user agent string         var strAgent = window.navigator.userAgent;         var intIndex = strAgent.indexOf("MSIE ");         // Display the user agent string         alert(strAgent);         // Parse the string to find the version number         if (intIndex > 0)             return parseInt(strAgent.substring(intIndex + 5,                              strAgent.indexOf(".", intIndex)));         else             return 0;     } --> </SCRIPT> </HEAD> <BODY> <H1>Are you using IE 4.0?</H1><P> <FORM> <INPUT TYPE="BUTTON" VALUE="Find out!" Name="cmdBrowser" OnClick="var rtn=browserType();"> </FORM> </BODY> </HTML>

Location

The Location object provides information about the current Internet location. It allows you to retrieve the address of the current location through the HRef property or retrieve portions of the address through the properties Hash, Host, Hostname, Pathname, Port, Protocol, and Search.

Frames

The Frames collection allows access to all the frames in the browser. The collection provides a mechanism for programmatically manipulating one frame from script running in another frame. Normally, the collection is accessed using an index number that begins with zero, but you can access the windows by name if you have provided names for them. (When you provide names for windows, you should ensure that all windows have unique names since the Frames collection will return only the first window with the specified name.) The following code declares a set of frames and gives them names:

<FRAMESET COLS="27%,73%">     <FRAME SRC="/Demos/toolbar.htm" NAME="TOOLBAR" SCROLLING="Yes">     <FRAMESET ROWS="25%,75%">         <FRAME SRC="/Demos/banner.htm" NAME="BANNER" SCROLLING="No">         <FRAME SRC="/Demos/home.htm" NAME="MAIN" SCROLLING="Yes">     </FRAMESET>     <NOFRAMES>         <BODY BGCOLOR="FFFFFF">         <H3>Your browser does not support frames</H3><BR>         <H4>You're missing the show!!</H4><P>         Get the <A HREF="http://www.microsoft.com/ie/">Internet         Explorer</A>     </NOFRAMES> </FRAMESET>

Once the frames are defined inside a frame set, you can use the Frames collection to access any of the existing frames. In the preceding example, three frames were designated: Toolbar, Banner, and Main. Manipulating the Main window from the Toolbar window can be accomplished with the following code:

window.parent.frames("MAIN").navigate "http://www.microsoft.com"

Navigator

The Navigator object represents the entire browser. This object is useful in an environment where the browser is supporting multiple frames. A single-frame Web page has only one Window object, so the Window object and the browser can be considered one and the same. A multiple-frame Web page, however, has a separate Window object for each frame, so the only way to access the browser as a whole is through the Navigator object.

Event

The Event object supports all the events that occur in Internet Explorer. This object is extremely important in Dynamic HTML and is discussed in detail in Chapter 4.

Screen

The Screen object represents the client screen and returns information about its capabilities. Perhaps the most useful of the Screen properties are Height and Width, which return the screen resolution for the client in pixels. This information can then be used to accurately reposition elements on a Web page based on the screen resolution.

Document

The Document object represents the document currently loaded in the browser. It is perhaps the most important of all the objects in the hierarchy because it acts as the gateway to every aspect of the document, from the background color to each and every individual tag located in the document. In fact, Dynamic HTML relies heavily on accessing HTML tags through the Document object. (See Appendix D for a description of the object's properties, methods, and events.)

As a simple exercise, let's use the Document object to generate a fade-in effect that causes the browser background to gradually change from black to white. This is an interesting effect that adds some simple action to a page. (It also requires the use of the SetTimeout method of the Window object.)

The Document object gives you access to many of the HTML attributes that define the <BODY> tag. Using the BGColor property of the Document object, you can read and write to the BGCOLOR attribute, which takes as an argument the color for the page background in RGB format. This means that you must provide the color as six hexadecimal digits: the first two digits represent red, the second two represent green, and the last two represent blue. Black is 000000, and white is FFFFFF. The fade-in example will change the color from black to white over time using the SetTimeout method.

Changing the color is simple but has just one trick. You must be sure to properly format the BGColor property in code, or you will not get the intended results. Correct formatting is done with the VBScript Hex function, which takes a number as an argument and returns the hexadecimal equivalent as text. This is exactly what the BGColor property expects.

In the example, you define a variable for the background color, retrieve the existing color, and modify it. Let's say you just want to read the existing color and change it to white in only one step. The following code would work:

Dim lngBGColor lngBGCOLOR = Document.BGColor lngBGCOLOR = &HFFFFFF Document.BGColor = Hex(lngBGColor)

This reading and writing is simple enough and can be done at any time from script. In order to get the fade-in effect, you must increment the background color value periodically until the background is completely white. If the fade-in code is written as a separate routine, you can use SetTimeout to call the routine at regular intervals. Here is the code:

lngBGColor = lngBGColor + &H111111 Document.BGColor = lngBGColor

The complete code for the example is shown in Listing 3-3 and simply expands this idea.

Listing 3-3. The fade-in effect.

<HTML> <HEAD> <META NAME="GENERATOR" Content="Microsoft Developer Studio"> <META HTTP-EQUIV="Content-Type" content="text/html;     charset=iso-8859-1"> <TITLE>Fade-In</TITLE> <SCRIPT LANGUAGE="VBScript"> <!--     ` Color constants     Const ntsBGStart = &H0     Const ntsBGStep = &H111111     Const ntsBGEnd = &HFFFFFF     Const ntsTimerStep = 10     ` Variable for background color     Public lngBGColor     Sub Window_OnLoad()         ` Set timer         intTimeout = Window.SetTimeout("Fade", ntsTimerStep)         ` Initialize background color         lngBGColor = ntsBGStart         Document.BGColor = Hex(lngBGColor)     End Sub     Sub Fade()         ` Fade in         lngBGColor = lngBGColor + ntsBGStep         Document.BGColor = Hex(lngBGColor)         ` Keep going until white         If lngBGColor < ntsBGEnd Then             intTimeout = Window.SetTimeout("Fade", ntsTimerStep)         End If     End Sub --> </SCRIPT> </HEAD> <BODY> <CENTER><H1>Welcome to My Web Page!</H2></CENTER> </BODY> </HTML>