How to create a Smart Tag DLL in Visual Basic for use in Office XP (286267)

SUMMARY

Smart Tags are a technology introduced with Office XP that provide Office users more interactivity with the content of their Office documents. A Smart Tag is an element of text in an Office document that is recognized as having custom actions associated with it. An example of one of these special elements of text might be an e-mail name that is typed into a Word document or an Excel workbook. If the e-mail name is recognized as a Smart Tag, the user is presented with one or more actions to perform on the given text. Possible actions associated with an e-mail name are to look up additional contact information, or send a new e-mail message to that contact.

You can extend the capabilities of Office XP by developing your own Smart Tag Recognizer/Action dynamic-link library (DLL) for use in Office documents. This article describes how to build a Smart Tag DLL by using Visual Basic 6.0 and discusses what registry settings are required for Office XP to identify and use your Smart Tag DLL.

Note Excel 2002 and Word 2002 are the only Office XP applications that support Smart Tags. However, you can apply the information that is presented in this article to Smart Tag development for any application that adopts the Smart Tag technology.

A Smart Tag DLL is a standard Component Object Model (COM) DLL that implements two special interfaces: ISmartTagRecognizer and ISmartTagAction. The ISmartTagRecognizer interface is responsible for recognizing text that is typed into a document as a Smart Tag. The ISmartTagAction interface is responsible for performing actions on a particular Smart Tag string at the user's request. It is not required that these interfaces be implemented in the same DLL. You can have a recognizer DLL and one or more action DLLs that extend a single Smart Tag type for different actions.

Create the Smart Tag DLL in Visual Basic

The following steps create a simple Smart Tag DLL that recognizes the Microsoft Network (MSN) Instant Messenger contacts and gives the user the ability to send e-mail or instant messages to a recognized contact. Instant Messenger is required to use this sample. If you do not have Instant Messenger, you can obtain a copy from the following MSN Web site:

1. In Visual Basic, create a new ActiveX DLL project.
2. On the Project menu, click Project1 Properties. Change the project name to MessengerSmartTag, and then click OK.
3. On the Project menu, click References. Select the Microsoft Smart Tags 1.0 Type Library and the MSN Messenger 1.0 Type Library, and then click OK.
   
   Note If the specified type libraries are not listed, you can browse for them. The default location for the Microsoft Smart Tags 1.0 Type Library is C:\Program Files\Common Files\Microsoft Shared\Smart Tag\Mstag.tlb, and the default location for the MSN Messenger 1.0 Type Library is C:\Program Files\Messenger\Msmsgs.exe.
