Using Events to Control Actions

  • Article
SharePoint Designer Developer Reference

Microsoft Office SharePoint Designer has two types of events: events that are raised from the application, and events that are raised from the page.

Application events

You can use the events for the application to control under what conditions a Web site is published; whether you want to save a page whenever the OnPageClose event is fired; and whether you want to set styles, fonts, or backgrounds whenever a new page is created.

Page events

In the Microsoft Internet Explorer DHTML object model, event handlers are created by using scripts for run time. However, in the Office SharePoint Designer object model, when you work with objects that correspond to elements in a page, you are programming with events that are compatible with Internet Explorer but that are used at design time. To program events for design time, you use the same method as you would use to raise application events. To illustrate, the following example catches the onclick event for a hyperlink in Office SharePoint Designer.

In the Visual Basic Editor, insert a class module and name it CatchOnClick. Add the following code to the class module.

Dim WithEvents eAnchor As AnchorElement
Dim WithEvents eDoc As DesignerDocument
Dim e As EventObject
Private Sub Class_Initialize()
Set eDoc = ActiveDocument
Set eAnchor = eDoc.links(0)
End Sub
Private Function eAnchor_onclick() As Boolean
Set e = eAnchor.Document.parentWindow.event
If (MsgBox("OnClick Event for " & e.srcElement.tagName & _
    " would you like to cancel the event bubbling?", _
    vbYesNo) = vbYes) Then
    e.cancelBubble = True
    e.returnValue = False
Else
    e.cancelBubble = False
    e.returnValue = True
End If
End Function
Private Function eDoc_onclick() As Boolean
MsgBox "OnClick event for the Document object"
End Function

Next add a standard module and add the following code.

Public e As CatchOnClick
Sub GetClick()
Set e = New CatchOnClick
End Sub

Note

To run the example, perform the following steps:

  • Create a new page and add a hyperlink to it.
  • Run the GetClick procedure to create a global instance of the CatchOnClick event handler class.
  • Click the hyperlink.

A prompt is displayed stating that the onclick event fired. The prompt also queries the user to determine whether the program should pass the event up the event chain. If Yes is chosen, the onclick event is passed up to the document object to be handled.

To control the object to which the event is passed, you must set both the cancelBubble and returnValue properties. The cancelBubble event works to cancel the event from going any farther up the event chain. Set the cancelBubble property of the EventObject to True when you don't want the onclick event to be passed up to the next level of onclick events; otherwise, set the cancelBubble property to False. For example, if you have an image that has an onclick event placed on a document, which also has an onclick event, you set the cancelBubble property for the EventObject object to True for the image, assuming that you don't want the onclick event to be passed up to the document onclick event.

You use the returnValue property to control the default action taken by Office SharePoint Designer when an event fires. Using the previous example of an image placed on a document, if the returnValue property for the EventObject for the image is set to False in the onclick event, the shortcut menu is disabled (because the right-click shortcut menu is the default action for the onclick event).