Microsoft Office 2000/Visual Basic Programmer's Guide

Understanding Events

An event is something that happens in response to an action, such as clicking a button or moving the mouse. In a Web page, an event handler is a script procedure that runs in response to an event. If you have used VBA, you are probably very familiar with the concept of events and event handlers. This section introduces you to events in the DHTML object model and gives a brief overview of how to work with them by using script in a Web page.

To write script that responds to events in a Web page, you can write an event handler for an object in the page, or you can take advantage of event bubbling in DHTML to create a global event handler. The DHTML object model exposes an event object that has a srcElement property that you can use to return the object that triggered an event. In addition, when an event occurs in a Web page, the VBScript me property returns a reference to the object in which the event occurred. When an event occurs in an object on a Web page, the event will "bubble up" through each parent object until it reaches the document object.

Here's how event bubbling works: Everything you see on a Web page displayed in a browser is part of the document object. Therefore, any object on the page is a child object of, at least, the document object. You can have objects nested several levels deep. For example, in the following HTML code, there is a word1 word object nested in a sent2 sentence object, which is nested in a para1 paragraph object, which is nested in the body object, which is nested in the document object. The HTML code has been formatted to make it easier to identify the nested levels in this page:

<BODY ID=body>
<H2>Office Programmer's Guide Chapter 12:
<BR> Using Web Technologies
</H2>
<HR>
<P ID=para1>
   <SPAN ID=sent1>
      This is text in the first paragraph on this page.
   </SPAN> 
   <SPAN ID=sent2>
      This sentence is itself an object on this page and 
      it contains this 
      <SPAN ID=word1>
         <B>word</B>,
      </SPAN>
      which is also an object on this page.
   </SPAN>
</P>
</BODY>

If a user viewing this page in a browser clicked the word1 object, a click event would occur for that object. If that event is not handled, or the event is handled but the event object's cancelBubble property is not set to True, that event will continue to bubble up through every parent object until it reaches the document object level. In the HTML code shown above, an uncancelled click event would bubble up to the document object through the following sequence of events:

word1 onclick »» sent2 onclick »» para1 onclick »» body onclick »» document onclick

For an example of a page that illustrates event bubbling and how to handle or cancel the bubbling of the click event at any level, see the EventBubbling.htm file in the ODETools\V9\Samples\OPG\Samples\CH12 subfolder on the Office 2000 Developer CD-ROM.

The EventBubbling.htm file also illustrates several of the other properties discussed in this section. It shows how to use the VBScript me property to identify an object on a page, and it shows how to use the srcElement property of the event object to identify the object that is the source of an event in a document-level global event handler. It also shows how to use the event object's cancelBubble property to prevent an event from bubbling up further through a document.

There are three ways to tie an event procedure directly to an object on a Web page:

The most common method is to create a subroutine within a script block by using the form Sub objectid_oneventname(). For example, the following code from the EventBubbling.htm file shows the word1 object's click event procedure:
```
<SCRIPT LANGUAGE = VBScript>

</SCRIPT>
```
If, instead of using the click event, you want to write script to run when the mouse pointer moves over an object on a page, you could create the following mouseOver event procedure for an object with an id property value of menuItem:
```
Sub menuItem_onmouseOver()
   ' Add VBScript code for mouseOver event here.
End Sub
```
A second way to create an event procedure for an object is to use the For and Event keywords within the <SCRIPT> tag itself. For example, here is another way to create a script block to run code for the onclick event of the word1 object shown earlier:
```
<SCRIPT LANGUAGE = VBScript For=word1 Event=onclick>

</SCRIPT>
```
The disadvantage to using this technique is that you must create separate <SCRIPT> tag blocks for each event procedure you want in the page. If you use the first technique illustrated earlier with the menuItem object's mouseOver event procedure, you can add as many event procedures as you want inside a single <SCRIPT> tag block.
Note You must use this technique when you are using VBScript code to create event handlers in data access pages. In addition, if you are adding VBScript code to an existing Web page, you also need to insert the following <META> tag at the top of the page:
```
<META Name=VBSForEventHandlers Value=True>
```
A third way to create an event procedure for an object is to call a custom procedure directly from an object's element tag. For example, if in the mouseOver event you were only going to call the MyCustomFunction procedure, you could do it in one of two ways. You could create the menuItem_onmouseOver() event procedure as shown earlier and then call MyCustomFunction from that procedure, or you could include the event as an attribute of the object's element tag and indicate that you want to call the MyCustomFunction procedure. For example:
```
<SPAN ID=menuItem onmouseOver="MyCustomFunction()">
Menu Item One
</SPAN>
```

To see a simple example that uses all three methods discussed here to handle the onclick event for an object, see the ClickTest.htm file in the ODETools\V9\Samples\OPG\Samples\CH12 subfolder on the Office 2000 Developer CD-ROM.

For examples of pages that use both specific event handlers and a global event handler that takes advantage of the srcElement property, see the EventBubbling.htm, RollOverSample.htm, and DataSourceControl.htm files (or any of the many sample files discussed later in this chapter in "Working with the Office Web Components") in the ODETools\V9\Samples\OPG\Samples\CH12 subfolder on the Office 2000 Developer CD-ROM.

For more information about working with the DHTML object model, see the C:\Program Files\Microsoft Visual Studio\Common\IDE\IDE98\MSE\1033\Htmlref.chm file.

Note The path to the Htmlref.chm Help file reflects the language ID folder (1033) for U.S. English language support in Office. The language ID folder below C:\Program Files\Microsoft Visual Studio\Common\IDE\IDE98\MSE differs for each language.