4. Change the name of Class1 to Action.
5. Paste the following code into the code window for the Action class:

   Private Declare Function ShellExecute Lib "shell32.dll" Alias _
     "ShellExecuteA" (ByVal hwnd As Long, ByVal lpOperation As String, _
     ByVal lpFile As String, ByVal lpParameters As String, _
     ByVal lpDirectory As String, ByVal nShowCmd As Long) As Long
   
   Implements ISmartTagAction
   
   Private Property Get ISmartTagAction_ProgId() As String
    ' Return the ProgID of the Action interface.
      ISmartTagAction_ProgId = "MessengerSmartTag.Action"
   End Property
   
   Private Property Get ISmartTagAction_Name(ByVal LocaleID As Long) As String
    ' Return a short name describing the Action.
      ISmartTagAction_Name = "Messenger Smart Tag"
   End Property
   
   Private Property Get ISmartTagAction_Desc(ByVal LocaleID As Long) As String
    ' Return a long description describing the action.
      ISmartTagAction_Desc = "Provides actions for the Messenger Smart Tag"
   End Property
   
   Private Property Get ISmartTagAction_SmartTagCount() As Long
    ' Return the number of Smart Tags this action supports.
      ISmartTagAction_SmartTagCount = 1
   End Property
   
   Private Property Get ISmartTagAction_SmartTagName( _
    ByVal SmartTagID As Long) As String
    ' This method is called the same number of times as you
    ' return in SmartTagCount. This method sets a unique name
    ' for the Smart Tag.
      ISmartTagAction_SmartTagName = "microsoft/messenger#contacts"
   End Property
   
   Private Property Get ISmartTagAction_SmartTagCaption( _
    ByVal SmartTagID As Long, ByVal LocaleID As Long) As String
    ' This caption is displayed on the menu for the Smart Tag.
      ISmartTagAction_SmartTagCaption = "Messenger Smart Tag"
   End Property
   
   Private Property Get ISmartTagAction_VerbCount( _
    ByVal SmartTagName As String) As Long
    ' Return the number of verbs we support.
      If (SmartTagName = "microsoft/messenger#contacts") Then
        ISmartTagAction_VerbCount = 2
      End If
   End Property
   
   Private Property Get ISmartTagAction_VerbID( _
    ByVal SmartTagName As String, ByVal VerbIndex As Long) As Long
    ' Return a unique ID for each verb we support.
      ISmartTagAction_VerbID = VerbIndex
   End Property
   
   Private Property Get ISmartTagAction_VerbCaptionFromID( _
    ByVal VerbID As Long, ByVal ApplicationName As String, _
    ByVal LocaleID As Long) As String
    ' Get a caption for each verb. This caption is displayed
    ' on the Smart Tag menu.
      Select Case VerbID
        Case 1
          ISmartTagAction_VerbCaptionFromID = _
              "Send this contact an Instant Message"
        Case 2
          ISmartTagAction_VerbCaptionFromID = _
              "Send email to this contact"
      End Select
   End Property
   
   Private Property Get ISmartTagAction_VerbNameFromID( _
    ByVal VerbID As Long) As String
    ' Return a string name for each verb.
      Select Case VerbID
        Case 1
          ISmartTagAction_VerbNameFromID = "SendInstantMessage"
        Case 2
          ISmartTagAction_VerbNameFromID = "SendEmail"
      End Select
   End Property
   
   Private Sub ISmartTagAction_InvokeVerb(ByVal VerbID As Long, _
    ByVal ApplicationName As String, ByVal Target As Object, _
    ByVal Properties As SmartTagLib.ISmartTagProperties, _
    ByVal Text As String, ByVal Xml As String)
    ' This method is called when a user invokes a verb
    ' from the Smart Tag menu.
      Dim oMessenger As Messenger.IMessengerApp2
      Dim oMsgrObj As Messenger.MsgrObject
      Dim oUsers As Messenger.IMsgrUsers
      Dim oUser As Messenger.IMsgrUser
      Dim i As Integer
       
    ' Create an instance of Instant Messenger.
      Set oMessenger = CreateObject("Messenger.MessengerApp")
      Set oMsgrObj = CreateObject("Messenger.MsgrObject")
    ' Get a list of contacts.
      Set oUsers = oMsgrObj.List(0)
    ' Loop through the contacts.
      For i = 0 To oUsers.Count - 1
       ' Set a specific contact.
         Set oUser = oUsers(i)
       ' Check to see if the contact is the correct one.
         If LCase(oUser.FriendlyName) = LCase(Text) Then
            Select Case VerbID
              Case 1
               ' The user wants to display the Instant Message
               ' box to send the contact a message.
                 oMessenger.LaunchIMUI oUser
              Case 2
               ' Shell the "mailto" protocol to start the
               ' user's mail program and create a new message.
                 ShellExecute 0&, "open", "mailto:" & oUser.EmailAddress, _
                      vbNullString, vbNullString, 1
            End Select
         End If
      Next
   End Sub
   					

6. Add a new class to the project, and change the class name to Recognize. Paste the following code in the code window for the Recognize class:

   Implements ISmartTagRecognizer
   
   Dim Contacts() As String
   
   Private Sub Class_Initialize()
       Dim oMsgrObj As Object
       Dim oUsers As Object
       Dim oUser As Object
       Dim i As Integer
       
     ' Create an instance of Instant Messenger.
       Set oMsgrObj = CreateObject("Messenger.MsgrObject")
     ' Get a list of contacts.
       Set oUsers = oMsgrObj.List(0)
     ' Loop through the contacts.
       For i = 0 To oUsers.Count - 1
       ' Set the user.
         Set oUser = oUsers(i)
       ' Redimension the array for the new contact.
         ReDim Preserve Contacts(i)
       ' Add the user to the contacts list (in lower case).
         Contacts(i) = LCase(oUser.FriendlyName)
       Next
    End Sub
   
   Private Property Get ISmartTagRecognizer_ProgId() As String
    ' Return the ProgID of the Recognizer interface.
      ISmartTagRecognizer_ProgId = "MessengerSmartTag.Recognizer"
   End Property
   
   Private Property Get ISmartTagRecognizer_Name(ByVal LocaleID As Long) As String
    ' Return a short title about your recognizer.
      ISmartTagRecognizer_Name = _
         "Microsoft Messenger Contacts Visual Basic Recognizer"
   End Property
   
   Private Property Get ISmartTagRecognizer_Desc(ByVal LocaleID As Long) As String
    ' Return a long description of your recognizer.
      ISmartTagRecognizer_Desc = _
         "Microsoft Messenger recognizes your Instant Messenger Contacts"
   End Property
   
   Private Property Get ISmartTagRecognizer_SmartTagCount() As Long
    ' Return the number of Smart Tags that you support.
      ISmartTagRecognizer_SmartTagCount = 1
   End Property
   
   Private Property Get ISmartTagRecognizer_SmartTagName( _
    ByVal SmartTagID As Long) As String
    ' This method is called the same number of times as you
    ' return in SmartTagCount. This method sets a unique name
    ' for the Smart Tag.
      ISmartTagRecognizer_SmartTagName = "microsoft/messenger#contacts"
   End Property
   
   Private Property Get ISmartTagRecognizer_SmartTagDownloadURL( _
    ByVal SmartTagID As Long) As String
    ' Return the URL that gets embedded in documents.
      ISmartTagRecognizer_SmartTagDownloadURL = nil
   End Property
   
   Public Sub ISmartTagRecognizer_Recognize(ByVal Text As String, _
    ByVal DataType As SmartTagLib.IF_TYPE, ByVal LocaleID As Long, _
    ByVal RecognizerSite As SmartTagLib.ISmartTagRecognizerSite)
    ' The Recognize method is called and passed a text value.
    ' You should recognize strings in the text and set up the actions.
      Dim i As Integer
      Dim startpos As Integer
      Dim strlen As Integer
      Dim propbag As SmartTagLib.ISmartTagProperties
       
    ' Convert the text to lower case.
      Text = LCase(Text)
    ' Loop through all contacts.
      For i = 0 To UBound(Contacts)
       ' Look for a contact name in the text.
         startpos = InStr(Text, Contacts(i))
       ' Find the length of the contact name.
         strlen = Len(Contacts(i))
       ' Look for all occurrences of contacts in the string
         While (startpos > 0)
          ' Create a new property bag.
            Set propbag = RecognizerSite.GetNewPropertyBag
          ' Commit the Smart Tag to the property bag.
            RecognizerSite.CommitSmartTag "microsoft/messenger#contacts", _
                     startpos, strlen, propbag
         ' Continue looking for contacts in the string.
            startpos = InStr(startpos + strlen, Text, Contacts(i))
         Wend
      Next i
   End Sub
   					

7. Compile and build the DLL.

Register the Smart Tag DLL

Warning Serious problems might occur if you modify the registry incorrectly by using Registry Editor or by using another method. These problems might require that you reinstall your operating system. Microsoft cannot guarantee that these problems can be solved. Modify the registry at your own risk.

Before you can use any Smart Tag DLL, it must be registered on the system. Normal COM registration is done for you when you compile the project, distribute the DLL with the Package and Deployment Wizard, or call Regsvr32.exe with the DLL name. You must create additional registry entries that are not part of normal COM registration so that Office applications can identify the DLL as a Smart Tag DLL. To do this, follow these steps:

1. From a command line, start Regedit.exe.
2. Locate the following key in the registry:

   HKEY_CURRENT_USER\Software\Microsoft\Office\Common\Smart Tag\Actions

3. Add a new subkey named MessengerSmartTag.Action.
4. Locate the following key in the registry:

   HKEY_CURRENT_USER\Software\Microsoft\Office\Common\Smart Tag\Recognizers

5. Add a new subkey named MessengerSmartTag.Recognize.
6. Close the Registry Editor.

Test the Smart Tag DLL

Smart Tags obey the same security model as macros. If the security settings of the application are set to High, the Smart Tag DLL will not load unless the DLL is digitally signed (as do VBA macros). For more information on digital signing, see the "References" section.

To test the custom Smart Tag Recognizer/Action DLL in Word, follow these steps:

1. Start Instant Messenger, and log on.
   
   Note The sample Smart Tag requires that you log on to Instant Messenger. If you are not logged on to Instant Messenger, the custom DLL loads but does not recognize any contacts.
2. Start Word 2002. On the Tools menu, point to Macro, and then click Security. Set the macro security to Medium, and then click OK. If the macro security setting was previously set to High, restart Word.
3. Type the friendly name of a contact in a new document (for example, John Smith), and then press ENTER. A faint line appears beneath the friendly name to indicate that it is recognized as a Smart Tag. Move the mouse over the friendly name, and the Smart Tag Action button appears.
4. Click the Smart Tag button, and select one of the custom action items from the drop-down menu. You can send an e-mail or instant message to the contact from your new document.

You can use similar steps to test the Smart Tag DLL in Excel 2002.

Troubleshooting

If you have problems getting your custom Smart Tags to work, first check that the custom Smart Tag DLL is being loaded. In Word or Excel, on the Tools menu, click Auto Correct Options, click the Smart Tag tab, and ensure that the Label Text with Smart Tags check box is selected and that your Smart Tag DLL is listed and selected. If your Smart Tag is not listed, it may not be properly registered.

If the execution of the custom Recognizer or Action class is the source of the problem, you can debug a Smart Tag DLL as you would any Visual Basic COM DLL. Run the DLL from the Visual Basic Integrated Development Environment (IDE), and click Wait for components to be created if you are prompted for a debug method. Set a breakpoint in the Initialize event for the class item that you want to debug. When Excel or Word starts and loads the Smart Tag, your code breaks at the breakpoint, and you can step through the code for debugging.

Your Smart Tag DLL should trap and handle any run-time errors. If a Visual Basic error is raised in your code and the error is not handled, Office immediately unloads the DLL and clears the item so that it is not loaded again. This behavior is identical to the way that Office treats COM Add-Ins and can give you the impression that Office is not loading the DLL when it is in fact doing so but was forced to unload it because of an unhandled run-time error.